Documentação da API

API REST pública do Abacato AI para integrar seus próprios sistemas ao WhatsApp.

Com a API pública você envia mensagens de WhatsApp (texto, template e mídia), lista os contatos importados, consulta o status de entrega e gerencia templates — tudo autenticado por uma chave de API criada no painel. Também é possível receber eventos por webhook ou plugar um Chatwoot sem escrever código. A especificação legível por máquina está disponível em openapi.yaml.

Última atualização: 2026-07-15 · versão 1.3.0

Primeiros passos

Base URL

https://api.abacato.vps.aprendendoai.com

Todas as requisições usam Content-Type: application/json e retornam JSON. Envios aceitos retornam 202; consultas retornam 200; uploads, 201.

Autenticação

Toda requisição é autenticada por uma chave de API enviada no cabeçalho X-API-Key. Crie e gerencie suas chaves no painel do Abacato AI em Configurações → Chaves de API. A chave completa é exibida uma única vez, no momento da criação — guarde-a com segurança.

X-API-Key: abct_live_xxxxxxxxxxxxxxxxxxxxxxxx

O cabeçalho Authorization: Bearer <chave> também é aceito, em qualquer endpoint — é o formato que clientes da Meta Cloud API já enviam.

Referência de endpoints

Todos os caminhos são relativos à Base URL e ficam sob /api/v1/public. Todos exigem o cabeçalho X-API-Key.

Enviar uma mensagem de texto

Parâmetros do corpo

Requisição

# envia um texto simples
curl -X POST https://api.abacato.vps.aprendendoai.com/api/v1/public/messages/text \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511888888888",
    "from": "5511987654321",
    "text": "Olá! Essa é uma mensagem de teste."
  }'

from (o número de origem, só dígitos) é opcional — necessário só se você tem vários números e quer escolher qual envia. Com um número, pode omitir.

Resposta 202 — aceita pela Meta (ainda não entregue)

{
  "message": {
    "id": "9f1c2d3e-...",
    "direction": "outbound",
    "recipientNumber": "5511888888888",
    "messageType": "text",
    "content": "Olá! Essa é uma mensagem de teste.",
    "wamid": "wamid.HBg...",
    "status": "sent",
    "sentAt": "2026-07-08T14:00:00.000Z"
  }
}

Enviar uma mensagem de template

Templates podem ser enviados a qualquer momento (fora da janela de 24h de atendimento). O template precisa já estar aprovado na conta de WhatsApp Business.

Parâmetros do corpo

Requisição

curl -X POST https://api.abacato.vps.aprendendoai.com/api/v1/public/messages/template \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511888888888",
    "from": "5511987654321",
    "templateName": "pedido_atualizado",
    "language": "pt_BR",
    "components": [
      { "type": "body",
        "parameters": [ { "type": "text", "text": "#1234" } ] }
    ]
  }'

from pode ser omitido se você tem um único número conectado.

Requisição — botão de URL dinâmica

O botão vira um componente próprio, com sub_type: "url" e index: "0" (o índice do botão no template). Se o template também tem variáveis no corpo, mande os dois componentes:

curl -X POST https://api.abacato.vps.aprendendoai.com/api/v1/public/messages/template \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511888888888",
    "templateName": "enviar_fatura",
    "language": "pt_BR",
    "components": [
      { "type": "body",
        "parameters": [ { "type": "text", "text": "Charles" } ] },
      { "type": "button", "sub_type": "url", "index": "0",
        "parameters": [ { "type": "text", "text": "9f8e7d" } ] }
    ]
  }'

Requisição — template de Authentication (OTP)

# o código é gerado pelo seu sistema; a API monta corpo + botão
curl -X POST https://api.abacato.vps.aprendendoai.com/api/v1/public/messages/template \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511888888888",
    "templateName": "codigo_acesso",
    "language": "pt_BR",
    "code": "123456"
  }'

Requisição — cabeçalho de mídia (vídeo, imagem ou documento)

Se o template foi criado com cabeçalho de mídia, informe o arquivo real num componente header. A mídia entra por link (URL pública) ou por id (de um upload, reutilizável por ~30 dias):

