Integración de la Conversation API con WeChat

En esta entrada de blog, te mostraremos cómo utilizar la Conversation API para establecer un canal de comunicación externo con tu aplicación y te demostraremos cómo hacerlo utilizando WeChat.

Utilizaremos la API pública de WeChat y la conectaremos a la API de conversación para permitir la mensajería bidireccional entre un cliente de WeChat y un cliente de Vonage, utilizando eventos personalizados.

Consulte este repositorio GitHub para ver nuestra integración de referencia.

Conceptos

Utilizaremos eventos personalizados para simular los mensajes de WeChat y construir un servidor middleware para interactuar con la API pública de WeChat.

Cuando un cliente desee enviar un mensaje utilizando WeChat, creará un evento personalizado de tipo 'custom:message:wechat' con dirección outbound. A su vez, nuestro servidor middleware recogerá ese evento utilizando eventos RTC y lo traducirá en una solicitud HTTP a la API de WeChat, notificando en un mensaje.

En el caso de un mensaje entrante (de un cliente de WeChat a un cliente de Vonage), nuestro servidor de middleware implementará el webhook de mensajería de WeChat y recibirá una notificación de WeChat sobre el nuevo mensaje. El servidor creará un evento 'custom:message:wechat' con dirección inbound y lo enviará. El cliente recogerá ese evento y lo mostrará como un mensaje WeChat.

An illustration showing the described architecture

Requisitos previos

WeChat

WeChat es una aplicación china de mensajería, redes sociales y pagos móviles desarrollada por Tencent. Cuenta con una base de usuarios de más de mil millones de personas, por lo que es imposible ignorarla como canal de mensajería líder. Se puede relacionar WeChat en China con Facebook en Estados Unidos.

WeChat proporciona una API que permite a los desarrolladores enviar y recibir mensajes. En este post, se utilizará una Account de WeChat junto con el sandbox de WeChat. Tenga en cuenta que esto es para simplificar la configuración con WeChat.

Puede seguir esta guía paso a paso para configurar su API de WeChat. Este paso a paso supone que ya está ejecutando nuestro servidor de integración de muestra.

1. Registre su Account de sandbox desde este enlace

2. Ejecute su servidor. En este ejemplo, utilizaremos ngrok

3. Utilice su dirección ngrok para rellenar la información del webhook. Nuestro punto final del servidor será https://[$NGROK_ADDRESS].com/weChatEvent Sustituye [$NGROK_ADDRESS] por tu dirección ngrok

4. Rellenar cualquier ficha

5. Haz clic en el botón Enviar y espera a que WeChat verifique tu webhook.

6. Ya está listo para recibir mensajes.

WeChat Screenshot

Para empezar a enviar mensajes desde WeChat a nuestro servidor, tienes que añadir la Account oficial a tu WeChat. Para ello, necesitará:

1. Vaya a su cuenta sandbox

2. Desplácese hasta "Código QR del número de prueba".

3. Escanea el código QR con tu WeChat

4. ¡Empieza a chatear!

WeChat Screenshot

Ahora deberías poder enviar mensajes desde tu cliente WeChat a nuestra Account de WeChat y recibirlos en tu instancia en ejecución de nuestro servidor en la ruta /weChatEvent ruta.

Conversation API

La Conversation API es una API de bajo nivel que permite crear varios objetos como Usuarios, Miembros y Conversaciones. Las conversaciones son el concepto fundamental en torno al cual gira la API. Las conversaciones son contenedores de comunicaciones intercambiadas entre dos o más Usuarios que pueden ser una única interacción o el historial de todas las interacciones entre ellos.

Para obtener más información sobre la API, visite nuestra documentación. Necesitará:

1. Una aplicación

2. Una conversación

3. Acceso a su clave y secreto API

Configurar

El archivo example.env contiene todos los parámetros necesarios para poner en marcha la integración. Utilizaremos un identificador de conversación codificado para simplificar este ejemplo, aunque no es obligatorio.

Siga las instrucciones del archivo README y consulte la documentación de documentación de ngrok como ejemplo para un servicio que expondrá su integración.

Después de configurar todos los parámetros necesarios, simplemente ejecute el código utilizando 'npm start'.

Enviar y recibir un mensaje WeChat

Para enviar un mensaje mensaje saliente (desde un cliente de Vonage a un cliente cliente WeChat) necesitaremos crear el siguiente evento personalizado:

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

Para una mensaje entrante entrante (de un cliente WeChat a un cliente de Vonage) tendremos que crear el mismo evento pero invirtiendo su dirección.

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

Eche un vistazo al siguiente fragmento que muestra cómo enviar un evento 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'); 
    }
  });
};

Nuestro cliente de Vonage, a su vez, recibirá el evento personalizado y lo analizará como un mensaje WeChat.

Recapitulemos

En las secciones anteriores hemos aprendido a integrar WeChat con tu aplicación utilizando nuestra Conversation API. Sin embargo, WeChat es solo un ejemplo de lo que puedes integrar con la Conversation API; podría haber sido un canal de mensajería diferente, como WhatsApp, o incluso un canal de comunicación diferente, como el correo electrónico.

La flexibilidad que aporta la Conversation API con sus eventos personalizados permite integrar una amplia variedad de canales de comunicación.

Puede encontrar una versión completa de este tutorial en GitHub

Si desea obtener más información sobre lo que puede hacer con nuestras API, visite nuestro portal para desarrolladores para más información.