WhatsApp

A API expõe operações para gerenciar contatos e enviar mensagens de texto via inboxes WhatsApp já conectadas (Baileys ou WhatsApp Cloud API). O envio passa pelo serviço interno de WhatsApp da plataforma — não há comunicação direta com a API do Meta nesta versão.

Para conectar uma inbox use o painel Configurações → Integrações → WhatsApp Business. A API v1 não cria inboxes, apenas opera sobre as existentes.

Contatos

GET /v1/whatsapp/contacts

Lista os contatos de WhatsApp do time.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Página atual
`limit`	number	20	Itens por página (máx: 100)
`tag`	string	—	Filtrar por tag
`client_id`	uuid	—	Filtrar por cliente vinculado
`search`	string	—	Buscar por nome, telefone ou push_name
`sort`	string	`-created_at`	`push_name`, `custom_name`, `phone`, `created_at`, `updated_at`

Request

curl -X GET "https://app.sonarbr.io/api/v1/whatsapp/contacts?search=joao" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440010",
      "phone": "5511999998888",
      "jid": "5511999998888@s.whatsapp.net",
      "push_name": "João Silva",
      "custom_name": "João — TechStore",
      "profile_picture_url": null,
      "notes": null,
      "tags": ["lead-quente"],
      "client_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2026-05-18T10:30:00Z",
      "updated_at": "2026-05-18T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

POST /v1/whatsapp/contacts

Cria um novo contato. O jid é calculado automaticamente a partir do telefone (apenas dígitos com DDI).

Campo	Tipo	Obrigatório	Descrição
`phone`	string	Sim	Entre 10 e 15 dígitos, com DDI (`5511...`)
`custom_name`	string	Não	Nome de exibição interno
`notes`	string	Não	Anotações privadas
`tags`	string[]	Não	Tags livres
`client_id`	uuid	Não	Vincular a um cliente do CRM

curl -X POST https://app.sonarbr.io/api/v1/whatsapp/contacts \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999998888",
    "custom_name": "João — TechStore",
    "tags": ["lead-quente"],
    "client_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

GET /v1/whatsapp/contacts/:id

Busca um contato específico.

PUT /v1/whatsapp/contacts/:id

Atualiza custom_name, notes, tags ou client_id. O telefone é imutável (recrie o contato se precisar mudar).

curl -X PUT https://app.sonarbr.io/api/v1/whatsapp/contacts/CONTACT_UUID \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["lead-quente", "convertido"] }'

DELETE /v1/whatsapp/contacts/:id

Remove o contato permanentemente. Retorna 409 CONFLICT se o contato tiver conversas vinculadas (para evitar perda acidental do histórico via cascade). Arquive ou remova as conversas antes.

curl -X DELETE https://app.sonarbr.io/api/v1/whatsapp/contacts/CONTACT_UUID \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Mensagens

POST /v1/whatsapp/messages

Envia uma mensagem de texto. A v1 suporta somente texto — para mídia, use a interface web ou o endpoint legado autenticado por sessão.

Request Body

Campo	Tipo	Obrigatório	Descrição
`content`	string	Sim	Texto da mensagem
`inbox_id`	uuid	Sim*	Inbox de origem
`phone`	string	Sim*	Telefone do destinatário (dígitos com DDI)
`conversation_id`	uuid	Sim*	Alternativa: conversa existente

* Você precisa informar (inbox_id + phone) ou apenas (conversation_id). Se a conversa ainda não existir para o par inbox_id + phone, ela é criada automaticamente.

Request

curl -X POST https://app.sonarbr.io/api/v1/whatsapp/messages \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": "INBOX_UUID",
    "phone": "5511999998888",
    "content": "Olá! Sua proposta está pronta, podemos conversar?"
  }'

Response

{
  "success": true,
  "data": {
    "id": "msg-uuid",
    "conversation_id": "conv-uuid",
    "inbox_id": "INBOX_UUID",
    "remote_jid": "5511999998888@s.whatsapp.net",
    "whatsapp_message_id": "ABC123",
    "direction": "outgoing",
    "message_type": "text",
    "content": "Olá! Sua proposta está pronta, podemos conversar?",
    "status": "sent",
    "created_at": "2026-05-18T10:32:00Z"
  }
}

O status inicial é sent. Confirmações de entrega/leitura chegam via webhook (whatsapp.message.status) à medida que o WhatsApp confirma.

Erros Comuns

Código	Erro	Causa
`400`	`VALIDATION_ERROR`	Falta `content`, `inbox_id`, `phone` ou `conversation_id`
`400`	`VALIDATION_ERROR`	Inbox inativa
`404`	`NOT_FOUND`	Inbox/contato/conversa não encontrado ou pertence a outro time
`409`	`CONFLICT`	DELETE em contato com conversas vinculadas
`502`	`BAD_GATEWAY`	Falha ao enviar pelo serviço WhatsApp (rede, sessão Baileys desconectada, Meta indisponível)

Limitações conhecidas (v1)

Sem suporte a mídia (image/audio/video/document).
Sem suporte a templates pré-aprovados da Cloud API.
Sem retry automático — se o serviço retornar 502, sua aplicação deve reenviar com backoff.
Rate limit segue o limite global de 60 req/min por IP.

On this page