curl --request POST \
--url https://{host}/channel-api/messages/send \
--header 'Content-Type: application/json' \
--header 'x-channel-api-key: <api-key>' \
--data '
{
"contact": {
"value": "554396647639",
"name": "Cliente"
},
"message": {
"type": "text",
"text": {
"value": "Olá! Sua fatura foi gerada."
}
},
"metadata": {
"erpInvoiceId": "123456"
}
}
'{
"requestId": "3f2b4c1e-8a9d-4e2f-b1c3-9d8e7f6a5b4c"
}{
"statusCode": 400,
"message": "Base64 payload is required",
"error": "Bad Request"
}{
"statusCode": 404,
"message": "Invalid API token",
"error": "Not Found"
}Enviar mensagem
Enfileira o envio de uma mensagem de texto, template ou mídia pelo canal associado à chave de API. O envio é assíncrono: a resposta retorna imediatamente um requestId para correlação, e o processamento acontece em background. O status de cada envio pode ser acompanhado nos logs da aba API do canal.
curl --request POST \
--url https://{host}/channel-api/messages/send \
--header 'Content-Type: application/json' \
--header 'x-channel-api-key: <api-key>' \
--data '
{
"contact": {
"value": "554396647639",
"name": "Cliente"
},
"message": {
"type": "text",
"text": {
"value": "Olá! Sua fatura foi gerada."
}
},
"metadata": {
"erpInvoiceId": "123456"
}
}
'{
"requestId": "3f2b4c1e-8a9d-4e2f-b1c3-9d8e7f6a5b4c"
}{
"statusCode": 400,
"message": "Base64 payload is required",
"error": "Bad Request"
}{
"statusCode": 404,
"message": "Invalid API token",
"error": "Not Found"
}Variáveis de template
As variáveis (template.variables) são agrupadas por componente (header, body, buttons). Cada item aceita três formatos:
| Formato | Exemplo | Quando usar |
|---|---|---|
| String posicional | "R$ 500,00" | Placeholders numerados ({{1}}, {{2}}…) na ordem |
Objeto com key | { "key": "valor_fatura", "value": "R$ 500,00" } | Templates da Meta com variáveis nomeadas |
Objeto com correlationId | { "correlationId": 0, "value": "R$ 500,00" } | Formato legado por posição |
"variables": ["R$ 500,00"]) também é aceito e tratado como body (formato legado).
Botão order_details (Pix)
template.buttons serve para botões especiais montados pelo backend — hoje apenas order_details (cobrança Pix via WhatsApp):
{
"buttons": [
{
"index": 0,
"type": "order_details",
"orderDetails": {
"referenceId": "boleto-123456-20260402",
"type": "digital-goods",
"paymentType": "br",
"currency": "BRL",
"totalAmount": { "value": 50000, "offset": 100 },
"paymentSettings": [
{
"type": "pix_dynamic_code",
"pixDynamicCode": {
"code": "00020101021226700014br.gov.bcb.pix...",
"merchantName": "Zazz Internet",
"key": "39580525000189",
"keyType": "CNPJ"
}
}
],
"order": {
"status": "pending",
"subtotal": { "value": 50000, "offset": 100 },
"items": [
{
"retailerId": "1234567",
"name": "Mensalidade",
"amount": { "value": 50000, "offset": 100 },
"quantity": 1
}
]
}
}
}
]
}
offset decimal: { "value": 50000, "offset": 100 } = R$ 500,00. O campo value também aceita string decimal de ERP (ex.: "129,90"), convertida automaticamente usando o offset. Placeholders textuais de botão continuam em variables.buttons.Mídia
base64 (sem prefixo data:). O campo mediaUrl existe no schema, mas ainda não é aceito no processamento — requisições de mídia sem base64 retornam 400 Base64 payload is required.Authorizations
Chave de API do canal, gerada na aba API das configurações do canal (Dashboard → Suporte → Canais). A chave é exibida uma única vez ao ser gerada; gerar uma nova invalida a anterior.
Body
Show child attributes
Show child attributes
Mensagem a ser enviada. O objeto correspondente ao type escolhido (text, template ou media) é obrigatório.
Show child attributes
Show child attributes
Identificador opcional de fluxo para correlação externa.
"flow-123"
Se true, encerra a conversa aberta do contato nesse canal antes de enviar a nova mensagem.
Metadados livres de correlação externa (chave/valor em string). Ficam registrados no log da requisição.
Show child attributes
Show child attributes
{ "erpInvoiceId": "123456" }
Response
Mensagem enfileirada com sucesso.
Identificador único da requisição, usado para correlação nos logs da aba API do canal.
"3f2b4c1e-8a9d-4e2f-b1c3-9d8e7f6a5b4c"