Building a WeChat (Weixin) robot

Matt presented a talk on Building a WeChat robot at Barcamp Shanghai Spring 2014! Here's a recap of the talk, as well as a link to download the source code of the robot.

Now, robots are cool, but building a real robot requires lots of hardware knowledge.

Weixin Bot.004

And one common topic you'll notice in today's talk is that I am quite lazy.

Weixin Bot.003

So when I say "robot" I'm talking about a robot you can build with software: a chatterbot. Send a message to a WeChat account, and get a message back.

Why WeChat? WeChat is ubiquitous in China, and so it's a great way of getting your service in front of as many people as possible, without them having to download another app.

Weixin Bot.005

Now you or I have personal WeChat accounts, but if we want to build a bot we need an official account. There are two types of these, Subscription Accounts and Service Accounts.

Weixin Bot.007

Subscription Accounts are best for marketing purposes. You have the ability to send up to 5 "broadcasts" each month to all your followers - perhaps if you are a restaurant, you want to announce some new specials. The downside of subscription accounts is they are hidden away in the WeChat interface inside the Subscription Accounts section.

Service Accounts are listed in the main WeChat friends list. You're only allowed to send one broadcast a month. But, any time someone sends you a message, you can reply to them immediately, and also send them messages for up to 48 hours. So, if you're trying to do customer service via WeChat, or build a bot, a Service Account is a great choice.

Here's the signup form for a WeChat official account (currently Chinese only).

Weixin Bot.008

You'll need to provide some basic information like name, email address, and which type of account you want. The two pieces of information that may require some effort are the 营业执照 (Company License) and 组织机构代码证 (Organization number). Right now you'll need to have a Chinese company license to apply for a WeChat official account.

After submitting all your data, be prepared to wait. It will take about 3 business days for your app to get approved.

Weixin Bot.009

One you're finally approved, you have access to the WeChat API. This comes in two flavours: basic API and advanced API. The basic API provides all that we need to build a basic chatterbot!

Weixin Bot.010

In the Developers section, you now need to provide a URL and Token. At the URL provided, you now need to provide a simple web server. This will listen for requests from the WeChat server. So, for example every time someone sends you a message, you receive an HTTP request with the details of their message.

Weixin Bot.012

For our backend server we used a simple stack running on Heroku, with Node.js and Express, but you could use any language and framework, like Ruby on Rails, or PHP.

Weixin Bot.013

When you first register an application with WeChat they will send you an authorization request to your URL. This includes the token you provided earlier, plus various other OAuth credentials, and an parameter called "echo_str", which you should return if everything checks out OK.

As mentioned previously, I'm quite lazy, so to avoid having to figure out the authentication issues, I simply return the echo_str for ALL requests. This should not be recommended in a production application.

Weixin Bot.016

Now, each time you receive a message to your account, you'll get an HTTP request. You may be hoping for a nice JSON payload.

Weixin Bot.017

Unfortunately, Tencent decided to use XML, and not very well structured XML at that.

Weixin Bot.018

Here's what a typical incoming message looks like.

Weixin Bot.019

You get a FromUserName and ToUserName. These are actually encrypted so you don't have access to the user's real WeChat ID. There's also a timestamp, the type of message (in this case text, but it could also be image, video or voice) and the text content.

To parse this in Node.js, we install an npm package called express-xml-bodyparser and configure Express to use it.

Weixin Bot.020

Next, we implement a method to handle the request. We parse the values out of the XML...

Weixin Bot.021

Then we construct some XML to send back as a response. Notice that we've switched the to username and from username, to ensure the message gets sent back to the recipient. The text of our reply is "Thanks for sending me a message saying (original message)".

Weixin Bot.022

How does this work? Like this!

Weixin Bot.023

Now this is great, but of course version 1 of our robot is pretty stupid. How can we imbue our bot with some more intelligence?

To solve this I turned to the work of Joseph Weizenbaum.

Weixin Bot.024

He was a brilliant German-American computer scientist based at MIT. In 1966 he wrote a program called ELIZA. ELIZA was one of the first programs which tried to interpret and respond to natural language inputs from users.

