Saltar para o conteúdo principal
Uma conversa é o thread de WhatsApp entre o seu negócio e um contato. Quase todos os endpoints de envio e de ações (/conversation/*) a recebem no corpo da requisição sob o objeto conversation.

​
Identificar uma conversa

O objeto conversation aceita um de quatro identificadores. O resolver avalia nesta ordem: uuid → whatsapp_user_id → username → phone: whatsapp_user_id busca por igualdade exata e username por igualdade case-insensitive (ignora maiúsculas); phone é normalizado para dígitos. Quando o contato tem BSUID, phone e whatsapp_user_id identificam valores distintos (veja Note).
​
uuid
string
O UUID de um GET /conversations. O caminho mais direto e estável (pode ficar obsoleto se duas conversas do mesmo contato forem unificadas — veja a nota de unificação abaixo).
​
whatsapp_user_id
string
O BSUID do contato (identidade opaca do Meta). Resolve por igualdade exata contra o BSUID armazenado; se não resolver, o endpoint responde 404 sem cair para phone. Identificador recomendado daqui em diante.
​
username
string
Username público de WhatsApp do contato, com ou sem @ inicial e sem distinguir maiúsculas. Resolução best-effort contra o último username observado pela plataforma (o usuário pode mudar seu handle); se vários contatos o compartilham, o endpoint responde 409 (USERNAME_AMBIGUOUS).
​
phone
string
Número no formato E.164 (+5215512345678). É normalizado para dígitos antes do lookup. Útil quando você só tem o telefone.
O telefone pode estar duplicado entre contatos (números reciclados ou identidades separadas que compartilham o número): nesse caso a API responde 409 (PHONE_NUMBER_AMBIGUOUS) em vez de adivinhar — identifique a conversa por whatsapp_user_id ou uuid. Além disso, whatsapp_user_id pode mudar se o usuário registrar novamente sua conta de WhatsApp (rotação de identidade do lado do Meta). Use o uuid como chave estável no seu sistema e whatsapp_user_id como identificador de resolução preferencial.
phone e whatsapp_user_id são identificadores distintos: phone é o telefone (wa_id sem +) e whatsapp_user_id é o BSUID do contato. Coincidem apenas enquanto o contato não tem BSUID. Nas respostas, whatsapp_user_id retorna o BSUID real quando existe, com fallback para o telefone para que sempre haja um valor resolvível. Atenção no round-trip: se o contato ainda não tem BSUID, este campo traz o telefone; reenvie-o então como phone, não como whatsapp_user_id — o resolver casa whatsapp_user_id por igualdade exata e responderia 404.
Quando o mesmo contato acabou registrado duas vezes por identidade (por exemplo, primeiro só com o telefone e depois com o BSUID), as duas conversas são unificadas automaticamente em uma só: todo o histórico passa para a sobrevivente. O uuid da conversa absorvida deixa de resolver e responde 404; o telefone e o BSUID migram para a sobrevivente. Se um uuid que você guardou começar a dar 404, resolva a conversa novamente por phone ou whatsapp_user_id.

​
A janela de 24h

É o conceito central do WhatsApp e decide o que você pode enviar.
1

O contato te escreve

O WhatsApp abre uma janela de 24 horas. Cada nova mensagem do contato reinicia o contador.
2

Janela aberta

Você pode enviar mensagens livres: texto, mídia e quick replies.
3

Passam 24h sem resposta

A janela se fecha. A única mensagem permitida é um template aprovado pelo Meta.
4

Enviar um template reabre a janela

Você volta a poder enviar mensagens livres.
Enviar texto, mídia ou quick reply com a janela fechada falha com WINDOW_CLOSED (422). Envie um template primeiro para reabri-la.

​
Consultar o estado da janela

Antes de enviar uma mensagem livre, você pode verificar se a janela está aberta com POST /conversation/status:
A resposta inclui window.status (open ou closed) e window.hours_remaining, além do estado de atribuição, caixa de entrada, tags e inbox_status da conversa. Use-o para decidir entre uma mensagem livre e um template.

​
Próximos passos

Enviar mensagens

Texto, mídia, quick replies e templates.

Templates

Como enviar templates com a janela de 24h fechada.