API WhatsApp

1. Visão geral

A API Central Inteligencialy conecta o WhatsApp dos clientes do seu sistema à plataforma oficial da Meta (WhatsApp Cloud API). Com ela, o seu sistema:

• conecta o número de WhatsApp de um cliente em poucos cliques, pela tela oficial da Meta;
• lê as conversas e mensagens desse número;
• responde mensagens de texto dentro da janela de atendimento de 24 horas;
• envia templates (mensagens pré-aprovadas pela Meta), inclusive para quem ainda não escreveu.

A comunicação é sempre servidor a servidor: o seu backend chama a API. O navegador e o aplicativo do seu cliente nunca falam com ela diretamente, com uma única exceção descrita na seção 5: a tela da Meta devolve o navegador para a API ao final da conexão.

Conceitos

Endereço e formato

• Endereço base: https://api.inteligencialy.com (sem prefixo /api). Use sempre https://: chamadas em http:// são redirecionadas, e nesse redirecionamento um POST pode chegar como GET.
• Corpo e resposta em JSON, UTF-8. Envie Content-Type: application/json e Accept: application/json.
• Datas em ISO 8601 (ex.: 2026-09-23T14:30:00+00:00).
• Identificadores (connection_id, onboarding_id, conversation_id) são UUIDs.

2. Antes de começar

Combine com a Inteligencialy:

1. Credencial de acesso. Um token no formato intely_live_…, entregue por canal seguro.
2. URL de retorno. Um endereço https:// do seu sistema para onde o navegador do cliente volta depois de conectar o WhatsApp (seção 5, etapa 3). Ele é cadastrado do nosso lado; a API nunca aceita esse endereço vindo da requisição.

Cada cliente que for conectar o WhatsApp precisa de:

• uma conta no Facebook com acesso ao portfólio empresarial (Meta Business) da empresa, ou disposição para criar um durante a conexão;
• o número de WhatsApp que será conectado, com acesso a ele para receber o código de verificação;
• para enviar templates: uma forma de pagamento cadastrada na conta dele na Meta. Mensagens dentro da janela de 24 horas não exigem isso.

3. Autenticação

Envie a credencial no cabeçalho Authorization de todas as chamadas:

curl https://api.inteligencialy.com/integrations/whatsapp/connections \
  -H "Authorization: Bearer intely_live_SEU_TOKEN" \
  -H "Accept: application/json"

Credencial ausente, inválida, revogada ou vencida responde 401 invalid_integration_credentials.

Não envie cabeçalhos que pareçam escolher cliente, conexão ou credencial por fora do Bearer (por exemplo X-Tenant-Id, X-Connection-Id, X-Waba-Id, X-Product-Key, X-Api-Key, Api-Key, Token): a API recusa a chamada com 422 invalid_payload. Quem você é sai só da credencial, e o recurso, só da URL.

Trocar a credencial

Para trocar sem interromper a integração: peça uma credencial nova, publique-a no seu servidor, confirme que as chamadas funcionam e só então avise a Inteligencialy para revogar a antiga. As duas funcionam ao mesmo tempo durante a troca.

4. Convenções da API

Formato de erro

{
  "error": "codigo_estavel",
  "message": "Mensagem legível para pessoas.",
  "request_id": "identificador-da-requisicao"
}

• Trate pelo campo error, nunca pela message. O código é estável; a mensagem pode mudar.
• O request_id também vem no cabeçalho X-Request-ID. Guarde-o no seu log: é o que permite investigar um problema com a gente.

Erros gerais. Os erros próprios de cada rota estão na seção dela.

As etapas START e desconectar um número conferem o formato do corpo antes de validar os campos. Nelas também podem vir 400 invalid_json (corpo vazio ou que não é JSON), 413 payload_too_large, 415 unsupported_media_type (falta Content-Type: application/json) e 503 service_unavailable (configuração indisponível do nosso lado). Nas demais rotas esses casos respondem 422 invalid_payload. Os códigos 400 bad_request e 422 validation_error existem no tratamento genérico de erros, mas nenhuma rota de integração os devolve hoje; se aparecerem, trate como invalid_payload.

Campos não reconhecidos são recusados

