Gestión de nombres de usuario y BSUID de WhatsApp

Esta guía te explica los cambios que debes realizar en tu integración de la Messages API de Vonage para que sea compatible con los nombres de usuario de WhatsApp y los BSUID.

Requisitos previos

Una aplicación de Vonage activa con la función «Mensajes» activada
An Account of WhatsApp Business (WABA) and a WhatsApp phone number linked to Meta and Vonage
Puntos finales de webhook configurados para mensajes entrantes y devoluciones de llamada de estado

Actualiza tus solicitudes de envío de mensajes

Ahora puedes enviar mensajes utilizando un BSUID, además de un número de teléfono o en lugar de este. El to Ahora, este campo admite tanto un número de teléfono como un BSUID para los destinatarios de WhatsApp.

Enviar únicamente a un número de teléfono (comportamiento actual, sin cambios):

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "message_type": "text", "to": "14155550123", "from": "14155559876", "text": "Hello!" }'

Enviar únicamente a un BSUID:

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "message_type": "text", "to": "US.13491208655302741918", "from": "14155559876", "text": "Hello!" }'

Importante: Cuando utilices un BSUID, incluye siempre el valor completo: el prefijo del código de país, el punto y todos los caracteres alfanuméricos. Si omites o modificas cualquier parte del BSUID, la solicitud fallará.

Gestionar la respuesta actualizada al envío del mensaje

La respuesta al mensaje de envío no ha cambiado. Para obtener más información, consulta el Especificaciones de la API «Enviar mensaje».

Actualiza el controlador de devolución de llamada (webhook) de tu estado

Las notificaciones de estado para los mensajes salientes enviados, entregados y leídos incluyen ahora un whatsapp.recipient objeto y un profile objeto con nuevos campos.

Carga útil actualizada de la llamada de retorno de estado:

{
  "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 nuevos y modificados:

Campo	Descripción
`profile.username`	El nombre de usuario de WhatsApp del usuario, si lo tiene. Se omite en el caso de los mensajes con estado «enviado» o si el usuario no tiene nombre de usuario.
`whatsapp.recipient.user_id`	El BSUID del usuario. Siempre está presente en los estados «entregado» y «leído».
`whatsapp.recipient.parent_user_id`	El BSUID principal del usuario. Solo aparece si tu empresa ha habilitado los BSUID principales.
`whatsapp.recipient.wa_id`	El número de teléfono del usuario. Se omite si el mensaje se ha enviado a un BSUID y no es posible incluir el número de teléfono.

Para failed llamadas de retorno de estado, recipient_user_id se omite si el mensaje se envió a un número de teléfono.

Actualiza tu gestor de mensajes entrantes (webhook)

Los webhooks de mensajes entrantes ahora incluyen un whatsapp.sender objeto y una versión actualizada profile objeto.

Carga útil actualizada de la llamada de retorno de mensajes entrantes:

{
  "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"
    }
  }
}

En from Este campo mostrará el número de teléfono del usuario, si está disponible. Si el número de teléfono no está disponible, se mostrará el BSUID en su lugar.

Campos nuevos y modificados:

Campo	Descripción
`profile.username`	El nombre de usuario de WhatsApp del usuario, si ha elegido uno. Se omite si el usuario no tiene nombre de usuario.
`whatsapp.sender.user_id`	El BSUID del usuario. Siempre está presente.
`whatsapp.sender.parent_user_id`	El BSUID principal del usuario. Solo aparece si tu empresa ha habilitado los BSUID principales.
`whatsapp.sender.wa_id`	El número de teléfono del usuario. Se omite si el usuario ha elegido un nombre de usuario y el número de teléfono no puede incluirse según las condiciones descritas anteriormente.

Solicitar el número de teléfono de un usuario (opcional)

Si tu integración requiere el número de teléfono de un usuario —por ejemplo, con fines de autenticación o verificación—, puedes solicitarlo directamente en la conversación. Hay dos formas de hacerlo: a través de un mensaje preaprobado mensaje de plantilla o a través de un mensaje interactivo.

Opción 1: Mensaje modelo con un botón para solicitar información de contacto

Primero debes crear y conseguir que se apruebe una plantilla de WhatsApp que incluya un REQUEST_CONTACT_INFO botón a través del API de gestión de plantillas de WhatsApp. Una vez aprobada, envía la plantilla mediante la Messages API de Vonage:

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_WABA_NUMBER", "to": "USERS_NUMBER", "channel": "whatsapp", "message_type": "custom", "custom": { "type": "template", "template": { "name": "YOUR_TEMPLATE_NAME", "language": { "policy": "deterministic", "code": "en" }, "components": [ { "type": "BODY", "parameters": [] }, { "type": "buttons", "buttons": [ { "type": "REQUEST_CONTACT_INFO", "text": "Share Contact Info" } ] } ] } } }'

Opción 2: Mensaje interactivo con un botón para solicitar información de contacto

También puedes solicitar un número de teléfono dentro de una ventana de conversación activa mediante un mensaje interactivo, sin necesidad de utilizar una plantilla preaprobada:

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_WABA_NUMBER", "to": "USERS_NUMBER", "channel": "whatsapp", "message_type": "custom", "custom": { "type": "interactive", "interactive": { "type": "request_contact_info", "body": { "text": "Please share your phone number with us to continue." }, "action": { "name": "request_contact_info" } } } }'

Más información

Qué hay que saber sobre los nombres de usuario y los BSUID de WhatsApp

Navegación