Integración de Messages API

Puedes integrar la API de Messages con el Client SDK de Vonage para permitir que los mensajes entrantes a la API de Messages se envíen a una conversación y que los mensajes salientes se devuelvan a través de la API de Messages.

Para continuar, ya debería estar familiarizado:

• Recepción de mensajes entrantes con la API Messages
• Conversaciones
• Usuarios
• Conversación Miembros
• Envío de eventos de mensajes con el Vonage Client SDK

Cómo funciona

Cuando se trata de Messages API hay que tener en cuenta los casos de entrada y salida.

Mensajes entrantes

Cuando recibe un mensaje entrante en su URL de webhook de entrada de la Messages API, responde con un objeto JSON que indica a la Messages API que reenvíe este mensaje a la Conversation API con alguna información sobre a qué Conversación debe reenviarse el mensaje entrante.

A continuación se muestra un ejemplo utilizando JavaScript y 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,
  }]);
});

Esta ruta se llama en cada mensaje entrante a la aplicación de Vonage; en el caso de los SMS, esto se activaría al enviar un SMS a un número virtual vinculado a tu aplicación de Vonage, pero el proceso es el mismo para los otros canales que ofrece Messages API. La respuesta es un objeto JSON, que es similar al objeto Objetos de control de llamada utilizado para Voice, que proporciona información a la Conversation API sobre cómo gestionar este mensaje. La Conversation API hace algunas cosas automáticamente por usted con esta respuesta:

1. Busca una Conversación con el nombre indicado en el campo conversation_name en la región indicada en la propiedad region propiedad. Si no existe, creará una en la región especificada.

2. Busca un Usuario con el nombre dado en el campo user en la región indicada en la propiedad region propiedad. Si no existe, creará una en la región especificada.

3. Si se trata de un nuevo usuario o es nuevo en la conversación especificada, se añadirá al usuario como miembro de la conversación. Entonces se creará un evento de mensaje en la Conversación con el cuerpo del mensaje entrante original enviado al webhook.

Como puede ver, la región es vital para asegurarse de que los mensajes entrantes de la Messages API llegan a la Conversación correcta. La dirección regiones son los mismos que se utilizan en la configuración de Voice API y Client SDK. En un entorno de producción, es probable que tenga que construir una manera de desambiguar el webhook mensaje entrante para asegurarse de que llega a la conversación correcta. Esto podría ser una asignación de un número de teléfono a una conversación específica, o puede pedir al remitente que incluya algún tipo de texto predecible en el mensaje para controlar a qué conversación va el mensaje:

Conv1: Hello World!
Conv2: Hello Vonage!

Puede dividir la cadena en : y utilizar el primer elemento, por ejemplo Conv1 como nombre de la Conversación.

Mensajes salientes

Los mensajes salientes (nuevos Eventos de Mensaje de Conversación) serán enviados automáticamente por la Conversation API de vuelta a través del mismo canal en el que se recibió el mensaje entrante. Cuando se añade un usuario a una conversación, se crea un miembro. La afiliación puede verse como la vinculación de un usuario a una conversación a través de un canal. Además de los canales que admite la Conversation API, los canales Canales de la API de Messages para la mensajería.

Cuando un mensaje entrante de Messages API se reenvía a la Conversation API, se crea un miembro en la conversación especificada con el canal en el que se recibió el mensaje entrante. Por ejemplo, si el fragmento de código de webhook anterior se usó en respuesta a un mensaje SMS entrante usando el SDK del servidor de Vonage, puedes obtener el objeto miembro:

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

Lo que daría el 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 puede ver, el channel contiene el tipo de SMS como se esperaba, con el objeto from.number que es el número de teléfono virtual vinculado a mi aplicación de Vonage, y el botón to.number es el número que envió el SMS. Compárelo con otro objeto In-App Member del Client SDK:

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

Cuando se envía un nuevo Evento de Mensaje a la Conversación, la Conversation API buscará el channel para el Miembro y entregar el Evento de Mensaje allí. Así, para el primer miembro, se enviará un SMS a través de la Messages API a la dirección to.number del virtual from.number y para el segundo Miembro, se entregará a través de In-App Messaging.

Creación de usuarios y miembros de Messages API

Como se muestra arriba, la Conversation API puede crear un usuario y miembro para ti automáticamente, pero si deseas crearlo tú mismo, puedes hacerlo usando el SDK del servidor de Vonage o la Conversation API directamente:

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);

Esto creará primero un Usuario con un Canal SMS que contiene el número de teléfono que el Usuario utilizará para enviar un SMS. A continuación, ese usuario se añade como miembro de la conversación con un canal SMS, tal y como se ha descrito anteriormente. Los canales del usuario se comparan con los canales proporcionados al crear un miembro.