Migração do Dispatch para o Failover do Messages

Este guia compara as funcionalidades da Dispatch API com as do recurso de failover no Messages API, e destaca alguns pontos a serem considerados ao migrar da Dispatch API para a funcionalidade de failover da Messages API.

Concepts Gerais

Em um nível conceitual geral, a Dispatch API e o recurso de Failover da Messages API são, em linhas gerais, semelhantes. Ambos permitem que você:

Especifique uma mensagem inicial, juntamente com uma ou mais mensagens alternativas a serem enviadas caso a mensagem inicial não seja entregue.
Failover entre diferentes tipos de mensagens.
Failover entre diferentes canais de mensagens.

Há, no entanto, algumas diferenças importantes que devem ser levadas em conta. A tabela abaixo apresenta uma breve visão geral de algumas dessas diferenças, que são explicadas com mais detalhes no restante do documento.

Dispatch API	Failover da Messages API
Lógica de failover baseada em `condition_status` e `expiry_time` propriedades	Lógica de failover baseada no fato de a mensagem estar `rejected`
Oferece dois tipos de webhook de status de mensagem: mensagens individuais e relatório final	Oferece um tipo de webhook de status de mensagem
-	Oferece suporte a canais adicionais, como o RCS, bem como a tipos de mensagens adicionais
Usos do Messages v0.1	Implementado no Messages v1
Não compatível com os SDKs do servidor	Compatível com os SDKs de servidor

Principais diferenças

A principal diferença entre o failover da Dispatch API e o da Messages API é a lógica pela qual o failover é acionado.

A Dispatch API define um workflow matriz que contém um objeto para cada mensagem em um fluxo de trabalho, exceto a última. Dentro desse objeto, um condition_status a propriedade é definida especificando o status da mensagem a ser retornada dentro do prazo especificado expiry_time. Se o status não for retornado dentro do expiry_time, nesse caso, o fluxo de trabalho passa para a próxima mensagem.
O recurso de failover da Messages API define as propriedades da mensagem inicial e, em seguida, inclui um failover matriz que contém os objetos de mensagem para as mensagens restantes no fluxo de trabalho. Ela não define condições separadas para cada mensagem em um fluxo de trabalho; em vez disso, o fluxo de trabalho passa para a próxima mensagem se a mensagem atual retornar um status de rejected.

Existem algumas outras diferenças entre as duas APIs que devem ser levadas em conta. Elas são abordadas no Outras considerações seção.

Como fazer uma solicitação

Ambas as APIs exigem a realização de uma chamada HTTP POST solicitação às respectivas URLs (https://api.nexmo.com/v0.1/dispatch/ para a Dispatch API e https://api.nexmo.com/v1/messages (para a Messages API).

A Dispatch API utiliza a Messages API em segundo plano (a Dispatch API é, essencialmente, uma camada de orquestração (para a Messages API), de modo que os objetos de mensagem são semelhantes no que diz respeito às propriedades que contêm. No entanto, o Dispatch utiliza o Messages v0.1, enquanto o recurso de failover do Messages está implementado no Messages v1 (consulte Outras considerações), portanto, a estrutura JSON dos objetos de mensagem é diferente (a v1 usa uma estrutura mais simples).

A seguir, apresentamos exemplos de como fazer uma solicitação usando ambas as APIs.

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

O exemplo acima ilustra um fluxo de trabalho da Dispatch API que realiza o failover de uma mensagem com imagem (MMS) para uma mensagem de texto (SMS). Se uma delivered não foi recebido o status da mensagem MMS com imagem dentro de 600 segundos, a mensagem de texto SMS é enviada.

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!"
		}
	]
}

O exemplo acima ilustra um fluxo de trabalho da Messages API que realiza o failover de uma mensagem de imagem MMS para uma mensagem de texto SMS. Se uma rejected Assim que for recebido o status da mensagem MMS com imagem, a mensagem de texto SMS é enviada.

Respostas

Ambas as APIs retornam respostas semelhantes para solicitações bem-sucedidas.

Dispatch API

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

O dispatch_uuid é usado para identificar o fluxo de trabalho do Dispatch no contexto dos webhooks de status de mensagem.

Messages API

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

