Apresentando o failover de mensagens na Messages API do Vonage

Failover de mensagens já está disponível na Messages API for Vonage. Antes de entrarmos em detalhes sobre o que é o failover e como usá-lo, vamos fazer uma breve visão geral da Messages API para quem ainda não estiver familiarizado com ela.

Visão geral da Messages API

A Messages API é uma API de mensagens multicanal que permite que as empresas enviem e recebam diversos tipos de mensagens por meio de vários canais de comunicação, incluindo SMS, MMS, RCS, WhatsApp e outros.

A estrutura exata do JSON da carga útil da solicitação à API varia de acordo com o canal e/ou o tipo de mensagem, mas todas as mensagens seguem os mesmos princípios básicos. O JSON de todas as mensagens conteria propriedades para até, de, canal, e tipo_da_mensagem, bem como uma propriedade para a própria mensagem, que variaria dependendo do tipo de mensagem. Há também propriedades opcionais adicionais, algumas das quais relacionadas a recursos específicos suportados por um determinado canal ou tipo de mensagem.

Por exemplo, esta seria a estrutura JSON para enviar um mensagem de texto por meio do SMS :

{
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "message_type": "text",
   "text": "Hello from Vonage!"
}

Uma imagem imagem enviada por meio do canal utilizaria uma estrutura JSON mais ou menos assim:

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "image",
   "image": {
     "url": "https://example.com/image.jpg"
    }
}

A resposta à solicitação da API conterá um corpo de resposta com um propriedade message_uuid , que identifica de forma exclusiva o objeto de mensagem nos servidores da Vonage. Esse UUID pode então ser usado para rastrear o status da mensagem.

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
}

Status da mensagem

Depois que a solicitação inicial à API for feita, o objeto de mensagem passará por vários estados, tais como enviado e entregue, à medida que a Messages API tenta entregá-la ao destinatário especificado por meio da rede de downstream do canal solicitado.

Uma alteração no status acionará o envio de uma solicitação HTTP para o ponto de extremidade do webhook de status definido nas configurações do seu aplicativo Vonage. O corpo da solicitação conterá uma carga JSON estruturada mais ou menos assim (embora possa haver propriedades adicionais, dependendo do canal e do status):

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "Vonage",
   "channel": "sms",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "delivered"
}

Os status específicos podem variar ligeiramente dependendo do canal. Por exemplo, canais como RCS e WhatsApp possuem um status de “lido” que indica que uma mensagem entregue já foi lida pelo destinatário, ao passo que SMS e MMS não oferecem a funcionalidade de fornecer status de de leitura.

Um status de mensagem que todos os canais têm em comum é o rejeitado . Dependendo do canal e/ou do tipo de mensagem, pode haver vários motivos pelos quais uma mensagem foi rejeitada. Em todos os casos, porém, uma status “rejeitado” significa que a mensagem não será entregue ao destinatário.

O que é o failover do Message

Antes da implementação do failover na Messages API do Vonage, se você quisesse incorporar alguma resiliência ao seu aplicativo de mensagens para lidar com situações em que as mensagens fossem rejeitadas, precisaria implementar você mesmo a lógica de negócios necessária para isso. Por exemplo, você poderia configurar um sistema para acompanhar o status de uma solicitação de mensagem específica usando as mensagens do webhook “Message Status” por meio do message_uuid retornado na chamada HTTP inicial; e, caso uma status “rejeitado” fosse recebido para um objeto de mensagem, fazer uma solicitação para que uma mensagem alternativa fosse enviada.

Com o recurso de failover, esse tipo de lógica pode ser incorporado à própria solicitação inicial da mensagem. Vamos descobrir como!

Como usar o failover na Messages API

Para usar o failover na Messages API , é necessário incluir uma failover propriedade adicional na carga JSON que define a mensagem. O valor dessa propriedade é um array que contém um ou mais objetos de mensagem.

{
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "message_type": "text",
   "text": "Hello from Vonage!",
   "failover": [
     // message objects
   ]
}

Se a mensagem inicial for rejeitada, a Messages API enviará automaticamente o primeiro objeto de mensagem no matriz de failover . Se essa mensagem também for rejeitada, o segundo objeto (caso haja um definido) será enviado, e assim por diante.

Ao incluir o propriedade de failover na solicitação da API, um message_uuid é recebido na resposta HTTP, como de costume, mas uma propriedade adicional, workflow_id , também é incluída:

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

