Skip to main content

WeChat

WeChat connects a WeChat Customer Service account (微信客服) to the platform through a WeCom (企业微信) app that your organization owns. People write to the account from WeChat, your AI agent answers them, and your agents can reply from the Inbox.

Beta

This channel is in Beta. WeCom decides which callback URLs and IP addresses it accepts for an app, so try the setup with a test WeCom organization before you connect your main one.

Overview​

After you connect a WeCom app:

  • Messages come in on their own. When someone writes to your WeChat Customer Service account, WeCom notifies the platform, and the platform fetches the new messages. Messages sent before you connected are not brought in.
  • Your AI agent answers. Each message is answered like any other incoming message.
  • Your team can reply from the Inbox. Agents see WeChat conversations in the Inbox and reply there. A reply that WeChat refuses is marked as failed, with WeChat's reason.

Who it's for​

  • Admins set up the WeCom app and connect it on the platform.
  • Agents reply to WeChat conversations from the Inbox.

What you need before you connect​

  1. A WeCom organization, and an account that is its super admin. Only a super admin can hand a WeChat Customer Service account to an app.
  2. A WeChat Customer Service account in that organization, or the right to create one.
  3. The region of your AI agent (r1 to r8), to know which IP addresses to allow. Ask your Yellow.ai contact if you're not sure. WeChat isn't available for AI agents in the India region (r0).

Connect WeChat​

The setup moves between the WeCom admin console and the platform. WeCom checks the platform's URL the moment you save it there, and the platform can only answer that check once it has your app's details.

Step 1: Create the app in WeCom​

  1. Sign in to the WeCom admin console at work.weixin.qq.com.
  2. Go to App Management and, under Self-built, create an app. Give it a name and a logo, and choose who can see it.
  3. On the app's page, copy the AgentId. Next to Secret, click View, then Send. The Secret arrives in your WeCom app; copy it from there.
  4. Go to My Company and copy the Corp ID shown at the bottom of the page.
  5. Back on the app's page, open Receive messages and choose Set to receive messages via API. Click Get randomly next to Token and next to EncodingAESKey, and copy both values. Tick WeChat Customer Service Messages and Events. Leave this page open and don't click Save yet.

Step 2: Connect the app on the platform​

  1. On the switcher, click Channels.
  2. Click Messaging, then click WeChat.
  3. Enter the Corp ID, AgentId, Secret, Token and EncodingAESKey, and click Save. You see WeChat connected successfully.
  4. Copy the Webhook URL shown on the page.

Step 3: Finish the setup in WeCom​

  1. On the Set to receive messages via API page you left open, paste the Webhook URL into URL and click Save. WeCom checks the URL straight away. If the check fails, make sure the Token and EncodingAESKey on that page are the ones you saved in step 2.

  2. On the app's page, open Company's Trusted IP and add the IP addresses of your region, separated by ;:

    RegionIP addresses
    r1129.151.139.158; 129.151.132.226
    r2108.136.205.230; 108.137.122.1; 108.137.171.143
    r318.138.125.225; 18.139.149.20; 13.213.140.63
    r435.84.216.215; 35.83.102.39; 34.212.108.52
    r552.51.139.165; 54.73.244.109; 34.253.39.147
    r620.173.116.38; 20.21.2.200; 20.21.131.95
    r734.166.81.74; 34.166.146.65; 34.166.142.59
    r8145.241.139.22

  3. Go to Apps > WeChat Customer Service, open API, and under Apps that can call APIs, select the app you created.

  4. Choose the WeChat Customer Service accounts the app manages. If you don't have one yet, click Create Account first.

To test the channel, open the account's link or QR code in WeChat on a phone and send a message.

Once connected, the WeChat page shows the Corp ID and AgentId under Connected account.

What can be sent and received​

Messages from WeChat users:

  • Text, and taps on the menu options your AI agent sent.
  • Images, voice messages, videos and files. Voice messages arrive as AMR audio files.
  • Locations and links.
  • Contact cards, Mini Programs, WeChat Channels products, orders and posts, and forwarded chat histories. Each arrives as a line of text that describes it, for example [Product] Running shoes, ¥299.00, Shop name, so your AI agent can answer it.
  • Meetings, calendar events and notes. WeCom doesn't share what's in them, so they arrive as [Meeting], [Calendar event] and [Note].

Replies from your AI agent or your agents:

  • Text. WeChat allows 2,048 bytes per message, so a longer reply is sent as several messages.
  • Quick replies and cards, sent as WeChat menu messages that people tap. Each card is sent as its own menu. A card with one link button and an image uploaded to the platform is sent as a WeChat link card instead, which shows the image.
  • Images, videos, audio and files uploaded through the platform. WeChat shows JPG and PNG images and MP4 videos up to 10 MB, and AMR voice messages up to 2 MB. WebP images are converted to PNG. Anything else is sent as a file, up to 20 MB.
  • Locations, sent as a WeChat location.
  • Web views, sent as their link.

WeChat's rules for replies​

WeChat sets these limits, and the platform can't change them:

  • 48 hours. You can reply only within 48 hours of the customer's last message.
  • 5 replies per message. Each message from a customer allows up to 5 replies, until the customer writes again. A long text that is split, or a reply with several cards, counts as several replies.
  • 100 customers until you verify. A WeCom organization that isn't verified can serve 100 customers in total. Verify your organization in WeCom to remove this cap.

When WeChat refuses a reply, the reply is marked as failed in the conversation, with the reason, for example More than 48 hours since the customer last wrote.

Good to know​

  • Customers appear by an ID. WeCom identifies each customer by an ID (external_userid), so a conversation shows that ID rather than the person's WeChat name.
  • Connect each app to one AI agent. A WeCom app has one callback URL, so it can send its messages to only one AI agent, in one environment, at a time.
  • To change the details, disconnect and connect again. The WeChat page doesn't edit a saved connection. If you generate a new Token or EncodingAESKey, save the same values in WeCom too.
  • Disconnecting doesn't change WeCom. It removes the app's details from the platform. Change or remove the URL in WeCom as well.

References​

  1. WeChat Customer Service: receive messages and events
  2. WeChat Customer Service: send messages
  3. Receive messages and events from WeCom
  4. Upload temporary media
Last updated on