Cada rota aceita exatamente os campos documentados. Um campo a mais responde 422: isso evita que um erro de digitação passe despercebido.

Chamadas sem dados enviam {}

Várias etapas são POST sem dados (exchange, connection, subscribe, entre outras). Envie sempre o corpo {}. Um POST sem corpo pode ser barrado pela proteção do servidor antes de chegar à API, com uma resposta 406 em HTML, sem error nem request_id.

Limite de chamadas

Os limites são por minuto. Alguns são compartilhados entre rotas:

Em 429 too_many_requests por limite de chamadas, aguarde e repita somente aquela chamada, sem laço apertado. Nunca reinicie um fluxo inteiro por causa de um 429. Três 429 não se resolvem em segundos e têm tratamento próprio: template_daily_cap_reached e template_edit_too_soon (seção 9), e o too_many_requests da retomada da Coexistência, que vem do limite da própria Meta.

Idempotência

Os envios de mensagem exigem um idempotency_key criado por você: de 8 a 128 caracteres, começando por letra ou número, com letras, números, ., _, : e -. Use uma chave por mensagem lógica (por exemplo, lembrete-agendamento-8841).

A chave do texto vale dentro da conversa; a do template vale dentro da conexão. Como agir em cada resposta:

• Sucesso: repetir a mesma chave devolve o resultado original com "idempotent": true e status 200, sem enviar de novo.
• Sem resposta (queda de rede, tempo esgotado): repita com a mesma chave. Se o envio saiu, vem o resultado dele. Se o envio ficou sem desfecho, vem 409 outbound_intent_not_reusable ou 409 template_send_not_reusable: confira na conversa se a mensagem saiu e, se não saiu, envie com chave nova.
• Em andamento (409 outbound_intent_in_progress ou 409 template_send_in_progress): outra chamada com a mesma chave está enviando agora. Espere alguns segundos e repita com a mesma chave. Não troque a chave: a mensagem sairia duas vezes.
• Falta de forma de pagamento (409 whatsapp_payment_method_required, só em template): depois que o cliente cadastrar, repita com a mesma chave.
• Falha (502, 503, ou 409 whatsapp_connection_not_ready no momento do envio): a chave fica encerrada e repeti-la responde 409 *_not_reusable. Em 502 a Meta recusou: corrija a causa antes de tentar com chave nova. Em 503 o resultado é incerto e a mensagem pode ter saído: confira na conversa e, se não saiu, envie com chave nova.

Paginação das listagens

Valem para conexões, contatos, conversas, mensagens e fila de saída. Em conexões e contatos, from e to são aceitos mas não filtram nada. Qualquer outro parâmetro responde 422 invalid_parameters. A lista de templates não é paginada.

As listagens respondem neste formato; next_cursor é null na última página:

{
  "data": [ ... ],
  "next_cursor": "MjAyNi0wOS0yMyAxODowMjo0NC4wMDB8NDIx",
  "request_id": "..."
}

Trate o cursor como opaco: não monte nem altere.

5. Conectar o WhatsApp de um cliente

A conexão usa o Cadastro Incorporado (Embedded Signup) da Meta: o seu cliente clica em "Conectar WhatsApp" no seu sistema, faz o processo na tela oficial da Meta e volta para o seu sistema já conectado. Todo o trabalho com a Meta fica com a API; o seu sistema faz um redirecionamento e uma sequência de chamadas.

1. START: o seu backend pede o início da conexão e recebe a URL da tela da Meta.
2. Tela da Meta: o navegador do cliente abre essa URL e ele conclui o processo.
3. Retorno: a Meta devolve o navegador para a API, que o redireciona para a sua URL de retorno.
4. EXCHANGE: o seu backend confirma a autorização, imediatamente.
5. CONFIRM ASSETS: confirma qual conta e número do WhatsApp serão usados; se houver mais de uma opção, liste os ativos e peça a escolha.
6. CONNECTION: cria a conexão e devolve o connection_id.
7. SUBSCRIBE: ativa o recebimento de mensagens. Só aqui a conexão está pronta.

Etapa 1: START

{
  "tenant_external_id": "cliente-4821",
  "onboarding_mode": "business_app"
}