Ao receber solicitações de webhook de “Status da Mensagem” para objetos de mensagem que foram enviados com um propriedade de failover , a carga JSON incluirá um objeto de workflow com o workflow_id , cujo valor corresponderá ao workflow_id recebido na resposta à solicitação inicial da API. Nesse contexto, um “workflow” representa a série de mensagens – a mensagem inicial e a(s) mensagem(ns) de failover definida(s).

Além disso, o objeto de fluxo de trabalho conterá um propriedade “items_number” e uma propriedade items_total . A items_number indica a qual “item” ou mensagem, dentro do fluxo de trabalho geral, esta solicitação de Status da Mensagem se refere. Uma items_number de 1 indica a mensagem inicial, e número_de_itens de 2 indica o primeiro objeto de mensagem no matriz de failover e assim por diante. O propriedade `items_total` indica o número total de “itens” ou mensagens no fluxo de trabalho como um todo; por exemplo, um items_total de 3 indicaria uma mensagem inicial com duas mensagens definidas no matriz de failover .

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900001",
   "from": "Vonage",
   "channel": "sms",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "delivered",
   "workflow": {
      "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
      "items_number": "1",
      "items_total": "2"
   }
}

A Messages API enviará solicitações de status de mensagem conforme necessário para cada mensagem em um fluxo de trabalho. Assim, por exemplo, você poderia receber um status de rejeitado para número_de_itens 1, e, em seguida, um status de entregue (com o mesmo message_uuid e workflow_id) para número de itens 2. Se, por outro lado,  número_de_itens 1 foi entregue , então o fluxo de trabalho estaria concluído e quaisquer mensagens subsequentes no fluxo de trabalho não acionariam solicitações de status de mensagem.

Quando usar o failover

Agora que já abordamos o que é o failover e como usá-lo, vamos examinar algumas maneiras pelas quais ele pode ser utilizado.

Failover entre canais

Você pode aproveitar a capacidade multicanal da Messages API tentando enviar uma mensagem para um canal e, caso a mensagem inicial seja rejeitada, alternando para outro canal.

Um caso de uso comum seria a transição do RCS para o SMS. Embora o RCS já seja amplamente compatível atualmente (as mensagens RCS são compatíveis com o iOS desde a versão 18), ele ainda não é tão difundido em termos de compatibilidade com dispositivos e cobertura de rede quanto o SMS. Além disso, alguns dispositivos exigem que você habilite as mensagens RCS no próprio dispositivo (ou seja, elas não vêm habilitadas por padrão). O envio de uma mensagem para um dispositivo que não suporta RCS resultaria na rejeitada. Nessa situação, você poderia, em vez disso, fazer o failover para uma mensagem SMS.

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "text",
   "text": "Hello from Vonage!",
   "failover": [
     {
       "to": "447700900001",
       "from": "Vonage",
       "channel": "sms",
       "message_type": "text",
       "text": "Hello from Vonage!"
     }
   ]
}

Failover múltiplo

A ideia geral é semelhante à do exemplo anterior, mas com mais canais utilizados para oferecer uma alternativa adequada com base no tipo de mensagem. Por exemplo, você pode querer enviar uma mensagem de produto com uma imagem via RCS, que recorra a uma imagem por MMS caso o dispositivo do destinatário não seja compatível com RCS e, em seguida, recorra ao SMS caso a rede do destinatário não seja compatível com MMS.

{
   "to": "447700900001",
   "from": "Vonage-RCS-Agent",
   "channel": "rcs",
   "message_type": "image",
   "image": {
     "url": "https://example.com/image.jpg"
    },
   "failover": [
     {
      "to": "447700900001",
      "from": "447700900000",
      "channel": "mms",
      "message_type": "image",
      "image": {
         "url": "https://example.com/image.jpg"
      }
    },
    {
       "to": "447700900001",
       "from": "Vonage",
       "channel": "sms",
       "message_type": "text",
       "text": "Check out this image https://example.com/image.jpg"
     }
   ]
}

Conclusão e próximos passos

Nesta publicação, exploramos a funcionalidade de failover na Messages API. Vimos o que é o failover, como usá-lo e algumas situações em que ele pode ser útil.

Se você quiser se aprofundar no tema do failover, pode conferir o guia em nossa documentação para desenvolvedores, exemplos de trechos de código que demonstram o uso do failover em nossos SDKs de servidor, além da especificação completa da especificação da Messages API.

Você está desenvolvendo algo incrível com a Messages API, planejando usar a funcionalidade de failover ou talvez tenha apenas dúvidas sobre o recurso ou sobre a API em geral? Entre em contato conosco no nosso espaço de trabalho da Comunidade Vonage no Slack!