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, deberías estar ya familiarizado con:

• Recepción de mensajes entrantes con la API Messages
• Conversaciones
• Usuarios
• Miembros de la conversación
• 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 llamadas Se utiliza en Voice, que proporciona información a la Conversation API sobre cómo gestionar este mensaje. La Conversation API realiza automáticamente varias acciones por ti 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 puedes ver, esta región es fundamental para garantizar que los mensajes entrantes procedentes de la Messages API lleguen a la conversación correcta. El regiones son los mismos que se utilizan en la configuración de la Voice API y del Client SDK. En un entorno de producción, es probable que tengas que idear una forma de desambiguar el webhook del mensaje entrante para asegurarte de que llegue a la conversación correcta. Esto podría consistir en una asignación de un número de teléfono a una conversación específica, o bien podrías pedir al remitente que incluya algún tipo de texto predecible en el mensaje para controlar a qué conversación se dirige 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 puedes ver, el channel El objeto contiene el tipo de SMS tal y como se esperaba, con el 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 desde el que se envió el SMS. Compáralo 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 enviar allí el evento de mensaje. Así pues, en el caso del primer miembro, se enviará un SMS a través de la Messages API al to.number del virtual from.number y, en el caso del segundo miembro, se enviará 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);

En primer lugar, se creará un usuario con un canal SMS que contenga el número de teléfono que el usuario utilizará para enviar un SMS. A continuación, dicho usuario se añadirá 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 facilitados al crear un miembro.