• tenant_external_id: o identificador do cliente no seu sistema. Texto de até 191 bytes, não pode ser só espaços nem conter caracteres de controle.
• onboarding_mode (opcional): standard (padrão, também quando vier null) ou business_app. Veja o quadro abaixo.
• A rota não aceita parâmetros na URL (query string).

Resposta 201 (trecho):

{
  "status": "pending",
  "onboarding_id": "3f1c2a9e-5b7d-4c1e-9a2f-6d8e0b4c7a11",
  "state": "...",
  "expires_at": "2026-09-23T15:30:00+00:00",
  "meta": {
    "onboarding_mode": "business_app",
    "feature_type": "whatsapp_business_app_onboarding",
    "signup_dialog_url": "https://www.facebook.com/v26.0/dialog/oauth?...",
    ...
  },
  "request_id": "..."
}

O bloco meta traz também identificadores técnicos da configuração da Meta; você não precisa deles. Guarde o onboarding_id associado ao cliente. A sessão vale até expires_at (60 minutos).

Veja também os erros de formato do corpo exclusivos desta etapa, na seção 4.

Se meta.signup_dialog_url vier null, a conexão não está disponível do nosso lado: não monte a URL por conta própria, fale com a Inteligencialy.

Etapa 2: abrir a tela da Meta

Leve o navegador do cliente para meta.signup_dialog_url, na janela inteira (redirecionamento, não popup nem iframe). Use a URL exatamente como recebeu: ela já contém tudo o que a Meta precisa e o vínculo seguro com a sessão. Não monte a URL por conta própria.

Em Coexistência, só abra a URL depois de conferir que meta.onboarding_mode é business_app e meta.feature_type é whatsapp_business_app_onboarding. Se não for, não abra e trate como erro.

Etapa 3: retorno para o seu sistema

Ao final, a Meta devolve o navegador para a API, que redireciona para a sua URL de retorno com:

https://seu-sistema.com/whatsapp/retorno?onboarding_id=3f1c2a9e-...&status=completed

https://seu-sistema.com/whatsapp/retorno?status=failed&error=onboarding_expired

O retorno nunca traz códigos nem mensagens da Meta: a API já os recebeu e guardou. Se a API não conseguir identificar a sessão (um endereço de retorno adulterado, por exemplo), ela não sabe para onde devolver o navegador e mostra o erro em JSON na própria página.

Etapa 4: EXCHANGE

Corpo {}. Resposta 200: {"status": "token_exchanged", "onboarding_id": "...", "idempotent": false, "request_id": "..."}. Chamar de novo depois de um sucesso devolve o mesmo resultado com "idempotent": true.

Etapa 5: CONFIRM ASSETS

Confirma a conta do WhatsApp (WABA) e o número que o cliente autorizou. Na maioria dos casos há exatamente um de cada: envie {} e a API resolve sozinha.

Chame primeiro o CONFIRM ASSETS com {}. Só se ele responder 409 assets_ambiguous, consulte GET …/assets, mostre as opções ao cliente e repita o confirm com a escolha. Não encerre o onboarding em token_exchanged nem em assets_ambiguous.

Resposta 200:

{
  "status": "assets_confirmed",
  "onboarding_id": "...",
  "waba_id": "912991988105750",
  "phone_number_id": "1073521112511032",
  "idempotent": false,
  "request_id": "..."
}

Depois de um confirm bem-sucedido, a escolha não muda mais nesta sessão: um novo confirm devolve os mesmos ativos com "idempotent": true, mesmo que traga outra seleção. Para trocar de número, recomece do START.

Se a resposta for 409 assets_ambiguous, o cliente autorizou mais de uma conta ou número. Liste as opções e confirme a escolhida:

Resposta 200 (trecho; os itens trazem também dados informativos da conta na Meta):

{
  "status": "assets_available",
  "selection_required": true,
  "wabas": [
    {
      "waba_id": "912991988105750",
      "name": "Barbearia Centro",
      "on_behalf_of_business": { "id": "...", "name": "Barbearia Centro Ltda" },
      "phone_numbers": [
        {
          "phone_number_id": "1073521112511032",
          "display_phone_number": "+55 47 8423-3257",
          "verified_name": "Barbearia Centro",
          "is_on_business_app": true
        }
      ]
    }
  ]
}

