Skip to main content

​
O campo phone

Em toda a API, phone identifica o chat, não necessariamente um telefone: Regras para números: sem +, espaços, parênteses ou traços; DDI obrigatório (55 para o Brasil). A API aceita o celular brasileiro com e sem o nono dígito, mas o WhatsApp pode registrar o contato de um jeito só. Veja a seguir como o Wabox acerta o número.

​
Número certo no envio

Contas de WhatsApp criadas antes de 2016 ainda podem estar registradas sem o nono dígito. Mandar para a outra forma do número falha com phone_not_on_whatsapp.
  • verify_phone: true em qualquer envio de mensagem nova: o Wabox confere o número no WhatsApp antes de enviar e manda para o número em que ele está registrado. Sem conta no WhatsApp, o envio falha com phone_not_on_whatsapp no delivery, sem tentar enviar.
  • Cache: o número conferido fica guardado por 30 dias, renovados a cada uso. Enquanto ele estiver guardado, todo envio para esse número vai para o número certo, mesmo sem verify_phone. Um número conferido por GET /phone-exists/{phone} também entra no cache.
  • Sem verify_phone e sem o número no cache, o Wabox não consulta nada: a mensagem vai para o número como você mandou.
  • O delivery mantém o phone como você mandou e traz o número usado em canonical_phone. Os webhooks received e message_status dessa conversa chegam com o canonical_phone, então use-o para ligar as respostas à conversa certa.
Consultar números no WhatsApp tem custo: muitas consultas em pouco tempo são um sinal de risco para o número. Prefira verify_phone no primeiro envio para um contato, não em todos.

​
LID

O WhatsApp está migrando de identificadores baseados no telefone para LIDs (linked identifiers): um número opaco por conta (98765432109876@lid) que não revela o telefone. Hoje os dois convivem. O WhatsApp entrega alguns eventos identificados por LID, principalmente em grupos e para contatos que ativaram a proteção do número. Na prática:
  • O webhook received pode trazer chat_lid, sender_lid e participant_lid além de phone/participant_phone. Guarde os dois.
  • Em conversas privadas, quando o WhatsApp só informa o LID, o Wabox busca o número no mapa LID → número que a sessão já aprendeu e manda o número em phone (o LID continua em chat_lid). Em raros casos o número ainda não é conhecido e phone (ou participant_phone) chega no formato LID. Use o LID como destino: todos os endpoints aceitam xxx@lid em phone.
  • GET /contacts/{phone} e GET /phone-exists/{phone} devolvem lid quando ele é conhecido e aceitam LID como entrada. Use-os para converter de um lado para o outro.
  • Não trate o LID como chave permanente: o WhatsApp pode reatribuí-lo em situações como troca de número. Use phone como a chave de negócio e o LID como identificador auxiliar.

​
Grupos

Ids de grupo aparecem como <id>-group em toda a API e nos webhooks. O <id> costuma ser um timestamp de criação com dígitos extras (120363012345678901); grupos antigos podem ter o formato <criador>-<timestamp>-group. Use exatamente o que a API devolveu.
  • Criar: POST /groups devolve o id.
  • Descobrir por link de convite: GET /groups/invite-info?invite=https://chat.whatsapp.com/....
  • Dentro do grupo, quem enviou está em participant_phone / participant_lid.

​
Canais

O id de um canal é <id>@newsletter. Para publicar, use qualquer send-* com esse id em phone (você precisa ser admin do canal). Reações e leitura têm endpoints próprios em Canais.

​
Mensagens

message_id é uma string opaca escolhida pelo remetente. Para mensagens enviadas pela API, o Wabox gera um id no formato do WhatsApp Web (3EB0 + 18 hex) e o devolve na resposta antes de enviar. É o mesmo id em delivery, message_status e reference_message_id. Ids de mensagens recebidas vêm no formato do aparelho de quem enviou e podem ter outro tamanho.

​
Usar o seu próprio id

Todo envio que cria uma mensagem nova (send-text, mídias, contato, localização, link, enquete, encaminhar, interativos, produto…) aceita custom_message_id: o Wabox envia a mensagem ao WhatsApp com esse id, e ele passa a ser o message_id da resposta, do delivery, do message_status e das respostas e reações de quem recebe. Serve para manter os ids do seu sistema, por exemplo ao migrar de uma integração Baileys que já escolhia o id (messageId).
  • Qualquer formato de 1 a 128 caracteres ASCII visíveis, sem espaços (cp_123, 3EB0…, um UUID…).
  • O id é único por instância. Se ele já pertencer a uma mensagem na fila ou enviada, a resposta é 409 duplicate_message_id, com o wabox_id do envio existente em details, porque o WhatsApp de quem recebe descartaria a segunda mensagem como duplicada. O id de um envio que falhou (webhook delivery com error_code) pode ser reutilizado para tentar de novo.
  • Ações não aceitam custom_message_id: edições (edit_message_id), reações, pins e apagar respondem com o message_id da mensagem referenciada, e o delivery delas traz o mesmo id com operation (edit, reaction, delete…). Veja Falha de uma ação. Voto em enquete e resposta a evento também não aceitam.

​
id, message_id, wabox_id, event_id