Latest news

Building Chatbots For WeChat — Part #2

No comments

Building Chatbots For WeChat — Part #2

Introduction

Welcome to Part #2 of the tutorial! Part #1 introduced the basics of creating a chatbot for the WeChat and Weixin platforms from scratch and test it in a local debugging environment.

In Part #2 some important topics regarding real-world bots will be covered: queues, asynchronous replies and hosting the bot on a PaaS cloudHeroku.

How big is WeChat, again?

In the Part #1 introduction I have shown how bit WeChat is by providing some (impressive) numbers. Then I stumbled upon this article that furtherly stresses the concept:

in China the most important layer of the smartphone stack is not the phone’s operating system. Rather, it is WeChat. [..] WeChat is into the daily lives of nearly 900 million Chinese [..] every aspect of a typical Chinese person’s life, not just online but also is conducted through a single app [..] There is nothing in any other country that is comparable: not LINE, not WhatsApp, not Facebook.

…and even the Economist acknowledged the power of Tencent over Apple in China.

A note on the WeChat sandbox environment

In case you are not able to log into the WeChat sandbox environment and get an Unable to initialize error, try the Weixin sandbox environment. It's the same application, but in Chinese. Using Chrome, the inline Google translator does a good job in turning it to English.

Synchronous and Asynchronous Replies

The WeChat platform allows both synchronous and asynchronous replies to be sent to users interacting with the chatbot. Synchronous replies are easier to implement, but they will not fit in most scenarios. WeChat enforces a 5 seconds timeout for synchronous replies to be sent to output and some kinds of tasks will take more than that in order to be processed. Some requests will need to be dispatched to other services for fulfillment or, depending on the scenario, even filed to human operators for review (think about customer support applications). So the fulfillment might not take place immediately and a sync reply would not do.

The asynchronous reply flow can be implemented in WeChat bots, granting up to 48 more hours to respond. The WeChat platform though always requires an empty synchronous reply within 5 seconds to confirm that the request has been acknowledged and the chatbot backend is working.

The proper flow to handle a request is then:

  1. Validate the request (verify signature, format, …)
  2. Store the request in a queue
  3. Acknowledge the request sending an empty response to output
  4. Process the queued requests and send asynchronous replies

If something fails at steps 1 and 2, an error can be sent back synchronously. Steps 3 and 4 can be parallelized using threads or handled with queues. Threads can fit scenarios when the message processing might take longer than 5 seconds, but it’s immediate, short enough and fully automated. Queues are more flexible and allow better control over systems load and resource usage.

Before moving to the next paragraphs, please note that:

  • async replies in WeChat are available only in the sandbox and to verified “official” accounts (see paragraph: Going Live).
  • request validation and synchronous replies have already been covered in Part #1 of this tutorial

Queuing Basics

Using queues, the 4 steps of the request handling flow introduced in the paragraph above can be broken down in two main blocks:

  • The web process will expose the webhook and handle steps #1 to #3
  • The worker process will handle step #4

The sample application provided with this tutorial implements these steps and wraps them in such two processes. Queuing can be implemented in different ways:

Using Heroku

Queuing in Heroku is very straightforward and strongly recommended as a best practice. Therefore, two kinds of dynos (long story short: dynos act like virtual server instances) are provided to deal with API endpoints and queued background jobs:

  • web dynos are meant to handle the frontend work (like exposing the API endpoints)
  • worker dynos process the queued jobs in background

Heroku will need two separate entry points to run the two different sets of dynos. This is a sample Procfile for an Heroku app:

web: gunicorn src.bot
worker: python src/worker.py

Using such Procfile and adding a scheduling add-on such as the free Heroku Scheduler to your application, the web dyno will run the gunicorn server and load the src/bot.py file to expose the API endpoints on the public network, while the the worker dyno will run the src/worker.py at defined intervals to process background jobs stored in the queue.

The sample application provided with this tutorial was designed to run on Heroku and is ready to be deployed.

Please note that the minimum time interval for the free scheduler is 10 minutes. Such interval might be too long for a real-world application. You can switch to other schedulers such as Temporize Scheduler that offer paid plans with better scheduling, or change the code and use threading to invoke the queue processor in parallel while returning the sync response to WeChat.

Using Amazon Lambda

Queueing can be done with Lambda as well. There are in fact several ways to implement queues in Lambda. The API and queued jobs processing code can be either split in different Lambdas or kept in the same trunk. Splitting the code is probably the cleaner solution, but in the latter case, the request context provided to the Lambda along with the parameters passed with the SNS event can be used to internally dispatch the execution request.

The sample application was not designed to run on Amazon Lambda, but the Python version can be adapted for this purpose. In order to convert the code to Lambda, the Falcon layer should be replaced with the Lambda Function Handler, the rest of the code should be reusable as-is. Environment variables can either be set in the Lambda configuration or as API Gateway stage variables (you will need an API Gateway to let the WeChat server connect to the Lambda).

Using a custom server and a job scheduler

The sample application will also work out-of-the-box on any server. The same commands provided in the Procfiles of the Python and Ruby sample apps should do, as long as the server features the required software packages and dependencies. Make sure that the web process is bound to a public IP address for the WeChat server to connect to it. The worker process should be run from a scheduler process such as crontab.

A “less silly echo bot”: The WeChat Heroku Bot Skeleton

As in Part #1, the sample application for this tutorial comes in two flavours:

This application is an evolution of The Silly Echo Bot and includes a queue manager, invoked by the worker process, that sends delayed messages to users. The included README.md files provide detailed instructions on how to configure and run the application locally (also applies to web servers) and deploy the application to Heroku, so please refer to them.

The code is thoroughly commented and also significantly longer that The Silly Echo Bot code, so I will not go through it here. The code basics in Part #1 can help understand the more advanced code in the sample application provided with this tutorial.

Going Live: applying for an Official Account

In order to apply for an Official Account (OA), several business and legal entity details and a “Company Business Registration” document (such as a Certificate of Good Standing) must be provided. Plus, in order to use some advanced API features (such as asynchronous messaging, which in most cases will be needed), the account must go through a “verification process” and the payment of a verification fee is required (300 RMB / ~45$ at the time of writing).

Please note that the International WeChat account does not allow to interact with users residing in China. In order to do so, you must apply for a Weixin account and such accounts can only be issued to Chinese entities. Weixin OA applications can be filed from the Weixin Admin website, while the WeChat Admin website accepts applications for international accounts. The “verification process” can be initiated after an application has been accepted and the account is activated.

Once again, well done!

Thank you for reading this tutorial. If you enjoyed it, click the ❤ below to recommend it to other interested readers! Feedback and suggestions are also very welcome!


Building Chatbots For WeChat — Part #2 was originally published in Chatbots Magazine on Medium, where people are continuing the conversation by highlighting and responding to this story.

Source: Chatbots Magazine

magnoliaBuilding Chatbots For WeChat — Part #2

Related Posts

Leave a Reply