Esta listagem consulta a Meta e pode levar alguns segundos. Erros: 409 onboarding_not_ready (EXCHANGE ainda não feito), 422 assets_not_found, 422 meta_token_invalid, 502 asset_confirmation_failed, 503 asset_confirmation_temporarily_unavailable (inclusive quando a autorização traz contas demais para listar no tempo disponível) e 503 encryption_unavailable, com o mesmo significado da tabela abaixo.

Depois, repita o confirm com a escolha (os identificadores como texto, entre aspas):

{ "waba_id": "912991988105750", "phone_number_id": "1073521112511032" }

Mostre as opções ao cliente pelo nome da conta e do número, como apareceram na tela da Meta. Se os nomes vierem vazios e houver mais de uma opção, peça a decisão a uma pessoa em vez de escolher sozinho. A escolha é conferida pela API: não é possível confirmar um número que o cliente não autorizou.

Nomes e is_on_business_app são informativos e podem vir null: quando a consulta à Meta falha ou demora e, no caso de is_on_business_app, a partir do 51º número de uma mesma listagem. Em Coexistência, o confirm lê o sinal de novo para o número escolhido.

Etapa 6: CONNECTION

Corpo {}. Resposta 201 (ou 200 com "idempotent": true se já existia):

{
  "status": "connection_materialized",
  "connection_id": "7b2e4d10-9c3a-4f5e-8b1d-2a6c9e0f3b44",
  "onboarding_id": "...",
  "waba_id": "912991988105750",
  "phone_number_id": "1073521112511032",
  "idempotent": false,
  "request_id": "..."
}

Guarde o connection_id associado ao cliente. Ele identifica o número em todas as rotas seguintes.

Uma conexão que já esteja disconnected é apenas histórico: depois de a desconexão ser confirmada, o mesmo número pode concluir um novo onboarding, inclusive para outro Produto ou tenant. A nova tentativa recebe outro connection_id; nunca reutilize o identificador histórico. Não há compartilhamento simultâneo: enquanto existir qualquer conexão que não seja disconnected, o conflito 409 continua sendo a resposta correta.

Etapa 7: SUBSCRIBE

Corpo {}. Resposta 200:

{
  "status": "active",
  "connection_id": "7b2e4d10-...",
  "idempotent": false,
  "coexistence_sync": "completed",
  "templates": {
    "status": "completed",
    "created": 5,
    "skipped": 0,
    "failed": 0,
    "deferred": 0,
    "pending_approval": ["confirmacao_agendamento"]
  },
  "request_id": "..."
}

Só mostre o WhatsApp como conectado quando vier "status": "active". Nesta etapa a API também:

• em Coexistência, pede à Meta os contatos e o histórico do celular (coexistence_sync). Eles chegam aos poucos, nos minutos seguintes;
• cria na conta do cliente os templates que o seu produto usa (templates). Eles passam pela análise da Meta antes de poderem ser enviados.

Falha nessas duas tarefas não impede a ativação: a conexão fica ativa mesmo assim. Se o próprio subscribe falhar com 502 whatsapp_subscription_failed, 503 whatsapp_subscription_temporarily_unavailable ou 503 whatsapp_subscription_in_progress (quando já há um em andamento), repita apenas o subscribe, manualmente. Nunca volte ao EXCHANGE por causa disso. Já 409 whatsapp_connection_not_ready significa que a conexão não pode ser ativada com a autorização desta sessão (por exemplo, ela venceu): repetir não resolve; recomece do START.

Retomar a sincronização da Coexistência

Corpo {}. Só é necessário quando o subscribe trouxe coexistence_sync igual a failed. A Meta aceita esse pedido apenas nas 24 horas seguintes à conexão. Contatos e histórico são pedidos separadamente; o que a Meta já aceitou numa tentativa anterior não é pedido de novo.

Resposta 200:

{
  "status": "completed",
  "connection_id": "7b2e4d10-...",
  "history_request_id": "...",
  "contacts_request_id": "...",
  "idempotent": false,
  "request_id": "..."
}

6. Conexões e contatos

Listar conexões

