Integração da Conversation API com o WeChat

Nesta postagem do blog, vamos mostrar como usar a Conversation API para estabelecer um canal de comunicação externo com seu aplicativo e demonstrar como fazer isso usando o WeChat.

Usaremos a API pública do WeChat e a conectaremos à Conversation API para permitir o envio e recebimento de mensagens entre um cliente do WeChat e um cliente da Vonage, utilizando eventos personalizados.

Consulte este repositório do GitHub para ver nossa integração de referência.

Conceito

Vamos usar eventos personalizados para simular mensagens do WeChat e criaremos um servidor de middleware para interagir com a API pública do WeChat.

Quando um cliente deseja enviar uma mensagem pelo WeChat, ele cria um evento personalizado do tipo “custom:message:wechat” com direção de saída. Por sua vez, nosso servidor de middleware capturará esse evento usando eventos RTC e o converterá em uma solicitação HTTP para a API do WeChat, notificando por meio de uma mensagem.

No caso de uma mensagem recebida (de um cliente do WeChat para um cliente da Vonage), nosso servidor de middleware implementará o webhook de mensagens do WeChat e será notificado pelo WeChat sobre a nova mensagem. O servidor criará um evento ‘custom:message:wechat’ com direção de entrada e o despachará. O cliente captará esse evento e o exibirá como uma mensagem do WeChat.

An illustration showing the described architecture

Pré-requisitos

WeChat

WeChat é um aplicativo chinês multifuncional de mensagens, mídia social e pagamentos móveis desenvolvido pela Tencent. Possui uma base de usuários de mais de um bilhão de pessoas, o que o torna impossível de ignorar como um dos principais canais de mensagens. Pode-se comparar o WeChat na China ao Facebook nos Estados Unidos.

O WeChat oferece uma API que permite aos desenvolvedores enviar e receber mensagens. Nesta postagem, será utilizada uma Account do WeChat em conjunto com o ambiente de teste (sandbox) do WeChat. Observe que isso tem como objetivo simplificar a configuração com o WeChat.

Você pode seguir este guia passo a passo para configurar sua API do WeChat. Este guia passo a passo pressupõe que você já esteja executando nosso servidor de integração de exemplo.

1. Cadastre sua conta na sandbox neste link

2. Execute seu servidor. Neste exemplo, usaremos o ngrok

3. Use seu endereço do ngrok para preencher as informações do webhook. O endpoint do nosso servidor será https://[$NGROK_ADDRESS].com/weChatEvent Substitua [$NGROK_ADDRESS] pelo seu endereço do ngrok

4. Preencha qualquer campo

5. Clique no botão “Enviar” e aguarde até que o WeChat Verify seu webhook

6. Agora você está pronto para receber mensagens!

WeChat Screenshot

Para começar a enviar mensagens do WeChat para o nosso servidor, você precisa adicionar o Account oficial ao seu WeChat. Para isso, você precisará:

1. Acesse sua conta de teste

2. Role a página até “Testar o código QR”

3. Digitalize o código QR usando o WeChat

4. Comece a conversar!

WeChat Screenshot

Agora você já deve conseguir enviar mensagens do seu aplicativo do WeChat para a nossa Account do WeChat e recebê-las na instância do nosso servidor em execução na /weChatEvent trajeto.

Conversation API

A Conversation API é uma API de baixo nível que permite criar diversos objetos, como Usuários, Membros e Conversas. As conversas são o conceito fundamental em torno do qual a API gira. As conversas são receptáculos das comunicações trocadas entre dois ou mais usuários, podendo ser uma única interação ou o histórico de todas as interações entre eles.

Para saber mais sobre a API, você pode acessar nossa documentação. Você precisará de:

1. Um pedido

2. Uma conversa

3. Acesso à sua chave e ao seu segredo da API

Configuração

O arquivo example.env contém todos os parâmetros necessários para colocar a integração em funcionamento. Usaremos um ID de conversa predefinido para simplificar este exemplo; no entanto, isso não é obrigatório.

Siga as instruções fornecidas no arquivo README e consulte a documentação do ngrok como exemplo de um serviço que irá expor sua integração.

Depois de configurar todos os parâmetros necessários, basta executar o código usando o comando “npm start”.

Como enviar e receber uma mensagem no WeChat

Para enviar uma mensagem (de um cliente da Vonage para um cliente do WeChat), precisaremos criar o seguinte evento personalizado:

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

Para um mensagem (de um cliente do WeChat para um cliente da Vonage), precisaremos criar o mesmo evento, mas inverter sua direção.

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

Dê uma olhada no trecho de código a seguir, que mostra como disparar um evento do 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'); 
    }
  });
};

Nosso cliente Vonage, por sua vez, receberá o evento personalizado e o interpretará como uma mensagem do WeChat.

Resumo

Aprendemos nas seções anteriores como integrar o WeChat ao seu aplicativo usando nossa Conversation API. No entanto, o WeChat é apenas um exemplo do que você pode integrar à Conversation API; poderia ter sido um canal de mensagens diferente, como o WhatsApp, ou até mesmo um canal de comunicação diferente, como o e-mail.

A flexibilidade que a Conversation API oferece por meio de seus eventos personalizados permite integrar uma ampla variedade de canais de comunicação.

Para acessar a versão completa deste tutorial, você pode encontrá-la no GitHub

Se você quiser saber mais sobre o que pode fazer com nossas APIs, acesse nosso portal do desenvolvedor para saber mais!