Envio de uma mensagem com failover

Ao enviar mensagens com a Messages API do Vonage, elas podem ser rejeitadas. Em uma única solicitação de API, é possível definir mensagens de failover para serem enviadas em seu lugar. Por exemplo, se o dispositivo de um cliente não for compatível com o seu canal principal, como o RCS, ele continuará recebendo suas mensagens por meio de canais alternativos.

Este guia explica como configurar o failover de mensagens em sua solicitação e como monitorar o status de entrega por meio de callbacks.

Envio de uma solicitação com failover de mensagem

Neste exemplo, uma mensagem de texto RCS é enviada primeiro, seguida por uma mensagem SMS caso a primeira falhe. A estrutura da solicitação é a mesma do envio de uma mensagem padrão pelo canal principal; a mensagem de failover é, então, definida em um failover matriz da seguinte forma:

{
  "to": "447700900000",
  "from": "Vonage",
  "channel": "rcs",
  "message_type": "image",
  "image": {
    "url": "https://example.com/image.jpg",
    "caption": "This is an image sent via RCS using the Vonage Messages API."
  },
  "failover": [
    {
      "to": "447700900000",
      "from": "447700900001",
      "channel": "sms",
      "message_type": "text",
      "text": "This is an SMS sent using the Vonage Messages API."
    }
  ]
}

Você pode definir quantos canais de failover forem necessários; as mensagens de failover serão enviadas na ordem em que estiverem definidas na matriz.

Cada mensagem na matriz de failover requer sua própria channel, message_type from, to, e o conteúdo da mensagem; mais informações sobre cada canal e seus parâmetros necessários podem ser encontradas no Especificação da API. Você também deve garantir que o conteúdo da mensagem esteja adaptado às capacidades de cada canal alternativo.

Exemplos de solicitações usando o cURL e os SDKs da Vonage podem ser encontrados no Enviar uma mensagem com failover página de trechos de código.

Status do monitoramento e chamadas de retorno

Quando sua mensagem for enviada, a API retorna callbacks de status para a URL do seu webhook. Eles acompanham o andamento e o resultado de cada mensagem na sequência de failover. Um exemplo de fluxo para o failover do RCS para o SMS seria:

  1. RCS Enviado → Mensagem enviada ao canal principal (neste caso, o RCS).
  2. RCS rejeitado → Falha na entrega da mensagem.
  3. SMS enviado → Mensagem de failover enviada por SMS.
  4. SMS entregue → Mensagem enviada com sucesso.

Exemplos de callbacks

Os exemplos de callback a seguir mostram atualizações de status para uma mensagem RCS que foi rejeitada e uma mensagem SMS que foi entregue. Em ambos os callbacks, você verá estes campos:

  • workflow.workflow_id — Identificador único para o fluxo de trabalho de failover.
  • workflow.items_number — Indica a sequência das mensagens enviadas (por exemplo, “1” para o primário, “2” para o primeiro failover).
  • workflow.items_total — Número total de mensagens que se tentou enviar neste fluxo de trabalho.
  • status — Indica o estado da entrega. Esses valores variam de acordo com o canal, mas serão um dos seguintes: submitted, delivered, rejected, undeliverable, ou read. Informações específicas sobre cada canal podem ser encontradas no Especificação da API.

RCS rejeitado

{
  "messageuuid": "001",
  "to": "447700900000",
  "from": "Vonage",
  "timestamp": "2024-01-01T14:00:02.000Z",
  "status": "rejected",
  "channel": "rcs",
  "workflow": {
    "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
    "items_number": "1",
    "items_total": "2"
  }
}

SMS entregue

{
  "messageuuid": "002",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2024-01-01T14:00:04.000Z",
  "status": "delivered",
  "channel": "sms",
  "workflow": {
    "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
    "items_number": "2",
    "items_total": "2"
  }
}

Use esses callbacks para rastrear onde e como as mensagens são entregues e para acionar as próximas ações ou registros.

Leitura complementar