{
  "data": [
    {
      "connection_id": "7b2e4d10-...",
      "tenant_external_id": "cliente-4821",
      "waba_id": "912991988105750",
      "phone_number_id": "1073521112511032",
      "status": "active",
      "created_at": "2026-09-23T14:31:02+00:00",
      "last_activity_at": "2026-09-23T18:02:44+00:00"
    }
  ],
  "next_cursor": null,
  "request_id": "..."
}

• Traz as conexões do seu produto, paginadas (seção 4): siga o next_cursor para ver todas. Não há filtro por cliente na consulta; separe pelo tenant_external_id do seu lado.
• status: active quando operando; disconnected quando o cliente desconectou. Antes da ativação, a conexão aparece com pending_subscription (criada, ainda sem SUBSCRIBE), subscription_in_progress ou subscription_ambiguous (SUBSCRIBE sem desfecho; repita o SUBSCRIBE). disconnect_ambiguous significa que a Meta pode ter removido o App: não repita a desconexão e avise a Inteligencialy. Só active recebe e envia mensagens.
• last_activity_at: última mensagem trocada, em qualquer direção (null se nunca houve).

Desconectar um número

Use somente pelo backend do seu produto, depois de o usuário confirmar a ação. O corpo identifica a empresa que está autorizada no seu sistema:

{
  "tenant_external_id": "cliente-4821"
}

A credencial Bearer determina o produto; a API compara o tenant_external_id exatamente com a conexão. Não aceite esse valor do navegador e não envie product_key, número, WABA ou token Meta. Uma conexão de outra empresa ou produto responde como inexistente.

Resposta 200:

{
  "status": "disconnected",
  "connection_id": "7b2e4d10-...",
  "idempotent": false,
  "request_id": "..."
}

A API remove a assinatura de webhooks do App na WABA e, somente depois de a Meta confirmar, apaga os contatos, conversas, mensagens, fila de saída e eventos locais daquele número. A linha técnica da conexão e o histórico de operações permanecem. Desvincular a Plataforma de Negócios no aplicativo WhatsApp Business continua sendo tarefa do dono do número. Em Coexistência, status=disconnected significa que o vínculo foi encerrado na Central; não é confirmação de que a Plataforma de Negócios foi desvinculada no celular. O dono deve conferir no WhatsApp Business em Configurações → Conta → Plataforma de Negócios → Desconectar conta.

Contatos (Coexistência)

A agenda do celular do cliente, sincronizada na conexão. Cada item traz contact_id, wa_id (número com DDI, só dígitos), full_name e first_name (podem vir null) e synced_at (horário informado pela Meta para aquele dado do contato; pode vir null). Ordena pelo nome, e o padrão desc vai de Z para A: para ordem alfabética, envie order=asc. Pagina com limit e cursor.

Para mostrar nomes na sua lista de conversas sem copiar a agenda para o seu banco, filtre pelos números que estão na tela:

GET /integrations/whatsapp/connections/{connection_id}/contacts?wa_id=5511988887777,5519998406637

• Até 100 números por consulta, separados por vírgula, só dígitos (sem +, sem espaço vazio entre vírgulas e sem vírgula sobrando no fim; senão, 422 invalid_parameters).
• Com wa_id, a resposta não é paginada: vêm todos os que existirem, e next_cursor é null. Não envie cursor junto (responde 422).
• Número que não está na agenda simplesmente não aparece. Mostre o número no lugar do nome.

7. Conversas e mensagens recebidas

Listar conversas

{
  "data": [
    {
      "conversation_id": "c4a1...",
      "contact_wa_id": "5511988887777",
      "last_direction": "inbound",
      "last_message_at": "2026-09-23T18:02:44+00:00",
      "message_count": 12,
      "service_window_open": true,
      "service_window_expires_at": "2026-09-24T18:02:44+00:00"
    }
  ],
  "next_cursor": null,
  "request_id": "..."
}

service_window_open diz se é possível responder com texto livre agora. service_window_expires_at é o fim da janela aberta pela última mensagem recebida: continua preenchido com uma data passada depois que a janela fecha, e vem null se o contato nunca escreveu. Decida pelo service_window_open.

last_message_at é o horário da última mensagem da conversa informado pela Meta (quando o contato enviou), não o horário em que ela chegou à API. Mudança de status de entrega não altera a conversa.

Mensagens de uma conversa

