Migración del envío a la conmutación por error de mensajes

En esta guía se compara la funcionalidad de la Dispatch API con la funcionalidad de la función Failover de la aplicación Messages APIy describe algunos aspectos que deben tenerse en cuenta al migrar de la Dispatch API a la funcionalidad de conmutación por error de la Messages API.

Concepts généraux

A nivel conceptual general, la Dispatch API y la función Failover de la Messages API son muy similares. Ambas cosas te permiten:

  • Especifique un mensaje inicial, con mensaje(s) alternativo(s) que se enviará(n) en caso de que el mensaje inicial no se entregue.
  • Fail over entre diferentes tipos de mensajes.
  • Fail over entre diferentes canales de mensajería.

No obstante, hay algunas diferencias importantes que conviene conocer. El cuadro que figura a continuación ofrece un breve resumen de algunas de estas diferencias, que se explican con más detalle en el resto del documento.

Dispatch API Fallo de la API de Messages
Lógica de conmutación por error basada en condition_status y expiry_time propiedades Lógica de conmutación por error basada en el mensaje rejected
Proporciona dos tipos de webhook de estado de mensajes: mensajes individuales e informe final Proporciona un tipo de webhook de estado de mensaje
- Admite canales adicionales, como RCS, así como tipos de mensajes adicionales.
Utiliza Mensajes v0.1 Implementado en Mensajes v1
No compatible con los SDK de servidor Compatible con SDK de servidor

Principales diferencias

La principal diferencia entre la Failover de la Dispatch API y la de la Messages API es la lógica por la que se activa la conmutación por error.

  • La Dispatch API define una función workflow que contiene un objeto para cada mensaje de un flujo de trabajo excepto el último. Dentro de ese objeto se creará un condition_status especificando la propiedad status del mensaje que debe devolverse dentro del expiry_time. Si el estado no se devuelve dentro del expiry_timeel flujo de trabajo pasa al siguiente mensaje.

  • La función Failover de la Messages API define las propiedades del mensaje inicial y, a continuación, incluye una opción failover que contiene los objetos de mensaje para los mensajes restantes en el flujo de trabajo. No define condiciones separadas para cada mensaje en un flujo de trabajo; en su lugar, el flujo de trabajo pasa al siguiente mensaje si el mensaje actual devuelve un estado de rejected.

Hay algunas otras diferencias entre las dos API que hay que tener en cuenta. Éstas se tratan en la sección Otras consideraciones sección.

Realizar una solicitud

