Skip to main content

​
O fluxo principal (visão geral)

  1. Ter um template pronto (painel ou API) com conteúdo por canal.
  2. Chamar POST /v1/templates/send com template (id ou nome), channels, to e variables.
  3. Receber 202 com IDs por canal e acompanhar entrega pelos webhooks ou APIs de cada canal.
A API pode enriquecer destinos (ex.: achar e-mail pelo telefone do contato) quando os dados existem na base.

​
Pré-requisitos

  • API Key com escopos conforme os canais que for usar: whatsapp:send, sms:send, email:send.
  • Template já criado no painel ou pela API v1 (POST /v1/templates com escopo templates:create), com conteúdo e variáveis definidos para os canais desejados.
  • Para WhatsApp: instância ativa e, se não houver instância padrão no workspace, envie instanceId no body.
  • Para E-mail: domínio verificado e, se não houver domínio padrão, envie from no body.
Envie a API Key em toda requisição:
  • Header: Authorization: Bearer sk_live_xxxxx
  • ou Header: x-api-key: sk_live_xxxxx

​
1. Enviar por template

Use o ID ou o nome do template, os canais desejados e a lista de destinatários. Passe as variáveis exigidas pelo template em variables. Request 
POST /v1/templates/send
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "template": "boas_vindas",
  "channels": ["whatsapp", "email"],
  "to": [
    "5511999999999",
    "joao.silva@email.com",
    "5521988888888"
  ],
  "variables": {
    "nome": "João da Silva",
    "1": "https://meusite.com/ativar"
  },
  "instanceId": "cuid_da_instancia_aqui",
  "from": "ola@meudominio.com.br",
  "fromName": "Equipe Notifique"
}
Response (202 Accepted) 
{
  "success": true,
  "data": {
    "messageIds": ["clxx...", "clxx..."],
    "emailIds": ["clxx..."],
    "status": "QUEUED",
    "count": 3
  }
}

​
2. Campos do body

CampoObrigatórioDescrição
templateSimID (cuid) ou nome do template.
channelsSimArray com um ou mais de: whatsapp, sms, email.
toSimAté 100 destinatários (telefones E.164 e/ou e-mails). Se um canal precisar de telefone ou e-mail que você não passou, a API tenta completar buscando o contato no workspace (por telefone ou e-mail) e usando o outro campo do contato.
variablesConforme templateObjeto chave-valor para substituir no conteúdo.
instanceIdSe WhatsApp sem defaultID da instância de WhatsApp.
fromSe E-mail sem defaultE-mail de origem (remetente).
fromNameNãoNome de exibição do remetente (e-mail).

​
3. Respostas de erro

O formato é o mesmo das APIs SMS, E-mail, WhatsApp e Push: camelCase e corpo unificado. Body de erro (exemplo 400): 
{
  "success": false,
  "error": "Bad Request",
  "message": "Missing required template variables",
  "details": [{ "field": "variables", "message": "Missing variable: nome" }],
  "missingVariables": ["nome"]
}
Campos possíveis: success (false), error, message, code (opcional), details (array de { field, message }), missingVariables (apenas em 400 por variáveis faltando). Consulte a página Respostas de erro para a lista completa de códigos HTTP e códigos code. Resumo rápido:
  • 400 — Validação: variáveis faltando (missingVariables), from/instanceId obrigatório não informado, domínio não verificado, SMS com texto final menor que 9 caracteres (SMS_MESSAGE_TOO_SHORT).
  • 401 — API Key ausente ou inválida.
  • 402 — Workspace bloqueado, saldo/créditos insuficientes ou limite da API Key (WORKSPACE_BLOCKED, INSUFFICIENT_CREDITS*, API_KEY_SPEND_LIMIT_EXCEEDED).
  • 403 — Escopo insuficiente ou créditos/plano (INSUFFICIENT_CREDITS, PLAN_LIMIT_CREDITS).
  • 404 — Template ou instância não encontrados.
  • 409 — SMS duplicado (code: SMS_DUPLICATE_RECENT).
  • 503 — Serviço de e-mail não configurado ou instância WhatsApp indisponível.

​
Resumo do fluxo

  1. Crie o template no painel ou com POST /v1/templates (escopos templates:create / templates:update) — mesmo contrato validado no painel. Use {{name}} para nome do contato; campos personalizados usam a chave técnica definida em Contatos. Veja Variáveis do contato e CRUD.
  2. Chame POST /v1/templates/send com template, channels, to e variables (e instanceId/from quando necessário).
  3. Use a resposta 202 com messageIds, smsIds, emailIds para acompanhar status nos endpoints e webhooks de cada canal.