{
  "data": [
    {
      "message_id": "9d0e...",
      "meta_message_id": "wamid.HBgN...",
      "direction": "inbound",
      "type": "text",
      "text": "Oi, queria remarcar meu horário",
      "media_reference": null,
      "delivery_status": null,
      "event_timestamp": "2026-09-23T18:02:44+00:00"
    }
  ],
  "next_cursor": null,
  "request_id": "..."
}

• direction: inbound (recebida) ou outbound (enviada).
• type: o tipo informado pela Meta (text, image, audio e outros), template para template enviado pela API, ou null quando o status de uma mensagem chegou antes da própria mensagem. Trate tipos desconhecidos sem erro.
• media_reference: identificador da mídia na Meta, quando houver. A API não oferece download de mídia.
• delivery_status: null enquanto não chega status. Os valores usuais são sent → delivered → read, ou failed, e entre eles o status só avança. A Meta pode mandar outros valores, que são repassados como vieram; mensagens do histórico da Coexistência podem trazer status mesmo sendo recebidas.

Como saber que chegou mensagem nova

A API envia um webhook ao backend do Produto logo depois de registrar a mensagem recebida. O endereço e o segredo são configurados uma vez pela Inteligencialy para cada Produto; não há polling, nem token Bearer no navegador. O webhook só cobre mensagens inbound de conexões ativas. Status de entrega, ecos, histórico, contatos e templates não geram este aviso.

O destino recebe POST com JSON:

{
  "event_id": "d269cfad-7cf5-42c8-b0bf-1d6abcc7fc6e",
  "event_type": "whatsapp.message.received",
  "occurred_at": "2026-10-08T15:30:00.000Z",
  "product_key": "HORALI",
  "tenant_external_id": "empresa-123",
  "connection_id": "...",
  "conversation_id": "...",
  "message": {
    "message_id": "wamid.HBgN...",
    "direction": "inbound",
    "type": "text",
    "text": "Olá, quero agendar",
    "media_reference": null,
    "event_timestamp": "2026-10-08T15:30:00.000Z"
  }
}

• Assinatura: o corpo JSON bruto é assinado por HMAC SHA-256. Verifique o cabeçalho X-Inteligencialy-Signature-256, no formato sha256=<hex>, com o segredo exclusivo do Produto. X-Inteligencialy-Event-Id e X-Inteligencialy-Event-Type repetem o identificador e o tipo.
• ACK: depois de validar e persistir o trabalho, responda qualquer HTTP 2xx em até cinco segundos. Redirecionamentos não são seguidos.
• Idempotência: guarde e deduplique por event_id. Uma entrega pode ser repetida após timeout, falha de rede ou resposta não-2xx, e eventos podem chegar fora de ordem.
• Recuperação: a primeira tentativa é imediata. Se o seu backend estiver indisponível, a API conserva o evento e tenta de novo; a recuperação pode levar até 16 minutos na infraestrutura atual. Não crie polling para compensar isso.
• Para consultar mensagens ou conferir status depois, as rotas de conversas e mensagens continuam disponíveis.

8. Enviar mensagem de texto

{
  "idempotency_key": "resposta-8841-1",
  "text": "Claro! Temos horário amanhã às 15h. Confirma?",
  "on_closed_window": "queue"
}

Texto livre só pode ser enviado com a janela de 24 horas aberta, ou seja, até 24 horas depois da última mensagem recebida do contato. Com a janela fechada:

• reject: a API recusa com 409 service_window_closed. Para falar com o contato, use um template (seção 9).
• queue: a mensagem entra na fila e sai sozinha, sem custo, quando o contato escrever de novo, se isso acontecer antes de expires_at. Cada mensagem recebida libera até 5 mensagens da fila daquela conversa, em ordem; as demais esperam a próxima mensagem do contato. Cabem até 50 mensagens na fila de cada conversa.

A chave de idempotência vale dentro desta conversa: repeti-la aqui devolve o resultado original; usar a mesma chave em outra conversa cria uma intenção independente.

Acompanhar a fila de saída