Ambas API requieren realizar una solicitud HTTP POST a sus respectivas URL (https://api.nexmo.com/v0.1/dispatch/ para la Dispatch API y https://api.nexmo.com/v1/messages para la API Messages).

El Dispatch API utiliza el Messages API en segundo plano (el Dispatch API es esencialmente un capa de orquestación para la Messages API), por lo que los objetos de mensaje son similares en cuanto a las propiedades que contienen. Sin embargo, Dispatch utiliza Messages v0.1 y la función Messages Failover está implementada en Messages v1 (véase Otras consideraciones), por lo que la estructura JSON de los objetos de mensaje es diferente (la v1 utiliza una estructura más plana).

A continuación se muestran ejemplos de cómo realizar una solicitud con ambas API.

Dispatch API

{
   "template":"failover",
   "workflow": [
		{
			"from": { "type": "mms", "number": "447900000000" },
			"to": { "type": "mms", "number": "447900000001" },
			"message": {
				"content": {
				"type": "img",
				"image": { "url": "https://example.com/image.jpg" }
				}
			},
			"failover":{
				"expiry_time": 600,
				"condition_status": "delivered"
			}
		},
		{
			"from": {"type": "sms", "number": "447900000000"},
			"to": { "type": "sms", "number": "447900000001"},
			"message": {
				"content": {
				"type": "text",
				"text": "This is an SMS sent via the Dispatch API"
				}
			}
		}
   ]
}

El ejemplo anterior muestra un flujo de trabajo de la Dispatch API que pasa de un mensaje de imagen MMS a un mensaje de texto SMS. Si un delivered no se recibe el estado del mensaje de imagen MMS dentro de 600 segundos, se envía el mensaje de texto SMS.

Messages API

{
	"to": "447700900000",
	"from": "447700900001",
	"channel": "mms",
	"message_type": "image",
	"image": {
		"url": "https://example.com/image.jpg"
	},
	"failover": [
		{
	"to": "447700900000",
	"from": "447700900001",
	"channel": "sms",
	"message_type": "text",
	"text": "Hello from Vonage!"
		}
	]
}

El ejemplo anterior muestra un flujo de trabajo de Messages API que pasa de un mensaje de imagen MMS a un mensaje de texto SMS. Si un rejected para el mensaje de imagen MMS, se envía el mensaje de texto SMS.

Respuestas

Ambas API devuelven respuestas similares en caso de que la solicitud se realice correctamente.

Dispatch API

{
	"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

En dispatch_uuid se utiliza para identificar el flujo de trabajo de Despacho en el contexto de los webhooks de Estado de Mensaje.

Messages API

{
	"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
	"workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9"
}

En message_uuid está presente en todas las solicitudes y se utiliza para identificar el mensaje inicial en el contexto de los webhooks de estado de mensaje. La dirección workflow_id sólo está presente para las solicitudes que incluyen el failover y se utiliza para identificar el flujo de trabajo en su conjunto.

Webhooks de estado de mensajes

Los webhooks de estado de mensajes se activan por un cambio en el estado de un mensaje individual y se envían a un punto final de webhook definido en la configuración de la cuenta de Vonage o en la configuración de la aplicación de Vonage.

Al igual que con los propios objetos de mensaje, la estructura JSON de la carga útil del webhook difiere entre las API. Además, la Dispatch API envía dos tipos de webhook de estado, mientras que la Messages API sólo envía uno.

Dispatch API

La Dispatch API envía:

  • Webhooks de estado se envían en relación con mensajes individuales dentro del flujo de trabajo.
  • Un "informe final webhook de estado se envía si/cuando el estado_condición especificado para un mensaje dentro del flujo de trabajo se cumple dentro del tiempo_de_expiración establecido, o si el mensaje final de un flujo de trabajo no puede entregarse.

Webhooks de mensajes individuales

Contienen un message_uuid que identifica el mensaje individual en relación con la Messages API. También contienen un workflow con un objeto dispatch_uuid El valor de esta propiedad coincide con lo que se recibe en la respuesta a la solicitud inicial, e identifica el flujo de trabajo global del Despacho.

{
	"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
	"to": {
		"type": "sms",
		"number": "447700900001"
	},
	"from": {
		"type": "sms",
		"number": "447700900000"
	},
	"timestamp": "2020-01-01T14:00:00.000Z",
	"status": "rejected",
	"error": {
		"code": 1300,
		"reason": "Not part of the provider network"
	},
	"usage": {
		"currency": "EUR",
		"price": "0.0333"
	},
	"_links": {
		"workflow": {
				"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"href": "/workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
		}
	}
}

Mensaje de informe final Webhook

Contiene un dispatch_uuid El valor de esta propiedad coincide con lo que se recibe en la respuesta a la solicitud inicial, e identifica el flujo de trabajo global del Despacho. También contiene una propiedad status de completed si el condition_status para un mensaje dentro del flujo de trabajo se cumple dentro del conjunto expiry_timeo error si no se puede entregar el mensaje final del flujo de trabajo.

{
	"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
	"template": "failover",
	"status": "completed",
	"timestamp": "2020-01-01T14:00:00.000Z",
	"usage": {
		"price": "0.02",
		"currency": "EUR"
	},
	"_links": {
		"messages": [
			{
				"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"href": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"channel": "mms",
				"usage": {
						"currency": "EUR",
						"price": "0.0333"
				},
				"status": "submitted"
			}
		]
	}
}

Messages API

La Messages API envía un mensaje webhook de estado para cualquier cambio de estado. Para los mensajes en los que failover la carga útil JSON incluirá una propiedad workflow objeto. Este objeto contendrá tres propiedades:

  • workflow_id: ID único para el flujo de trabajo de conmutación por error. Coincide con el valor de workflow_id devuelto en la respuesta a la solicitud inicial de la API.
  • items_number: Indica el mensaje específico dentro del flujo de trabajo al que se refiere el estado; p. ej. 1 para el mensaje inicial, 2 para el primer mensaje del failover etc.
  • items_total: Número total de mensajes definidos en el flujo de trabajo.
{
	"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
	"to": "447700900000",
	"from": "447700900001",
	"timestamp": "2025-02-03T12:14:25Z",
	"status": "delivered",
	"workflow": {
		"workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
		"items_number": "1",
		"items_total": "2"
	},
	"usage": {
		"currency": "EUR",
		"price": "0.0333"
	},
	"channel": "sms",
	"destination": {
		"network_code": "12345"
	},
	"sms": {
		"count_total": "2"
	}
}

Otras consideraciones

Además de las diferencias ya señaladas, hay algunas otras cosas a tener en cuenta al migrar de Dispatch API a la funcionalidad Failover de Message API.

Versión de la API de Messages

Como se menciona en otra parte de este documento, la Dispatch API es esencialmente una capa de orquestación sobre la Messages API. Es importante tener en cuenta que la Messages API tiene actualmente dos versiones: v0.1 y v1. La Dispatch API utiliza Messages v0.1 y la funcionalidad Messages Failover está implementada en v1. Además de una diferencia en la estructura de la carga útil JSON, hay algunas otras diferencias entre las versiones que vale la pena mencionar.

  • Mensajes v1 soporta canales y tipos de mensajes adicionales en comparación con v0.1. Por ejemplo, v1 admite el canal RCS (un caso de uso común para la conmutación por error es de RCS a SMS). Incluso dentro de los canales soportados por ambas, la v1 soporta algunos tipos de mensajes adicionales como texto MMS, archivos y tipos de mensajes de contenido.
  • Existen otros características adicionales que ofrece la v1 en comparación con la v0.1

SDK de servidor

Messages API (v1) se implementa en Vonage SDK de servidormientras que la API DIspatch no. La implementación de Messages API en los SDK de servidor incluye la funcionalidad de conmutación por error de mensajes. Existen SDKs de servidor para Node JS, PHP, Python, Java, Kotlin, .NET y Ruby. Los SDK le permiten integrar fácilmente la Messages API en sus aplicaciones sin tener que implementar su propia envoltura para el punto final de la API.

Recursos adicionales

Para más información sobre Dispatch API y Messages API, incluida la funcionalidad Failover, puede consultar las páginas de documentación enlazadas a continuación:

Dispatch API

Messages API