curl -X POST https://api.abacato.vps.aprendendoai.com/api/v1/public/messages/template \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511888888888",
    "templateName": "conta_criada_teste_30_dias",
    "language": "pt_BR",
    "components": [
      { "type": "header",
        "parameters": [
          { "type": "video", "video": { "link": "https://exemplo.co/videos/instalacao.mp4" } }
        ] },
      { "type": "body",
        "parameters": [ { "type": "text", "text": "João" } ] }
    ]
  }'

Resposta 202 — aceita pela Meta (ainda não entregue)

{
  "message": {
    "id": "9f1c2d3e-...",
    "direction": "outbound",
    "recipientNumber": "5511888888888",
    "messageType": "template",
    "templateName": "pedido_atualizado",
    "wamid": "wamid.HBg...",
    "status": "sent",
    "sentAt": "2026-07-08T14:00:00.000Z"
  }
}

Listar contatos importados

Parâmetros de query

Os contatos pertencem a um número. Sem from nem accountId, listamos os do número conectado há mais tempo (o primário) — o mesmo padrão do envio.

Requisição

# Primeira página, padrão (50 itens do número mais recente)
curl "https://api.abacato.vps.aprendendoai.com/api/v1/public/contacts" \
  -H "X-API-Key: abct_live_xxx"

# Segunda página, 20 por vez
curl "https://api.abacato.vps.aprendendoai.com/api/v1/public/contacts?page=2&limit=20" \
  -H "X-API-Key: abct_live_xxx"

# Buscar por nome ou trecho do número
curl "https://api.abacato.vps.aprendendoai.com/api/v1/public/contacts?search=maria" \
  -H "X-API-Key: abct_live_xxx"

# Contatos de um número específico, com busca. Codifique o valor na URL:
# um espaco vira %20 e o + de um telefone vira %2B
curl "https://api.abacato.vps.aprendendoai.com/api/v1/public/contacts?from=5511999999999&search=maria%20silva" \
  -H "X-API-Key: abct_live_xxx"

Resposta 200

{
  "contacts": [
    {
      "id": "3a2b1c...",
      "phoneNumber": "5511888888888",
      "name": "Maria Silva",
      "createdAt": "2026-07-01T10:00:00.000Z",
      "updatedAt": "2026-07-01T10:00:00.000Z"
    }
  ],
  "total": 128,
  "page": 1,
  "limit": 50
}

Status da conta de WhatsApp

Retorna o número conectado há mais tempo (o primário) — o mesmo pelo qual saem os envios sem seletor —, ou account: null se nenhum estiver conectado. Com vários números conectados, use GET /numbers para ver todos.

Requisição

curl https://api.abacato.vps.aprendendoai.com/api/v1/public/whatsapp/status \
  -H "X-API-Key: abct_live_xxx"

Resposta 200

{
  "account": {
    "id": "2e4ff797-b858-4676-bf18-355997675a36",
    "provider": "meta_cloud",
    "wabaId": "1234567890",
    "phoneNumberId": "9876543210",
    "evolutionInstanceName": null,
    "displayName": "Minha Empresa",
    "displayPhoneNumber": "+55 11 98765-4321",
    "label": "Atendimento",
    "qualityRating": "GREEN",
    "status": "active",
    "isCoex": true,
    "connectedAt": "2026-07-08T19:17:03.783Z"
  }
}

evolutionInstanceName só vem preenchido em conexões via QR Code; wabaId e phoneNumberId, só na API Oficial. label é o nome que você deu ao número no painel, ou null.

Listar mensagens

Mensagens recentes da conta, da mais nova para a mais antiga.

Parâmetros de query

As mensagens pertencem a um número. Sem from nem accountId, listamos as do número conectado há mais tempo (o primário).

Requisição

curl "https://api.abacato.vps.aprendendoai.com/api/v1/public/messages?limit=20&status=failed" \
  -H "X-API-Key: abct_live_xxx"

Resposta 200

{
  "messages": [ /* mesmo formato de Status da mensagem */ ],
  "hasMore": true
}

Enviar mídia

