Skip to main content
POST
/
channel-api
/
messages
/
send
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:
FormatoExemploQuando 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
Um array simples no lugar do objeto ("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
            }
          ]
        }
      }
    }
  ]
}
Valores monetários usam o menor valor da moeda com 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

Hoje o envio de mídia exige o conteúdo em 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

​
x-channel-api-key
string
header
required

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

application/json
​
contact
object
required
​
message
object
required

Mensagem a ser enviada. O objeto correspondente ao type escolhido (text, template ou media) é obrigatório.

​
flowId
string

Identificador opcional de fluxo para correlação externa.

Example:

"flow-123"

​
closeConversation
boolean
default:false

Se true, encerra a conversa aberta do contato nesse canal antes de enviar a nova mensagem.

​
metadata
object

Metadados livres de correlação externa (chave/valor em string). Ficam registrados no log da requisição.

Example:
{ "erpInvoiceId": "123456" }

Response

Mensagem enfileirada com sucesso.

​
requestId
string<uuid>
required

Identificador único da requisição, usado para correlação nos logs da aba API do canal.

Example:

"3f2b4c1e-8a9d-4e2f-b1c3-9d8e7f6a5b4c"