Pular para o conteúdo

Criar template

POST/connections/{id}/templates

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.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número).

Corpo da requisição

namestringobrigatório

Nome do template, único na conexão: letras sem acento, números, _ e -. É guardado em minúsculas.

bodystringobrigatório

Texto da mensagem, com variáveis no formato {{nome}}. Não pode ficar vazio nem só com espaços.

mediaobject

Mídia enviada junto com o texto, a partir de uma URL https pública. Opcional.

media.typestringobrigatório

Tipo da mídia: image, video, audio, document ou sticker.

Valores: "image", "video", "audio", "document", "sticker"
media.urlstring · uriobrigatório

URL 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.

formato `^https://`
media.captionstring

Legenda. 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.fileNamestring

Nome do arquivo, como o destinatário vê.

media.mimetypestring

Tipo MIME do arquivo (por exemplo, application/pdf). Obrigatório quando type é document.

media.pttboolean

Aceito 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.gifPlaybackboolean

Aceito 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

Respostas: código de status, erro e descrição
CódigoErro e descrição
201O template criado: id, connectionId, name (em minúsculas), body, media (quando há mídia), createdAt e updatedAt.
400O 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.
400FST_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.
401Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}.
403A chave não tem o escopo templates:write; a mensagem cita o escopo (This credential lacks the templates:write scope).
404A 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.
409A 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}.
429Requisiçõ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

Esta página ajudou? · Atualizado em 28 set 2026