Lista os envios de texto da conexão, os que passaram pela fila e os enviados direto com a janela aberta, ordenados pelo momento do pedido. Aceita o filtro status (queued, sending, sent, expired ou failed), além da paginação e do período (que filtra pelo momento do pedido). Cada item traz outbound_id, status, meta_message_id, attempts, last_error, expires_at, sent_at e created_at; para ligar um item à conversa, guarde o outbound_id devolvido no envio.

• sending: a mensagem está sendo entregue à Meta neste momento. Normalmente passa a sent ou failed em segundos; se a entrega for interrompida, passa a failed depois de 2 minutos, na próxima vez que alguém tocar nesse envio.
• failed com resultado incerto (a entrega foi interrompida sem resposta da Meta) não volta para a fila: confira na conversa se a mensagem saiu.

9. Templates

Templates são mensagens com texto aprovado pela Meta. São a única forma de iniciar uma conversa ou de falar com um contato fora da janela de 24 horas. A Meta cobra os envios na conta do seu cliente, conforme a tabela de preços dela, que depende da categoria e de a janela estar aberta.

Listar templates da conexão

Resposta {"data": [...], "request_id": "..."}, sem paginação e com no máximo 100 itens. Cada item traz name, language, status (APPROVED, PENDING, REJECTED, PAUSED, DISABLED, ou ABSENT para o que a última sincronização não encontrou mais na Meta), approved_category, requested_category, variables_count e last_synced_at. A rota não aceita parâmetros na URL.

Enviar template

{
  "idempotency_key": "lembrete-agendamento-8841",
  "to": "5511988887777",
  "template": "lembrete_agendamento_vespera",
  "language": "pt_BR",
  "variables": ["Ana", "Corte de cabelo", "14:30"],
  "accept_category": "UTILITY"
}

• to: número com DDI e DDD, só dígitos (8 a 18). Não precisa ter conversado antes.
• template e language: nome e idioma exatamente como na lista de templates. Idioma diferente conta como outro template.
• variables: os valores de {{1}}, {{2}}…, na ordem. A quantidade precisa bater com o template (variables_count na lista). Até 10 valores, cada um com até 1.024 bytes, sem quebra de linha, tabulação ou mais de quatro espaços seguidos; fora disso, 422 invalid_payload.
• accept_category (opcional): a categoria de cobrança que você aceita pagar. Com ele, a API só envia se a categoria aprovada pela Meta for exatamente essa. Sem ele, a API recusa se a Meta aprovou numa categoria diferente da pedida na criação, e recusa todo template aprovado como MARKETING. A Meta pode aprovar como MARKETING, que custa mais, um template pedido como UTILITY.

Resposta 201 (ou 200 com "idempotent": true para uma chave já enviada):

{
  "status": "sent",
  "send_id": "...",
  "meta_message_id": "wamid.HBgN...",
  "template": "lembrete_agendamento_vespera",
  "language": "pt_BR",
  "category": "UTILITY",
  "idempotent": false,
  "request_id": "..."
}

A mensagem aparece na conversa daquele número, criada se ainda não existir. Se o contato responder, a janela de 24 horas abre e o restante da conversa pode seguir em texto livre, sem custo de template.

Criar um template próprio

Para um caso que o catálogo do seu produto não cobre:

{
  "name": "aviso_atraso_profissional",
  "language": "pt_BR",
  "category": "UTILITY",
  "body": "Olá {{1}}, seu atendimento das {{2}} vai atrasar cerca de {{3}} minutos. Responda esta mensagem se preferir remarcar.",
  "examples": ["Ana", "14:30", "15"]
}

• name: letras minúsculas, números e _, até 64 caracteres. Não pode ser alterado depois.
• category: UTILITY ou MARKETING.
• body: até 1.024 bytes, com variáveis em sequência a partir de {{1}}.
• examples: exatamente um exemplo por variável, na ordem, cada um com até 256 bytes. A Meta usa os exemplos para analisar o template.

Variáveis fora de sequência ({{2}} sem {{1}}) respondem 422 template_placeholders_not_sequential; exemplos a menos ou a mais respondem 422 template_examples_required. Já existindo um template com o mesmo nome e idioma, só é possível criar de novo se ele estiver REJECTED ou ABSENT; nos outros casos, 409 whatsapp_template_already_exists. Conexão não ativa responde 409 whatsapp_connection_not_ready. Falha do lado da Meta responde 502 whatsapp_template_create_failed ou 503 whatsapp_template_create_temporarily_unavailable.

