Guía de migración de WhatsApp v0.1 a v1

Actualmente existen dos versiones de la Messages API: v0.1 y v1. Aunque la v1 es compatible con todas las funciones de la v0.1, existen algunas diferencias significativas entre ambas versiones que debe tener en cuenta si ya utiliza la v0.1 de la API y tiene previsto migrar a la v1.

Estructura JSON

Una de las diferencias más importantes entre las dos versiones es la estructura utilizada para los datos JSON en las peticiones a la API y para los datos de webhooks entrantes; la v1 proporciona una estructura simplificada y más plana. Para que tu aplicación funcione con v1, será necesario cambiar cualquier código que genere o haga referencia a los datos JSON.

Algunas de las diferencias entre ambas estructuras son:

• to y from son nodos de valor único en lugar de un objeto
• La mensajería channel sólo necesita especificarse una vez en lugar de especificarse como un type en to y from
• En message ha sido sustituido por un objeto message_typey un único nodo de valor con el tipo de contenido implícito en la etiqueta, por ejemplo "text": "this is a text"

Ejemplos

Texto saliente de WhatsApp V0.1

{
  "to": {
    "type": "whatsapp",
    "number": "447700900000"
  },
  "from": {
    "type": "whatsapp",
    "number": "447700900001"
  },
  "message": {
    "content": {
      "type": "text",
      "text": "Hello From Vonage!"
    }
  }
}

Texto saliente de WhatsApp V1

{
  "message_type": "text",
  "text": "Hello From Vonage!",
  "to": "447700900000",
  "from": "447700900001",
  "channel": "whatsapp"
}

Webhook de texto entrante de WhatsApp v0.1

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z",
  "to": {
    "type": "whatsapp",
    "number": "447700900000"
  },
  "from": {
    "type": "whatsapp",
    "number": "447700900001"
  },
  "message": {
    "content": {
      "type": "text",
      "text": "Hello From Vonage!"
    }
  }
}

Webhook de texto entrante de WhatsApp v1

{
  "channel": "whatsapp",
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2020-01-01 14:00:00 UTC",
  "message_type": "text",
  "text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
  "profile": {
    "name": "Jane Smith"
  },
  "context": {
    "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
    "message_from": "447700900000"
  }
}

Estos son algunos ejemplos. Compruebe el especificación para obtener un conjunto completo de campos para los distintos tipos de mensajes y webhooks.

Uso de Vonage Applications para Webhooks

Si utiliza webhookspara v1 deben configurarse dentro de un Aplicación de Vonage. Además, la Aplicación debe estar configurada para utilizar v1 como versión.

Un flujo de trabajo básico para configurar esto a través de la función Cuadro de mandos sería la siguiente:

1. Cree una nueva aplicación en Sus aplicaciones (dándole un nombre apropiado, etc.)
2. En Capacidades, active Mensajes
3. La activación de Mensajes debería exponer campos para webhooks de entrada y de estado. Establezca el webhook de entrada en la URL en la que desea recibir las devoluciones de llamada de los mensajes interactivos de WhatsApp.
4. Establezca la versión de Messages API en v1 mediante el menú desplegable
5. Haga clic en Generar nueva solicitud

Uso de JWT para autenticación si se utiliza una aplicación de Vonage

Si estás configurando una aplicación de Vonage, algo importante que debes tener en cuenta es que las aplicaciones de Vonage exigen el uso de JWT (JSON Web Tokens) para autenticar las solicitudes a la API. En otras palabras, la autenticación HTTP Basic no es una opción en esta situación. Más información sobre los JWT.

Vinculación de Numbers y canales sociales a las aplicaciones de Vonage

Si deseas que ciertos números y canales sociales estén disponibles para una aplicación de Vonage, debes vincular esos números y canales sociales a la aplicación. Esto puede hacerse a través de la función Cuadro de mandos. Desde el Página de ApplicationsSelecciona la aplicación que deseas vincular; puedes vincular Numbers a la aplicación en la pestaña "Vincular Numbers", y vincular canales sociales en la pestaña "Vincular canales sociales".

Características adicionales

Una de las razones por las que podría querer migrar a la v1 si actualmente está utilizando la v1, es para aprovechar algunas de las características adicionales que ofrece v1, por ejemplo Mensajes interactivos de WhatsApp.