Guía de migración de WhatsApp de la versión 0.1 a la versión 1

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
• El mensaje channel sólo necesita especificarse una vez en lugar de especificarse como un type en to y from
• El 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

Mensaje saliente de WhatsApp V0.1

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

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

Los anteriores son algunos ejemplos. Consulta el especificación para consultar un conjunto completo de campos para los distintos tipos de mensajes y webhooks.

Uso de las aplicaciones de Vonage para webhooks

Si utilizas webhooks, en la versión 1, estos deben configurarse dentro de un Aplicación de Vonage. Además, las aplicaciones deben configurarse para utilizar la versión v1.

Un proceso básico para configurarlo a través de la Panel de control 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. Al habilitar los mensajes, deben aparecer los campos correspondientes a los webhooks de entrada y de estado. Configura el webhook de entrada con la URL en la que deseas recibir las respuestas 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 Panel de control. De la 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 quizá te interese migrar a la v1, si actualmente utilizas la v1, es para aprovechar algunas de las características adicionales que ofrece v1, por ejemplo Mensajes interactivos de WhatsApp.