Envie exatamente um entre link (URL pública) ou mediaId (de um upload anterior). Enviar os dois, ou nenhum, retorna 400.

Corpo

Requisição

curl -X POST "https://api.abacato.vps.aprendendoai.com/api/v1/public/messages/media" \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","from":"5511987654321","type":"image","link":"https://exemplo.com/foto.jpg","caption":"Olá!"}'

from/accountId opcional — ver Escolher o número de envio.

Resposta 202

{
  "message": {
    "id": "9f8e7d...",
    "messageType": "image",
    "wamid": "wamid.HBgM...",
    "status": "sent"
  }
}

Números conectados

Todos os números de WhatsApp conectados à sua conta.

Resposta 200

{
  "numbers": [
    {
      "id": "7d6e5f...",
      "provider": "meta_cloud",
      "wabaId": "1234567890",
      "phoneNumberId": "9876543210",
      "displayName": "Minha Empresa",
      "displayPhoneNumber": "+55 11 99999-9999",
      "label": "Suporte",
      "qualityRating": "GREEN",
      "status": "active",
      "connectedAt": "2026-07-08T12:00:00.000Z"
    }
  ]
}

label é o nome que você deu ao número no painel. status pode vir como in_review: é a janela de 24-48h em que a Meta analisa um número recém-conectado — ele já envia e recebe normalmente.

Escolher o número de envio

Com mais de um número conectado, todo endpoint de envio e de consulta aceita um seletor opcional. A precedência é accountId, depois from, e por fim — se você não passar nenhum — o número conectado há mais tempo (o seu número primário).

curl -X POST "https://api.abacato.vps.aprendendoai.com/api/v1/public/messages/text" \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"from":"5511987654321","to":"5511888888888","text":"Olá"}'

Templates

Listar templates

Retorna todos os templates da conta, já com o texto do corpo e os componentes da Meta — é daqui que você lê as variáveis de cada template.

Resposta 200

{
  "templates": [
    {
      "id": "1a2b3c...",
      "metaTemplateId": "1234567890",
      "name": "pedido_atualizado",
      "category": "UTILITY",
      "status": "APPROVED",
      "language": "pt_BR",
      "bodyText": "Olá {{1}}, sua fatura {{2}} está disponível.",
      "components": [
        {
          "type": "BODY",
          "text": "Olá {{1}}, sua fatura {{2}} está disponível.",
          "example": { "body_text": [[ "João", "#1234" ]] }
        },
        {
          "type": "BUTTONS",
          "buttons": [
            { "type": "URL", "text": "Ver fatura", "url": "https://exemplo.co/f?id={{1}}", "example": [ "https://exemplo.co/f?id=9f8e7d" ] }
          ]
        }
      ],
      "pendingCategory": null,
      "rejectedReason": null
    }
  ]
}

Consultar as variáveis de um template

As variáveis ficam em dois lugares da resposta acima:

• bodyText mostra os espaços reservados como estão no texto: {{1}}, {{2}} (posicionais) ou {{nome}} (nomeadas).
• components carrega os valores de exemplo aprovados:
  • No componente BODY, posicionais vêm em example.body_text — um array de linhas: [[ "João", "#1234" ]] (o 1º valor é {{1}}, o 2º é {{2}}). Nomeadas vêm em example.body_text_named_params: [{ "param_name": "nome", "example": "João" }].
  • No botão URL, o exemplo é a URL já preenchida em example: ["https://exemplo.co/f?id=9f8e7d"].

Criar template

Parâmetros do corpo

Tipos de botão

Requisição

curl -X POST https://api.abacato.vps.aprendendoai.com/api/v1/public/templates \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pedido_atualizado",
    "category": "UTILITY",
    "language": "pt_BR",
    "bodyText": "Olá {{1}}, sua fatura {{2}} está disponível.",
    "footerText": "Toque no botão para pagar",
    "variableExamples": { "1": "João", "2": "#1234" },
    "messageSendTtlSeconds": 43200,
    "buttons": [
      { "type": "URL", "text": "Ver fatura", "url": "https://exemplo.co/f?id={{1}}", "urlExample": "9f8e7d" }
    ]
  }'

