Criar template
Cria um template de mensagem reutilizável na conexão: um corpo de texto com variáveis {{nome}} e, se quiser, uma mídia. Depois, envie pelo nome com POST /connections/{id}/send, passando template e os valores em variables. Escopo necessário: templates:write.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador da conexão (o número).
Corpo da requisição
namestringobrigatórioNome do template, único na conexão: letras sem acento, números, _ e -. É guardado em minúsculas.
bodystringobrigatórioTexto da mensagem, com variáveis no formato {{nome}}. Não pode ficar vazio nem só com espaços.
mediaobjectMídia enviada junto com o texto, a partir de uma URL https pública. Opcional.
media.typestringobrigatórioTipo da mídia: image, video, audio, document ou sticker.
"image", "video", "audio", "document", "sticker"media.urlstring · uriobrigatórioURL https pública do arquivo, baixada no momento de cada envio. Uma URL que não é https, que traz usuário e senha ou que aponta para um endereço privado ou interno é recusada já aqui, com 400.
media.captionstringLegenda. Pode usar as mesmas {{variáveis}} do corpo: no envio, elas são substituídas pelos valores de variables, e uma variável que só aparece na legenda e não veio vira texto vazio.
media.fileNamestringNome do arquivo, como o destinatário vê.
media.mimetypestringTipo MIME do arquivo (por exemplo, application/pdf). Obrigatório quando type é document.
media.pttbooleanAceito para manter o mesmo formato do envio, mas o template não guarda este campo: o áudio de um template sai como arquivo de áudio, não como mensagem de voz.
media.gifPlaybackbooleanAceito para manter o mesmo formato do envio, mas o template não guarda este campo: o vídeo de um template sai como vídeo comum.
Respostas
| Código | Erro e descrição |
|---|---|
| 201 | O template criado: id, connectionId, name (em minúsculas), body, media (quando há mídia), createdAt e updatedAt. |
| 400 | O nome tem caracteres fora de letras, números, _ e -, o corpo está vazio ou só com espaços, ou a URL da mídia é recusada (Media URL must not carry credentials, Media URL points to a non-public address), ou a mídia é um document sem mimetype (media.mimetype is required for documents). error diz qual foi. |
| 400 | FST_ERR_VALIDATIONO corpo (por exemplo, sem name ou sem body, media sem type ou sem url, um type fora da lista, ou media.url que não começa com https://) ou o id da conexão não segue o schema da operação; message diz o que está errado. |
| 401 | Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}. |
| 403 | A chave não tem o escopo templates:write; a mensagem cita o escopo (This credential lacks the templates:write scope). |
| 404 | A conexão não existe ou não é de quem chama (Connection not found): o recurso de outra pessoa responde exatamente como um que não existe. |
| 409 | A conexão já tem um template com esse nome, sem diferenciar maiúsculas de minúsculas (Template with this name already exists). Para mudar um template existente, use PUT /connections/{id}/templates/{name}. |
| 429 | Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After |
Detalhes
Cada template pertence a uma conexão (o número): outra conexão não enxerga os templates desta. Excluir a conexão exclui os templates dela.
O nome aceita só letras sem acento, números, _ e -, e é guardado em minúsculas: Confirmacao_Consulta vira confirmacao_consulta. Ele é único na conexão, sem diferenciar maiúsculas de minúsculas, e não muda depois: para renomear, crie um template novo e exclua o antigo.
Uma variável é {{ + um nome que começa com letra ou _ e continua com letras, números ou _ + }}. No envio, toda variável do corpo é obrigatória: faltando alguma em variables, o envio responde 400 com a lista em missingVariables. Veja Enviar mensagens.
Guia: Enviar mensagens