WhatsApp

Use a API para administrar contatos e enviar mensagens de texto por inboxes WhatsApp já conectadas. A API v1 não cria inboxes; conecte e administre os canais pelo painel.

Todos os endpoints desta página usam a base URL https://app.usecolmeia.com/api/v1 e autenticação Bearer.

Contatos

GET /whatsapp/contacts

Lista os contatos WhatsApp do time associado à chave de API.

Parâmetro	Tipo	Descrição
`page`	number	Página atual; padrão `1`.
`limit`	number	Itens por página; padrão `20`, máximo `100`.
`tag`	string	Filtra contatos que contenham a tag.
`client_id`	uuid	Filtra pelo cliente CRM vinculado.
`search`	string	Busca em `phone`, `custom_name` e `push_name`.
`sort`	string	`push_name`, `custom_name`, `phone`, `created_at` ou `updated_at`; use `-` para ordem descendente.

curl "https://app.usecolmeia.com/api/v1/whatsapp/contacts?search=ana&sort=-created_at" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Cria um contato ou recupera a identidade equivalente que já exista. O campo phone aceita um número brasileiro local inequívoco ou um número com DDI; a API remove a formatação e o normaliza para dígitos com DDI antes de persistir. Para números fora do Brasil, envie o formato internacional com DDI.

Quando uma variante brasileira do mesmo número já estiver cadastrada, a resposta devolve o contato existente com reused: true, em vez de criar um duplicado.

Campo	Tipo	Obrigatório	Descrição
`phone`	string	Sim	Telefone local BR inequívoco ou número com DDI.
`custom_name`	string	Não	Nome de exibição interno.
`notes`	string	Não	Anotações privadas.
`tags`	string[]	Não	Tags do contato.
`client_id`	uuid	Não	Cliente CRM a vincular.

curl -X POST "https://app.usecolmeia.com/api/v1/whatsapp/contacts" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+55 11 99999-8888",
    "custom_name": "Ana - Empresa Exemplo",
    "tags": ["lead-quente"],
    "client_id": "11111111-1111-4111-8111-111111111111"
  }'

GET /whatsapp/contacts/:id

Obtém um contato pelo UUID. O recurso só é retornado quando pertence ao time da chave de API.

PUT /whatsapp/contacts/:id

Atualiza somente custom_name, notes, tags e client_id. O telefone e o jid não são atualizáveis. Envie ao menos um desses campos.

curl -X PUT "https://app.usecolmeia.com/api/v1/whatsapp/contacts/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["lead-quente", "convertido"] }'

DELETE /whatsapp/contacts/:id

Exclui o contato permanentemente. Se houver conversas vinculadas, a API retorna 409 CONFLICT para impedir a remoção acidental do histórico.

curl -X DELETE "https://app.usecolmeia.com/api/v1/whatsapp/contacts/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Mensagens

POST /whatsapp/messages

Envia uma mensagem de texto. A v1 aceita somente texto e requer uma destas combinações:

content e conversation_id; ou
content, inbox_id e phone.

Com conversation_id, a API usa a inbox e o destinatário da conversa existente. Com inbox_id e phone, a API localiza uma conversa existente — inclusive em variantes brasileiras equivalentes — ou cria uma conversa quando o canal permitir.

Campo	Tipo	Obrigatório	Descrição
`content`	string	Sim	Corpo textual da mensagem.
`conversation_id`	uuid	Condicional	Conversa existente; dispensa `inbox_id` e `phone`.
`inbox_id`	uuid	Condicional	Inbox de origem quando `phone` for informado.
`phone`	string	Condicional	Destinatário local BR inequívoco ou com DDI quando não houver `conversation_id`.

curl -X POST "https://app.usecolmeia.com/api/v1/whatsapp/messages" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": "22222222-2222-4222-8222-222222222222",
    "phone": "+55 11 99999-8888",
    "content": "Olá! Sua proposta está pronta."
  }'

Janela de atendimento da Cloud API

Em uma inbox cloud_api, o envio de texto fora da janela de atendimento de 24 horas retorna 409 com o código customer_service_window_closed. Envie um template aprovado para reabrir a conversa; a API v1 não envia templates.

Erros comuns

Status	Código	Quando ocorre
`400`	`VALIDATION_ERROR`	Corpo inválido, telefone inválido, parâmetros de envio incompletos ou inbox inativa.
`404`	`NOT_FOUND`	Contato, conversa ou inbox inexistente ou de outro time.
`409`	`CONFLICT`	Tentativa de excluir contato com conversas vinculadas.
`409`	`customer_service_window_closed`	Texto enviado por Cloud API fora da janela de 24 horas.
`502`	`BAD_GATEWAY`	Falha no provedor ou serviço WhatsApp. O resultado não garante que a mensagem não tenha sido aceita pelo provedor nem persistida localmente.
`500`	`INTERNAL_ERROR`	O provedor aceitou a mensagem, mas a persistência local falhou: `Mensagem enviada, mas falha ao salvar no banco`.

Limitações da v1

Somente mensagens de texto; mídia e templates não são enviados por este endpoint.
Um 502 deve ser tratado como resultado incerto. Antes de reenviar, verifique o estado da conversa para evitar duplicidade.
A API não oferece chave de idempotência para o envio. Após o 500 de persistência, reconcilie a conversa e o provedor antes de reenviar: a mensagem pode já ter sido entregue e uma nova tentativa pode duplicá-la.