Retorna 201. O status e o category vêm da resposta da Meta — um template enviado como UTILITY pode voltar APPROVED como MARKETING se o conteúdo for promocional (custa ~9x mais).

Cabeçalho de mídia (imagem, vídeo ou documento)

Um template pode exibir uma imagem, vídeo ou documento acima do corpo — é o cabeçalho de mídia (não é um botão; botões não reproduzem mídia). Informe headerFormat e a URL pública do arquivo de exemplo em headerMediaUrl:

curl -X POST https://api.abacato.vps.aprendendoai.com/api/v1/public/templates \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "conta_criada_teste_30_dias",
    "category": "UTILITY",
    "language": "pt_BR",
    "headerFormat": "VIDEO",
    "headerMediaUrl": "https://exemplo.co/videos/instalacao.mp4",
    "bodyText": "Olá {{1}}! Sua conta foi criada e o teste de 30 dias já está ativo.",
    "footerText": "Atendimento de seg a sex, das 9h às 18h.",
    "variableExamples": { "1": "João" },
    "buttons": [
      { "type": "URL", "text": "Acessar o Abacato", "url": "https://abacato.app" }
    ]
  }'

Editar template

O {id} é o metaTemplateId (o id da Meta), não o id interno. Nome e idioma não podem mudar. Aceita os mesmos campos de conteúdo do criar. Depois da edição a Meta re-revisa e o status volta para PENDING.

Requisição

curl -X POST https://api.abacato.vps.aprendendoai.com/api/v1/public/templates/1234567890 \
  -H "X-API-Key: abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "bodyText": "Olá {{1}}, seu pedido {{2}} saiu para entrega.",
    "variableExamples": { "1": "João", "2": "#1234" }
  }'

Excluir template

A Meta exclui templates pelo nome, não pelo id.

Requisição

curl -X DELETE https://api.abacato.vps.aprendendoai.com/api/v1/public/templates/pedido_atualizado \
  -H "X-API-Key: abct_live_xxx"

Resposta 200

{ "deleted": true }

Status da mensagem

O {id} é o message.id (UUID) devolvido no envio. Como a entrega é assíncrona, este é o endpoint que diz se a mensagem realmente chegou.

Ciclo de vida do status

Requisição

curl https://api.abacato.vps.aprendendoai.com/api/v1/public/messages/9f1c2d3e-... \
  -H "X-API-Key: abct_live_xxx"

Resposta 200 — exemplo de falha na entrega

{
  "message": {
    "id": "9f1c2d3e-...",
    "recipientNumber": "5511888888888",
    "messageType": "template",
    "templateName": "codigo_acesso",
    "wamid": "wamid.HBg...",
    "status": "failed",
    "errorMessage": "Business eligibility payment issue",
    "sentAt": "2026-07-09T13:20:07.787Z",
    "statusUpdatedAt": "2026-07-09T13:20:09.013Z"
  }
}

Um 404 significa que a mensagem não existe ou não pertence à sua conta.

Mídia

Para enviar um arquivo que não está numa URL pública, faça upload primeiro e use o mediaId devolvido em POST /messages/media.

Upload

Requisição multipart/form-data com o campo file. Limite de 100 MB; acima disso a resposta é 413.

curl -X POST "https://api.abacato.vps.aprendendoai.com/api/v1/public/media" \
  -H "X-API-Key: abct_live_xxx" \
  -F "file=@/caminho/foto.jpg"

Resposta 201

{
  "id": "1234567890",
  "mimeType": "image/jpeg",
  "fileSize": 83122,
  "filename": "foto.jpg"
}

O id é o que você passa como mediaId em POST /messages/media. Ele é reutilizável por 30 dias.

Download

Devolve os bytes do arquivo, com o Content-Type original. Use este endpoint para baixar mídias recebidas em mensagens: a URL que a Meta gera expira em minutos e só funciona com o nosso token, então nunca é exposta.

Exclusão

Resposta 200

{ "deleted": true }

Webhooks

Configure em Configurações → Webhooks uma URL https para receber mensagens recebidas e atualizações de status. É a forma recomendada de saber que uma mensagem foi entregue, em vez de consultar o status em loop.