O message_uuid está presente em todas as solicitações e é usado para identificar a mensagem inicial no contexto dos webhooks de status de mensagem. O workflow_id está presente apenas para solicitações que incluam o failover matriz, e é usado para identificar o fluxo de trabalho como um todo.

Webhooks de status de mensagens

Os webhooks de status de mensagem são acionados por uma alteração no status de uma mensagem específica e são enviados para um ponto de extremidade de webhook definido nas configurações da conta da Vonage ou nas configurações do aplicativo da Vonage.

Assim como acontece com os próprios objetos de mensagem, a estrutura JSON da carga útil do webhook varia de acordo com a API. Além disso, a Dispatch API envia dois tipos de webhook de status, enquanto a Messages API envia apenas um tipo.

Dispatch API

A Dispatch API envia:

Webhooks de status são enviadas em relação a mensagens específicas dentro do fluxo de trabalho.
Um “relatório final” webhook de status é enviada se/quando o condition_status especificado para uma mensagem dentro do fluxo de trabalho for atendido dentro do expiry_time definido, ou se a mensagem final de um fluxo de trabalho não puder ser entregue.

Webhooks de mensagens individuais

Estes contêm um message_uuid que identifica a mensagem específica em relação à Messages API. Elas também contêm um workflow objeto com um dispatch_uuid propriedade; o valor dessa propriedade corresponde ao que é recebido na resposta à solicitação inicial e identifica o fluxo de trabalho geral do Dispatch.

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

Webhook de mensagem do relatório final

Isso contém um dispatch_uuid propriedade; o valor dessa propriedade corresponde ao que é recebido na resposta à solicitação inicial e identifica o fluxo de trabalho geral do Dispatch. Ela também contém um status de qualquer um dos dois completed se o especificado condition_status para que uma mensagem dentro do fluxo de trabalho seja atendida dentro do intervalo definido expiry_time, ou error se a mensagem final do fluxo de trabalho não puder ser entregue.

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

The Messages API envia um webhook de status para qualquer alteração no status. Para mensagens em que o failover Se a propriedade foi incluída, a carga JSON incluirá um workflow objeto. Esse objeto conterá três propriedades:

workflow_id: Identificador exclusivo do fluxo de trabalho de failover. Corresponde ao valor de workflow_id retornado na resposta à solicitação inicial da API.
items_number: Indica a mensagem específica dentro do fluxo de trabalho à qual o status se refere; por exemplo, 1 para a mensagem inicial, 2 para a primeira mensagem na failover matriz, e assim por diante.
items_total: Número total de mensagens definidas no fluxo de trabalho.

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

Outras considerações

Além das diferenças já mencionadas, há alguns outros aspectos que devem ser levados em consideração ao migrar da Dispatch API para a funcionalidade de failover da Messages API.

Versão da Messages API

Conforme mencionado em outra parte deste documento, a Dispatch API é, essencialmente, uma camada de orquestração sobre a Messages API. É importante observar, porém, que a Messages API possui, atualmente, duas versões: v0.1 e v1. A Dispatch API utiliza o Messages v0.1, e a funcionalidade de failover do Messages está implementada na v1. Além da diferença na estrutura da carga útil JSON, há algumas outras diferenças entre as versões que merecem destaque.

A versão 1 do Messages oferece suporte a canais e tipos de mensagem adicionais em comparação com a versão 0.1. Por exemplo, a versão 1 oferece suporte ao canal RCS (um caso de uso comum para failover é de RCS para SMS). Mesmo entre os canais suportados por ambas as versões, a versão 1 oferece suporte a alguns tipos de mensagem adicionais, como mensagens de texto MMS, mensagens com arquivos e mensagens de conteúdo.
Há uma série de outros recursos adicionais disponível na v1 em comparação com a v0.1

SDKs de servidor

A Messages API (v1) está implementada no Vonage SDKs de servidor, ao passo que a Dispatch API não o é. A implementação da Messages API nos SDKs de servidor inclui a funcionalidade de failover de mensagens. Existem SDKs de servidor para Node.js, PHP, Python, Java, Kotlin, .NET e Ruby. Os SDKs permitem que você integre facilmente a Messages API às suas aplicações sem precisar implementar seu próprio wrapper para o endpoint da API.

Recursos adicionais

Para obter mais informações sobre a Dispatch API e a Messages API, incluindo a funcionalidade de failover, consulte as páginas de documentação cujos links constam abaixo: