Pular para o conteúdo
apiwpp
Termo

O que é JID no WhatsApp

JID (Jabber ID) é o endereço interno que o WhatsApp usa para cada conversa: um contato é algo como [email protected], um grupo termina em @g.us e um contato identificado sem telefone termina em @lid.

Atualizado em

JID é o endereço interno de uma conversa no WhatsApp. A sigla vem de Jabber ID, herança do protocolo de mensagens em que o WhatsApp se baseou. Para quem usa o aplicativo, um contato é um número de telefone; por dentro, cada mensagem é endereçada a um JID, que junta um identificador e um domínio depois da arroba.

Os formatos de JID

Numa integração com o WhatsApp, você vai encontrar três formatos:

FormatoExemploO que é
@s.whatsapp.net[email protected]Um contato identificado pelo telefone, com código do país e DDD
@g.us[email protected]Um grupo
@lid11122233344455@lidUm contato identificado sem revelar o telefone (veja LID)

O primeiro formato parece o número com um sufixo, e é daí que vem o erro mais comum: achar que basta pegar o telefone do cadastro, tirar os símbolos e colar @s.whatsapp.net no fim.

Número de telefone não é o mesmo que JID

O JID de um contato é o número como o WhatsApp o registrou, que nem sempre é o número que está no seu cadastro. O caso clássico no Brasil é o nono dígito: contas antigas de celular podem estar registradas sem o 9, e o JID delas é [email protected], mesmo que o cliente informe 21 97777-6666. Montar o JID na mão com o 9 aponta para um endereço que não existe.

Por isso a apiwpp não pede que você monte o JID. No envio, o campo to recebe só dígitos, com país e DDD, e a apiwpp pergunta ao WhatsApp em qual JID aquele número está registrado antes de enviar:

{ "to": "5521977776666", "message": "Olá! Seu pedido saiu para entrega." }

Ela nunca inclui nem remove o nono dígito por conta própria: usa a resposta do WhatsApp. Se o número não está no WhatsApp, o envio falha na hora com not_on_whatsapp. Para conferir uma lista antes, a verificação de números consulta até 100 telefones por chamada e devolve o jid de cada um que existe.

Quando você já tem o JID, por exemplo porque ele veio num webhook, o campo to também aceita o JID completo (…@s.whatsapp.net, …@lid ou um grupo …@g.us), e ele é usado como veio.

Os campos jid e phone nos eventos

Todo evento de uma conversa individual que a apiwpp envia ao seu webhook traz dois campos de endereço:

{
  "type": "message.delivery",
  "data": {
    "messageId": "3EB0C767D26A1D8A3F52",
    "status": "delivered",
    "jid": "[email protected]",
    "phone": "+5511988887777"
  }
}

Em mensagens de grupo, jid é o grupo e phone é sempre null. E quando o contato chega como @lid, phone pode vir null até que o telefone seja descoberto; nesse momento o projeto recebe o evento contact.resolved. Os detalhes estão no verbete LID.

Na prática, use o jid como chave da conversa no seu sistema e o phone para mostrar e cruzar com o cadastro. Se o seu cadastro guarda o número com o nono dígito, compare os dois formatos ao procurar o contato.

Perguntas frequentes

Preciso montar o JID para enviar uma mensagem pela apiwpp?

Não. Envie o número só com dígitos, com código do país e DDD, no campo to. A apiwpp descobre em qual JID o número está registrado e envia para ele. Se preferir, o campo também aceita um JID completo.

Por que o JID que recebi no webhook não tem o nono dígito?

Porque aquela conta foi registrada no WhatsApp sem o 9, e o JID reflete o registro. A apiwpp não altera o número: phone mostra o telefone como o WhatsApp o conhece.

Qual campo devo usar como identificador do contato?

O jid, que está sempre presente e é estável. O phone pode ser null para contatos que chegam como LID e para mensagens de grupo.

LID (linked identity) é um identificador do WhatsApp, como 11122233344455@lid, que representa um contato sem revelar o número de telefone. É estável para o contato, mas não tem relação com o telefone.

O nono dígito é o 9 que os celulares brasileiros ganharam na frente do número. Contas de WhatsApp antigas podem continuar registradas sem ele, e uma mensagem enviada ao endereço com o 9 não chega até elas.

Webhook é uma chamada HTTP que um serviço faz para um endereço do seu sistema quando um evento acontece, como uma mensagem recebida. Em vez de perguntar de tempos em tempos se há novidades, o seu sistema é avisado na hora.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.