Referência da API

Antes de tudo

O login é a única chamada sem headers. Todas as outras levam os dois.

Erros

Todo erro tem o mesmo corpo:

{
  "status": "error",
  "message": "descrição do erro",
  "details": [{ "path": "campo", "error_type": "tipo", "message": "descrição" }]
}

details só aparece em 422.

Autenticação

POST /authentication

Quando usar: no início da integração e sempre que o token expirar. É a única chamada pública.

Corpo

201 — { user_id, token, role }. O token vai no header authorization das demais chamadas.

401 — "User/Password does not exists or is wrong." ou "User is disabled.".

Templates

Guia com exemplos: enviar templates.

GET /template

Quando usar: para saber quais templates existem e quais já foram aprovados — só um template approved pode ser enviado.

Query

200 — lista de templates. Cada um: identifier, name, namespace, language, status, category, components, quality_score e rejected_reason (quando recusado).

POST /template

Quando usar: para criar um template novo. Ele nasce pending e precisa ser aprovado pela Meta antes do primeiro envio.

Corpo

201 — o template criado, com status: "pending".

Erros: corpo inválido responde 401 (a validação do template acontece antes do broker); erro do broker vira 400, indisponibilidade vira 502 ou 504.

POST /template/media-handle

Quando usar: antes de criar um template cujo header é imagem, vídeo ou PDF. Devolve o handle que vai no componente de header.

Corpo: multipart, campo file.

201 — { handle }.

Erros: 400 sem arquivo ("File is required") ou com tipo não suportado; 422 acima de 25 MB.

DELETE /template

Quando usar: para remover um template que você não vai mais enviar.

Query: template_id.

201 — corpo vazio.

Número

Guia com exemplos: gerenciar o número.

Todas as chamadas abaixo exigem o header identifier; sem ele, 400 ("Identifier was not sent").

GET /phones/info

Quando usar: para ler o estado do número — para onde os webhooks vão, a qualidade e o limite atuais.

200

Credenciais do broker nunca aparecem aqui. 404 — "Phone does not exists".

GET /phones/info/history

Quando usar: para auditar quedas de qualidade ou de tier ao longo do tempo.

200 — lista de { eventDate, number, identifier, history: [{ event, from, to }] }.

GET /phones/webhook

Quando usar: para conferir qual URL está configurada agora.

200 — os mesmos campos de GET /phones/info. 404 — "Identifier not found."

PUT /phones/webhook

Quando usar: ao apontar (ou trocar) a URL que recebe mensagens e status. Passa a valer nas próximas entregas.

Corpo: { "webhook": string }.

200. 400 — "Error updating webhook" (URL inválida).

GET /phones/profile-image

Quando usar: para baixar a foto atual do perfil.

200 — binário, content-type: image/jpeg. Não é JSON.

PUT /phones/profile-image

Quando usar: para trocar a foto do perfil.

Corpo: multipart, campo photo.

200 — true. 400 — "Image was not sent".

GET /phones/about

Quando usar: para ler o perfil comercial exibido no WhatsApp.

200 — { address, description, email, websites: string[], vertical, about }. 404 — "Profile not found."

PATCH /phones/about

Quando usar: para atualizar o perfil. Todos os campos são opcionais — mande só o que muda.

Corpo: address, description, email, websites, vertical, about: { text }.

200 — true.

GET /phones/public_key

Quando usar: para conferir a chave pública do número e o estado da assinatura dela.

200 — { business_public_key, business_public_key_signature_status }. 400 — qualquer falha na leitura.

POST /phones/public_key

Corpo: { "publicKey": string }.

200 — true. 400 — "Error updating publicKey".

GET /phones/security_key

Quando usar: para saber com qual segredo os seus webhooks são assinados — e de onde ele vem.

200

404 quando o número não existe.

PUT /phones/security_key

Quando usar: ao definir ou rodar o segredo de assinatura. Leia rotação da chave antes de virar em produção.

Corpo: { "security_key": string | null } — obrigatório.

200 — { identifier, security_key, source }.

422 — string fora da faixa de tamanho.

503 — a chave foi gravada, mas o cache não pôde ser invalidado: a antiga ainda está assinando. Repita a chamada; é seguro repetir.

Envio

Guia com exemplos de todos os tipos: enviar mensagens.

POST /message/

Host: https://message.2bebandmaster.com.br (não o de gestão).

Quando usar: para enviar qualquer mensagem — texto, mídia, localização, contatos, template, interativa ou o indicador de digitação.

Corpo: uma mensagem, ou { "batch": [ ...mensagens ] } para várias (recomendado até 10 por lote; não é imposto).

200 — aceito e enfileirado, não entregue: { index, message, message_id } (lista, no caso de batch). O destino da mensagem chega depois por webhook.

Erros: 422 validação do corpo (e header authorization/identifier ausente) — o corpo do erro traz errors[], e o campo status dentro dele vale 400 mesmo assim: confie no código HTTP; 400 destinatário inválido, template_id que não é um ObjectId de 24 hex, identifier sem número correspondente, ou fila indisponível; 401 token mal formado, inválido ou expirado; 500 erro nosso. Não há 429.

Receber

Nada a chamar: mensagens, status e falhas chegam por webhook na URL do número.