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). O nono dígito do celular brasileiro é aceito com e sem, mas o WhatsApp pode registrar o contato de um jeito só — se phone_not_on_whatsapp aparecer, confira com GET /phone-exists/{phone}, que devolve o canonical_phone.

​
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. O que isso significa para você:
  • O webhook received pode trazer chat_lid, sender_lid e participant_lid além de phone/participant_phone. Guarde os dois.
  • Em raros casos, phone (ou participant_phone) chega só no formato LID, porque o WhatsApp não informou o número. Nesses casos, use o LID como destino: todos os endpoints aceitam xxx@lid em phone.
  • GET /contacts/{phone} e GET /phone-exists/{phone} devolvem lid quando conhecido, e aceitam LID como entrada — use para resolver de um lado para o outro.
  • Não trate o LID como chave permanente absoluta: o WhatsApp pode reatribuir em situações como troca de número. Trate 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

<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.

​
id, message_id, wabox_id, event_id