Intégrer l'API Conversation à WeChat

Dans cet article de blog, nous vous montrerons comment utiliser l'API Conversation pour établir un canal de communication externe avec votre application et nous vous ferons une démonstration à l'aide de WeChat.

Nous utiliserons l'API publique de WeChat et la connecterons à la Conversation API pour permettre une messagerie bidirectionnelle entre un client WeChat et un client Vonage, à l'aide de événements personnalisés.

Veuillez vous référer à ce dépôt GitHub pour notre intégration de référence.

Concepts

Nous utiliserons des événements personnalisés pour simuler les messages WeChat et construire un serveur intermédiaire pour interagir avec l'API publique de WeChat.

Lorsqu'un client souhaite envoyer un message à l'aide de WeChat, il crée un événement personnalisé de type "custom:message:wechat" avec une direction sortante. À son tour, notre serveur intermédiaire récupérera cet événement en utilisant les événements RTC et le traduira en une requête HTTP vers l'API de WeChat, en notifiant un message.

Dans le cas d'un message entrant (un client WeChat vers un client Vonage), notre serveur intermédiaire mettra en œuvre le crochet web de messagerie de WeChat et sera informé par WeChat du nouveau message. Le serveur créera un événement 'custom:message:wechat' avec la direction inbound et l'enverra. Le client récupérera cet événement et l'affichera comme un message WeChat.

An illustration showing the described architecture

Conditions préalables

WeChat

WeChat est une application chinoise polyvalente de messagerie, de médias sociaux et de paiement mobile développée par Tencent. Elle compte plus d'un milliard d'utilisateurs, ce qui en fait un canal de messagerie incontournable. On peut comparer WeChat en Chine à Facebook aux États-Unis.

WeChat fournit une API qui permet aux développeurs d'envoyer et de recevoir des messages. Dans ce billet, un Account WeChat sera utilisé parallèlement au bac à sable de WeChat. Veuillez noter que ceci a pour but de simplifier l'installation de WeChat.

Vous pouvez suivre ce guide étape par étape pour configurer votre API WeChat. Ce guide étape par étape suppose que vous utilisez déjà notre exemple de serveur d'intégration.

1. Enregistrez votre Account sandbox à partir de ce lien

2. Exécutez votre serveur. Dans cet exemple, nous utiliserons ngrok

3. Utilisez votre adresse ngrok pour remplir les informations du webhook. Le point de terminaison de notre serveur sera https://[$NGROK_ADDRESS].com/weChatEvent Remplacez [$NGROK_ADDRESS] par votre adresse ngrok

4. Remplir n'importe quel jeton

5. Cliquez sur le bouton d'envoi, et attendez que WeChat vérifie votre webhook

6. Vous êtes maintenant prêt à recevoir des messages !

WeChat Screenshot

Pour commencer à envoyer des messages de WeChat vers notre serveur, vous devez ajouter le compte officiel à votre WeChat. Pour ce faire, vous devez

1. Accédez à votre Account du bac à sable

2. Faites défiler vers le bas jusqu'à "Code QR du numéro de test".

3. Scannez le code QR à l'aide de votre WeChat

4. Commencez à discuter !

WeChat Screenshot

Vous devriez maintenant être en mesure d'envoyer des messages depuis votre client WeChat vers notre Account WeChat et de les recevoir sur votre instance en cours d'exécution de notre serveur sur la route /weChatEvent route.

Conversation API

L'API Conversation est une API de bas niveau qui vous permet de créer divers objets tels que des utilisateurs, des membres et des conversations. Les Conversations sont le concept fondamental autour duquel tourne l'API. Les conversations sont des conteneurs de communications échangées entre deux ou plusieurs utilisateurs. Il peut s'agir d'une seule interaction ou de l'historique de toutes les interactions entre eux.

Pour en savoir plus sur l'API, vous pouvez consulter notre documentation. Vous aurez besoin de :

1. Une application

2. Une conversation

3. Accès à votre clé API et à votre secret

Mise en place

Le fichier example.env contient tous les paramètres nécessaires à la mise en œuvre de l'intégration. Nous utiliserons un identifiant de conversation codé en dur pour simplifier cet exemple, mais ce n'est pas obligatoire.

Veuillez suivre les instructions données dans le fichier README et vous référer à la documentation de documentation ngrok comme exemple de service qui exposera votre intégration.

Après avoir défini tous les paramètres requis, il suffit d'exécuter le code en utilisant "npm start".

Envoi et réception d'un message WeChat

Pour envoyer un sortant (à partir d'un client Vonage à un WeChat), nous devons créer l'événement personnalisé suivant :

{
	"type":"custom:wechat:message",
	"body":{
		"to":"we_chat_client_id",
		"from":"we_chat_integration_id",
		"content":"Hello from Vonage!",
		"direction":"outbound"
	}
}

Pour un entrant (provenant d'un client WeChat vers un client Vonage), nous devrons créer le même événement, mais en inversant sa direction.

{
	"type":"custom:wechat:message",
	"body":{
		"to":"we_chat_integration_id",
		"from":"we_chat_client_id",
		"content":"Hello from WeChat!",
		"direction":"outbound"
	}
}

Jetez un coup d'œil à l'extrait suivant qui montre comment envoyer un événement WeChat :

const dispatchWeChatEvent = (wechat, direction = 'inbound') => {
  var options = {
    uri: `https://api.nexmo.com/v0.1/conversations/${conversationId}/events`,
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + jwt,
      Accept: 'application/json',
      'Content-Type': 'application/json'
    },
    json: {
      type: 'custom:wechat:message',
      body: {
        to: wechat.getTo(),
        from: wechat.getFrom(),
        content: wechat.getContent(),
        direction
      }
    }
  };

  request(options, (error, response, body) => {
    if (!error && response.statusCode == 200) {
      console.log('successfully sent WeChat message'); 
    }
  });
};

Notre client Vonage, à son tour, recevra l'événement personnalisé et l'analysera comme un message WeChat.

Récapitulation

Nous avons appris dans les sections précédentes comment intégrer WeChat à votre application à l'aide de notre API Conversation. Cependant, WeChat n'est qu'un exemple de ce que vous pouvez intégrer avec la Conversation API ; il aurait pu s'agir d'un canal de messagerie différent, tel que WhatsApp, ou même d'un canal de communication différent, tel que l'email.

La flexibilité qu'apporte la Conversation API avec ses événements personnalisés vous permet d'intégrer une grande variété de canaux de communication.

Pour une version complète de ce tutoriel, vous pouvez le trouver sur GitHub

Si vous souhaitez en savoir plus sur ce que vous pouvez faire avec nos API, veuillez consulter notre portail des développeurs pour en savoir plus !