Como lidar com nomes de usuário e BSUIDs do WhatsApp

Este guia explica as alterações que você precisa fazer na integração da Messages API do Vonage para oferecer suporte a nomes de usuário do WhatsApp e BSUIDs.

Pré-requisitos

• Um aplicativo Vonage ativo com o recurso “Mensagens” ativado
• Um Account do WhatsApp Business (WABA) e um número de telefone do WhatsApp vinculado à Meta e à Vonage
• Endpoints de webhook configurados para mensagens recebidas e retornos de chamada de status

Atualize suas solicitações de envio de mensagens

Agora você pode enviar mensagens usando um BSUID, além de um número de telefone ou em vez dele. O to Agora, esse campo aceita tanto um número de telefone quanto um BSUID para destinatários do WhatsApp.

Enviar apenas para um número de telefone (comportamento atual, inalterado):

Enviar apenas para um BSUID:

Tratar a resposta atualizada do envio da mensagem

A resposta à mensagem de envio permanece inalterada. Para mais detalhes, consulte o Especificação da API “Enviar mensagem”.

Atualize seu manipulador de retorno de chamada de status (webhook)

Os callbacks de status para mensagens enviadas, entregues e lidas agora incluem um whatsapp.recipient objeto e um profile objeto com novos campos.

Carga útil atualizada da chamada de retorno de status:

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "status": "read",
  "channel": "whatsapp",
  "profile": {
    "name": "John Smith",
    "username": "johnSmith"
  },
  "usage": { "currency": "EUR", "price": "0" },
  "whatsapp": {
    "pricing": {
      "type": "regular",
      "pricing_model": "CBP",
      "category": "service"
    },
    "recipient": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    },
    "conversation": {
      "id": "1234567890",
      "origin": { "type": "marketing" }
    }
  }
}

Campos novos e alterados:

Para failed callbacks de status, recipient_user_id é omitido se a mensagem tiver sido enviada para um número de telefone.

Atualize seu manipulador de mensagens recebidas (webhook)

Os webhooks de mensagens recebidas agora incluem um whatsapp.sender objeto e uma versão atualizada profile objeto.

Carga útil atualizada do callback de mensagens recebidas:

{
  "channel": "whatsapp",
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "profile": {
    "name": "Jane Smith",
    "username": "janeSmith"
  },
  "message_type": "text",
  "text": "Hello from Vonage!",
  "whatsapp": {
    "sender": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    }
  }
}

O from O campo conterá o número de telefone do usuário, caso esteja disponível. Se o número de telefone não estiver disponível, o BSUID será exibido em seu lugar.

Campos novos e alterados:

Solicitar o número de telefone de um usuário (opcional)

Se a sua integração exigir o número de telefone de um usuário — por exemplo, para fins de autenticação ou verificação —, você pode solicitá-lo diretamente na conversa. Há duas maneiras de fazer isso: por meio de um modelo de mensagem ou por meio de um mensagem interativa.

Opção 1: Mensagem modelo com um botão para solicitação de informações de contato

Primeiro, você deve criar e obter a aprovação de um modelo do WhatsApp que inclua um REQUEST_CONTACT_INFO botão por meio do API de gerenciamento de modelos do WhatsApp. Após a aprovação, envie o modelo usando a Messages API do Vonage:

Opção 2: Mensagem interativa com um botão para solicitação de informações de contato

Você também pode solicitar um número de telefone em uma janela de conversa ativa por meio de uma mensagem interativa, sem a necessidade de um modelo pré-aprovado:

Mais informações

Entendendo os nomes de usuário e os BSUIDs do WhatsApp