Responde 201 com name, language, status (o que a Meta informou, normalmente PENDING), approved_category, requested_category e variables_count. Dica que funciona: termine o texto pedindo uma resposta. Se o contato responder, a janela de 24 horas abre e o resto da conversa não gera custo de template.

Corrigir o texto de um template

{
  "name": "aviso_atraso_profissional",
  "language": "pt_BR",
  "body": "Olá {{1}}, seu atendimento das {{2}} vai atrasar uns {{3}} minutos. Responda se preferir remarcar.",
  "examples": ["Ana", "14:30", "15"]
}

Nome, idioma e categoria não mudam. A Meta reanalisa o texto; a resposta 200 com "status": "edit_submitted" confirma só o pedido. Limites da Meta: 1 edição por dia em template aprovado e 10 edições a cada 30 dias; a API confere a primeira regra antes de chamar a Meta, e a segunda, quando violada, volta como 502 whatsapp_template_edit_failed.

A quantidade de variáveis pode mudar na edição. Se mudar, ajuste os envios: com a quantidade antiga, eles passam a responder 422 template_variables_mismatch.

Manutenção

• POST…/templates/sync: atualiza a lista a partir da conta do cliente na Meta. Corpo {}. Não envia nada e não gera custo. Responde synced, created, updated, absent e truncated (contagens e se a leitura foi cortada). Falha na leitura: 502 whatsapp_template_sync_failed ou 503 whatsapp_template_sync_temporarily_unavailable.
• POST…/templates/provision: cria os templates do seu produto que faltarem na conta do cliente (por exemplo, se o subscribe voltou com templates.status partial ou failed). Corpo {}; os que já existem são ignorados. Responde com os mesmos campos do bloco templates do subscribe. Também tem tempo limitado: se voltar partial com deferred, chame de novo. Se o seu produto não tiver templates cadastrados, responde 409 whatsapp_template_catalog_empty.
• As duas rotas respondem 409 whatsapp_connection_not_ready se a conexão não estiver ativa.

10. Boas práticas e checklist

Segurança

• A credencial fica só no servidor, em variável de ambiente ou cofre de segredos.
• Nada de chamada à API a partir do navegador ou do aplicativo: sempre pelo seu backend.
• Não registre em log o token nem o conteúdo das mensagens dos seus clientes.

Robustez

• Trate erros pelo campo error e guarde o request_id.
• Envie {} nos POST sem dados.
• Use uma idempotency_key por mensagem lógica, derivada do seu dado (o id do agendamento, por exemplo), nunca aleatória. Repita a mesma chave quando não houver resposta, em *_in_progress e depois de whatsapp_payment_method_required. Use chave nova só depois de conferir que um 503 não enviou, ou depois de corrigir a causa de um 502. Detalhes na seção 4.
• Nunca repita o EXCHANGE automaticamente.
• Em 429 too_many_requests por limite de chamadas, espere e repita só aquela chamada. template_daily_cap_reached e template_edit_too_soon só se resolvem em horas.
• Na consulta periódica de mensagens, recue o from e descarte repetidas pelo message_id (seção 7).

Antes de liberar para os clientes

1. Conexão completa de ponta a ponta com um número de teste, até "status": "active".
2. Recebimento: uma mensagem enviada ao número aparece nas conversas.
3. Resposta em texto dentro da janela de 24 horas.
4. Envio de template aprovado para um número que ainda não conversou.
5. Tela de erro para cancelled, failed (com o error do retorno), onboarding_expired e coexistence_not_confirmed.
6. Explicação ao cliente sobre Coexistência antes de ele abrir a tela da Meta.

11. Referência rápida de rotas

Todas exigem Authorization: Bearer. Prefixo comum: /integrations/whatsapp. O retorno da tela da Meta (etapa 3) é uma rota da própria API, chamada pelo navegador, e não entra nesta lista.

12. Suporte

Em caso de dúvida ou problema, fale com o contato da Inteligencialy que entregou a sua credencial. Para qualquer erro, envie o request_id, o horário aproximado e a rota chamada. Nunca envie a credencial por mensagem, e-mail ou chamado.