It did this via some basic pattern matching. ELIZA could be fed with different scripts of patterns, and the most famous of these, called "DOCTOR", imitated a psychiatrist.

Weixin Bot.026

Here's ELIZA in action. You can see that ELIZA picks out certain words in a statement, and is able to formulate a reply using the words.

Weixin Bot.025

Now you're just talking nonsense!
> What makes you believe now I am just talking nonsense?

Weizenburg was surprised to discover that despite the primitiveness of the logic, users became quickly emotionally involved with interacting with ELIZA.

ELIZA is a fascinating episode in computing history, and I was delighted to see that the ELIZA logic is available as a npm module. That means integrating it into my bot was very simple.

First, install the module

Weixin Bot.027

Then, replace the reply logic with a new function.

Weixin Bot.028

Here's the code for replying. We keep a dictionary of ElizaBot objects. That way we can give each unique user who messages us their own instance. That means the message "memory" can be kept distinct.

If this is a new user, we set up a new ElizaBot for them, and request an initial phrase like "Please tell me your problem".

Weixin Bot.029

If this is an existing user, we simply call eliza.transform to get a suitable response, based on the last line of input (and previous inputs).

Weixin Bot.030

Let's see how this works:

Weixin Bot.031

There seems to be great potential for using ELIZA for people who are interested in app development services in Shanghai 😉

Weixin Bot.032

Of course, while this is a fun example, there's lots of cool stuff you could make with WeChat robots. A robot could return weather or air quality data on demand. If a user sends you a picture, you could do image processing on that picture and send them back something really creative. The only limit is your imagination!

Weixin Bot.034

 

To download the source code, check out the project on GitHub

Interested in finding out more about what's possible with WeChat, chatbots or mobile apps? Contact us!

Matt Mayer

Matt Mayer is a founder at ReignDesign. Matt is from the UK and was based in Shanghai for ten years. He is now living in Bangkok, Thailand.

14 comments

  1. Congrats! Looks like you’re the only English-speaking person who decided to share their experience of building a WeChat bot.

    Would you care to update your tutorial?

    Since then it appears WeChat has added several international pages, e.g. for registering a developer account: dev.wechat.com, and apply for an official account: http://admin.wechat.com/, also docs. Unfortunately none of that helps me, because everything seems to be designed and programmed terribly. I could not register a dev account for some reason, when I submit the form, nothing changes. The server responds with 200 and a JSON containing an error { ec: 21, em: “reg forbid” } (classic!). So it appears my “reg” was “forbid”, but no-one tells me why. Some of my colleagues were able to register, but the admin panel is also full of bugs, and they could not apply for an App.

    I’m struggling with this several days, and so far only have frustration from how badly everything is done.

        1. Right. To be frank, Tencent don’t really care about foreign companies, so the English-language developer site is a mess. Your best bet might be to find a Chinese partner to help sign you up under their company registration using the Chinese site.

  2. Hi Matt,
    I’m a software engineer based in France, and I use wechat a lot and also have group chats.
    I have been looking for Java API to process Wechat messages, and your blog provides interesting information.
    I do have a question and hope you can help.
    Do you know if there is a way by API to grab the messages in a group chat, or in one’s private chat? I’d like to redirect some group chat or private messages to some UI, and provide a reply from time to time.

  3. Hi Matt,

    Thank you for this great post! I read through the article and was about to get my hands dirty but the GitHub link gave me a 404…if it is possible could you please check that? Thanks a lot!

  4. How to log WeChat’s history?
    Hi, I would like to receive chat logs (ideally, automatically) from WeChat.
    The point is we use WeChat for corporate communication with couple Asian partners and would like to share dialogs with the whole team.
    it is important that all sides are agreed to save history outside of WeChat, so we are ok with all possible options.

  5. Hi Matt, thank you for so cool post.
    I do have a question and hope you can help.
    My task is to create a feed widget from latest posts from official account (I have access to that official account). Am I able to grab them using API or something like that?

  6. Hi! If I have a chatbot working for Skype, KIK and Facebook Messenger is it “easy” to connect the same bot to work with WeChat? I have been using the bot developer framework from Microsoft that has channel available for different platforms (not WeChat though).

Leave a Reply

Your email address will not be published. Required fields are marked *