Assinatura

Todo POST leva o cabeçalho X-Abacato-Signature, no formato sha256=<hmac>, calculado sobre o corpo bruto com o seu segredo de assinatura. Verifique-o antes de confiar no evento.

// Node.js
const esperado = 'sha256=' + crypto
  .createHmac('sha256', segredo)
  .update(corpoBruto)
  .digest('hex');
const valido = crypto.timingSafeEqual(
  Buffer.from(esperado), Buffer.from(req.headers['x-abacato-signature'])
);

Evento: mensagem recebida

{
  "event": "message.received",
  "timestamp": "2026-07-09T12:00:00.000Z",
  "data": {
    "from": "5511888888888",
    "contact_name": "Ana",
    "message_id": "wamid.HBgM...",
    "type": "image",
    "image": {
      "id": "1234567890",
      "media_url": "https://api.abacato.vps.aprendendoai.com/api/v1/public/media/1234567890"
    }
  },
  "account": { "phone_number_id": "9876543210" }
}

Em mídias adicionamos media_url: um link pronto para baixar os bytes com a sua chave de API, já que o id da Meta sozinho não é resolvível por você.

Evento: status da mensagem

{
  "event": "message.status",
  "data": {
    "message_id": "wamid.HBgM...",
    "status": "delivered",
    "recipient_id": "5511888888888"
  }
}

Entrega e reenvio

Responda 2xx rapidamente. Falhas são repetidas duas vezes (+30s e +120s) e registradas em Entregas recentes, de onde você pode reenviar manualmente — um reenvio traz o cabeçalho X-Abacato-Redelivery.

Integração com Chatwoot

O Chatwoot já traz um canal nativo de WhatsApp Cloud. Como falamos o protocolo da Meta, basta apontá-lo para nós: nenhuma alteração de código.

1. Em Configurações → Webhooks, no cartão Chatwoot, informe a URL base do seu Chatwoot e salve.
2. Copie o bloco de variáveis exibido e reinicie o Chatwoot:

WHATSAPP_CLOUD_BASE_URL=https://api.abacato.vps.aprendendoai.com
WHATSAPP_APP_SECRET=whsec_xxxxxxxxxxxxxxxx

3. Crie uma caixa de entrada WhatsApp com provedor WhatsApp Cloud, usando o phoneNumberId e o wabaId mostrados no painel. Como token de acesso, use uma chave de API do Abacato.

A partir daí, mensagens recebidas caem na caixa de entrada e as respostas dos agentes saem pelo seu número, sem intermediários.

Compatibilidade Meta Cloud API

Qualquer cliente que já fale a Graph API da Meta pode apontar a base URL para nós. Autentique com a sua chave de API, tanto em X-API-Key quanto em Authorization: Bearer.

Qualquer versão no formato v25.0 é aceita. As respostas — inclusive os erros — usam o mesmo envelope da Meta. Em GET /{media_id}, o campo url aponta para o nosso download: a URL da Meta expira e exige o nosso token.

curl -X POST "https://api.abacato.vps.aprendendoai.com/v25.0/9876543210/messages" \
  -H "Authorization: Bearer abct_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"messaging_product":"whatsapp","to":"5511999999999","type":"text","text":{"body":"Olá"}}'

Limites de taxa

Cada chave de API pode fazer até 1000 requisições a cada 15 minutos. Ao exceder, a API retorna 429 Too Many Requests — aguarde e tente novamente.

Erros

Erros retornam um corpo JSON no formato { "error": "descrição" }.

{
  "error": "Invalid or inactive API key"
}

Envio recusado

Quando um envio de texto, template ou mídia é recusado (pela Meta, ou pela API antes de chegar nela), a tentativa fica registrada como uma mensagem com status failed, e a resposta de erro traz o messageId dela. Consulte-a em Status da mensagem: o errorMessage repete o motivo. Um corpo inválido (um campo obrigatório ausente, por exemplo) não gera registro nem messageId.

{
  "error": "Cannot send a message to the sending number itself. Use a different recipient, or send from another connected number.",
  "messageId": "4b7e0c1a-..."
}