Intégration de l'API Messages

Vous pouvez intégrer l'API Messages au Client SDK de Vonage pour permettre l'envoi de messages entrants à l'API Messages vers une Conversation, et la livraison de messages sortants via l'API Messages.

Pour continuer, vous devriez déjà être familier avec :

• Réception des messages entrants avec l'API Messages
• Conversations
• Utilisateurs
• Membres de la conversation
• Envoi de messages avec le Client SDK de Vonage

Comment ça marche

Lorsqu'il s'agit de Messages API, il faut tenir compte des cas d'entrée et de sortie.

Messages entrants

Lorsque vous recevez un message entrant à l'URL de votre webhook Messages API Inbound, vous répondez par un objet JSON qui indique à l'API Messages de transmettre ce message à l'API Conversation avec quelques informations sur la Conversation à laquelle le message entrant doit être transmis.

Vous trouverez ci-dessous un exemple utilisant JavaScript et 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,
  }]);
});

Cette route est appelée pour chaque message entrant dans l'application Vonage. Pour les SMS, elle est déclenchée par l'envoi d'un SMS à un numéro virtuel lié à votre application Vonage, mais le processus est le même pour les autres canaux offerts par l'API Messages. La réponse est un objet JSON, qui est similaire à l'objet Appeler des objets de contrôle utilisée pour Voice, qui donne des informations à l'API Conversation sur la manière de traiter ce message. La Conversation API effectue quelques opérations automatiques pour vous avec cette réponse :

1. Il recherche une conversation dont le nom est indiqué dans la rubrique conversation_name dans la région indiquée dans le region de la propriété. S'il n'existe pas, il en créera un dans la région spécifiée.

2. Il recherche un utilisateur dont le nom est indiqué dans la rubrique user dans la région indiquée dans le region de la propriété. S'il n'existe pas, il en créera un dans la région spécifiée.

3. S'il s'agit d'un nouvel utilisateur ou d'un nouvel utilisateur de la conversation spécifiée, l'utilisateur sera ajouté en tant que membre de la conversation. Un événement de message sera ensuite créé dans la conversation avec le corps du message entrant original envoyé au webhook.

Comme vous pouvez le constater, la région est essentielle pour s'assurer que les messages entrants provenant de l'API Messages parviennent à la bonne Conversation. La région régions sont les mêmes que ceux utilisés dans la configuration de Voice API et du Client SDK. Dans un environnement de production, vous devrez probablement créer un moyen de désambiguïser le webhook du message entrant pour vous assurer qu'il est envoyé à la bonne conversation. Il peut s'agir d'une correspondance entre un numéro de téléphone et une conversation spécifique, ou vous pouvez demander à l'expéditeur d'inclure une sorte de texte prévisible dans le message pour contrôler la conversation à laquelle le message est destiné :

Conv1: Hello World!
Conv2: Hello Vonage!

Vous pouvez diviser la chaîne sur : et utiliser le premier élément, par exemple Conv1 comme nom de la conversation.

Messages sortants

Les messages sortants (nouveaux événements de messages de conversation) seront automatiquement renvoyés par l'API Conversation via le même canal que celui sur lequel le message entrant a été reçu. Lorsqu'un utilisateur est ajouté à une conversation, un membre est créé. L'adhésion peut être considérée comme une liaison d'un utilisateur à une conversation par l'intermédiaire d'un canal. Outre les canaux pris en charge par l'API Conversation, les canaux Canaux de l'API Messages sont prises en charge pour la messagerie.

Lorsqu'un message API Messages entrant est transmis à l'API Conversation, il crée un membre dans la conversation spécifiée avec le canal dans lequel le message entrant a été reçu. Par exemple, si l'extrait de code du webhook ci-dessus a été utilisé en réponse à un message SMS entrant à l'aide du SDK du serveur Vonage, vous pouvez obtenir l'objet membre :

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

Ce qui donnerait l'objet :

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

Comme vous pouvez le constater, le channel contient le type de SMS comme prévu, avec l'objet from.number étant le numéro de téléphone virtuel lié à mon Applications Vonage, et le to.number est le numéro qui a envoyé le SMS. Comparez cela à un autre objet In-App Member du Client SDK :

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

Lorsqu'un nouvel événement de message est envoyé à la Conversation, l'API de la Conversation consulte le fichier channel pour le membre et y délivrer l'événement de message. Ainsi, pour le premier membre, un SMS sera envoyé via l'API Messages à l'adresse to.number à partir de l'espace virtuel from.number et pour le second membre, elle sera délivrée via In-App Messaging.

Création d'utilisateurs et de membres de l'API Messages

Comme indiqué ci-dessus, l'API Conversation peut créer automatiquement un utilisateur et un membre pour vous, mais si vous souhaitez les créer vous-même, vous pouvez le faire à l'aide du SDK Vonage Server ou de l'API Conversation directement :

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

Cela permet d'abord de créer un utilisateur avec un canal SMS qui contient le numéro de téléphone que l'utilisateur utilisera pour envoyer un SMS. Ensuite, cet utilisateur est ajouté en tant que membre de la conversation avec un canal SMS comme décrit ci-dessus. Les canaux de l'utilisateur sont validés par rapport aux canaux fournis lors de la création d'un membre.