Integração da Messages API

É possível integrar a Messages API ao Vonage Client SDK para permitir que as mensagens recebidas pela Messages API sejam encaminhadas para uma Conversação e que as mensagens enviadas sejam entregues de volta por meio da Messages API.

Para continuar, você já deve estar familiarizado com:

• Recebimento de mensagens recebidas com a Messages API
• Conversas
• Usuários
• Participantes da conversa
• Eventos de envio de mensagens com o Vonage Client SDK

Como funciona

Ao lidar com a Messages API, é preciso levar em conta os casos de mensagens recebidas e enviadas.

Mensagens recebidas

Ao receber uma mensagem de entrada na URL do webhook de entrada da Messages API, você responde com um objeto JSON que instrui a Messages API a encaminhar essa mensagem para a Conversation API, fornecendo algumas informações sobre para qual conversação a mensagem de entrada deve ser encaminhada.

Veja a seguir um exemplo usando JavaScript e Express.JS:

app.post('/message/inbound', (req, res) => {
  const username = `+${req.body.from}`;
  const conversationName = 'my_conversation';
  const region = 'eu-3';

  console.log(username, conversationName, region);

  res.json([{
    action: 'message',
    conversation_name: conversationName,
    user: username,
    region: region,
  }]);
});

Essa rota é chamada a cada mensagem recebida pelo aplicativo Vonage; no caso de SMS, isso seria acionado pelo envio de uma mensagem de texto para um número virtual vinculado ao seu aplicativo Vonage, mas o processo é o mesmo para os outros canais oferecidos pela Messages API. A resposta é um objeto JSON, que é semelhante ao Objetos de controle de chamadas usado pelo Voice, que fornece informações à Conversation API sobre como lidar com essa mensagem. A Conversation API realiza algumas ações automaticamente para você com essa resposta:

1. Ele procura uma conversa com o nome fornecido no conversation_name propriedade, na região indicada no region propriedade. Caso ela não exista, será criada uma na região especificada.

2. Ele procura um usuário com o nome indicado no user propriedade, na região indicada no region propriedade. Caso ela não exista, será criada uma na região especificada.

3. Se for um novo usuário ou se for novo na conversa especificada, o usuário será adicionado como membro da conversa. Em seguida, será criado um evento de mensagem na conversa com o corpo da mensagem recebida originalmente enviada ao webhook.

Como você pode ver, essa região é essencial para garantir que as mensagens recebidas da Messages API cheguem à conversa correta. O regiões são os mesmos utilizados na configuração da Voice API e do Client SDK. Em um ambiente de produção, provavelmente você precisará criar uma maneira de esclarecer a ambiguidade do webhook de mensagens recebidas para garantir que ele chegue à Conversação correta. Isso pode se parecer com um mapeamento de um número de telefone para uma conversa específica, ou você pode pedir ao remetente que inclua algum tipo de texto previsível na mensagem para controlar para qual conversa a mensagem será direcionada:

Conv1: Hello World!
Conv2: Hello Vonage!

Você pode dividir a sequência de caracteres em : e use o primeiro elemento, por exemplo: Conv1 como nome da conversa.

Mensagens enviadas

As mensagens de saída (novos eventos de mensagem de conversa) serão enviadas automaticamente pela Conversation API de volta pelo mesmo canal em que a mensagem de entrada foi recebida. Quando um usuário é adicionado a uma conversa, isso cria um membro. A participação pode ser vista como uma vinculação de um usuário a uma conversa por meio de um canal. Além dos canais suportados pela Conversation API, o Canais da Messages API são compatíveis com mensagens.

Quando uma mensagem recebida pela Messages API é encaminhada para a Conversation API, ela cria um Membro na Conversação especificada, com o Canal no qual a mensagem recebida foi captada. Por exemplo, se o trecho de código do webhook acima foi usado em resposta a uma mensagem SMS recebida por meio do SDK do Servidor da Vonage, é possível obter o objeto membro:

const member = await vonage.conversations.getMember(
    'my_conversation_id',
    'sms_member_id'
    );

O que resultaria no seguinte objeto:

{
  "id": "MEM-644630b7-1ba6-4c71-9fae-834316f1d1d5",
  "conversationId": "CON-0f9af192-d916-4365-b0cb-1b7e3c53576c",
  "channel": {
    "type": "sms",
    "from": {
      "number": "447441446999"
    },
    "to": {
      "number": "441234567890"
    }
  },
  ...
}

Como você pode ver, o channel O objeto contém o tipo de SMS conforme esperado, com o from.number que é o número de telefone virtual vinculado ao meu aplicativo da Vonage, e o to.number é o número que enviou o SMS. Compare isso com outro objeto In-App Member do Client SDK:

{
  "id": "MEM-f5fa689b-8a3f-43f3-87fd-5af0d3e35221",
  "conversationId": "CON-0f9af192-d916-4365-b0cb-1b7e3c53576c",
  "channel": {
    "type": "app"
  },
  ...
}

Quando um novo evento de mensagem é enviado para a conversa, a Conversation API irá consultar o channel para o Membro e enviar a Notificação de Mensagem para ele. Assim, para o primeiro Membro, será enviado um SMS por meio da Messages API para o to.number do mundo virtual from.number e, para o segundo membro, será enviada por meio do In-App Messaging.

Criação de usuários e membros da Messages API

Conforme mostrado acima, a Conversation API pode criar um Usuário e um Membro automaticamente para você, mas se quiser fazer isso por conta própria, é possível utilizar o SDK do Servidor da Vonage ou a Conversation API diretamente:

const number = 'sms_sender_number';
const vonageNumber = "my_vonage_number";
const conversationId = 'my_conversation_id';

const formattedNumber = `+${number}`
const user = await vonage.users.createUser({
    name: formattedNumber,
    displayName: formattedNumber,
    channels: {
        sms: [{
            number: number
        }]
    }
});

const member = await vonage.conversations.createMember(
    conversationId,
    {
        state: 'joined',
        user: {
            name: user.name
        },
        channel: {
            type: 'sms',
            from: {
                number: vonageNumber
            },
            to: {
                number: number
            }
        }
    }
);


console.log(member);

Primeiramente, isso criará um usuário com um canal de SMS que contenha o número de telefone que o usuário utilizará para enviar uma mensagem SMS. Em seguida, esse usuário é adicionado como membro da conversa com um canal de SMS, conforme descrito acima. Os canais associados ao usuário são validados em relação aos canais fornecidos ao criar um membro.