BIRD WHATSAPP CENTRAL · API v1

Conecte seu sistema ao WhatsApp.

Uma API independente para CRMs, sites e aplicações. Cada integração recebe sua própria chave, cota de números e webhook. O sistema que você escolher controla o atendimento.

Baixar contrato OpenAPI · Consultar disponibilidade

Esta central não executa IA nem responde automaticamente. Nenhum número vem conectado. O titular conecta seu aparelho pelo QR e a aplicação autoriza os contatos que poderão ser processados.

Como integrar

  1. Solicite ao operador uma credencial exclusiva. Guarde a chave no servidor da sua aplicação.
  2. Use a URL deste site com o prefixo /v1 e o cabeçalho Authorization: Bearer SUA_CHAVE.
  3. Crie uma instância com POST /v1/instances e {"name":"Atendimento"}. A resposta contém o id.
  4. Solicite POST /v1/instances/{id}/connect e consulte GET /v1/instances/{id}/qr. Renderize o texto retornado como QR no seu sistema para o titular escanear.
  5. Autorize cada contato com PUT /v1/instances/{id}/contacts/{phone}, corpo {"consent":true,"reference":"seu-id"}. Telefone internacional, de 10 a 15 dígitos. Use DELETE na mesma rota para revogar.
  6. Receba eventos pelo webhook HTTPS ou consulte GET /v1/instances/{id}/events?after=0&limit=50. A resposta informa o próximo cursor.

Exemplo de chamada pelo seu servidor

const response = await fetch(process.env.BIRD_URL + '/v1/instances', {
  headers: { Authorization: 'Bearer ' + process.env.BIRD_KEY }
});
if (!response.ok) throw new Error('Bird HTTP ' + response.status);
const { data } = await response.json();

Autorização pelo seu CRM

Como alternativa ao cadastro de contatos na central, configure PUT /v1/admission com {"url":"https://seu-crm.exemplo/autorizacao"}. Seu backend recebe {id,instanceId,phone} assinado com seu segredo de webhook e responde {"allowed":true} somente para um lead autorizado. A consulta ocorre antes de cada processamento, sem cache. Falha ou timeout bloqueiam o processamento; o cadastro da central não sobrepõe essa decisão. URL vazia restaura o cadastro explícito.

Envios e eventos

Para enviar, use POST /v1/instances/{id}/messages com Idempotency-Key exclusivo e corpo {"to":"TELEFONE","text":"Mensagem aprovada","consent":true}. O contato precisa estar autorizado. HTTP 202 significa entrada na fila; consulte o job retornado para acompanhar. Um resultado needs_review exige conferência antes de qualquer nova tentativa.

Configure seu destino com PUT /v1/webhook e {"url":"https://seu-sistema.exemplo/hooks/bird"}. Valide x-bird-signature com HMAC-SHA256 do segredo exclusivo sobre timestamp + '.' + corpo JSON original, confira x-bird-timestamp e deduplique x-bird-event-id. Eventos podem ser repetidos; responda 2xx depois de recebê-los com segurança.

Operação

As chamadas autenticadas devem sair do seu backend. Cada chave acessa somente suas instâncias e eventos. Consulte GET /v1/capacity para sua cota. Mensagens de contatos não autorizados são descartadas antes da leitura do corpo. Eventos e mídia têm retenção de 72 horas.

A capacidade com aparelhos reais depende do uso. O servidor atual tem 4 GB; aumente os números conectados gradualmente.