Skip to main content

WeChat

Connect a WeChat Customer Service account (微信客服) to the platform. People write to the account from WeChat, your AI agent answers them, and your agents can reply from the Inbox. The connection goes through an app that you create in your company's WeCom (企业微信) admin console.

Read this first: WeChat has no buttons or carousels

WeChat Customer Service can't show buttons, quick reply chips or swipeable carousels. This is a WeChat rule, and no platform can change it. Your AI agent's quick replies and cards still work, but they look different from the web widget or WhatsApp:

  • Quick replies arrive as one message: the question, then each option as a blue line that the customer taps.
  • A carousel arrives as one message per card, one under the other. Customers can't swipe through the cards.
  • A card's picture shows only when the card has exactly one link button, or nothing but the picture.
  • Each customer message allows up to 5 replies, so a carousel with many cards is cut off.

See How replies look in WeChat for what your customers see, and Limitations for everything WeChat doesn't support.

How it works​

  1. A customer opens your WeChat Customer Service link or QR code in WeChat and sends a message.
  2. WeCom tells the platform that a new message is waiting. It does this through the Webhook URL that you save in WeCom.
  3. The platform fetches the message, and your AI agent replies to the customer in WeChat.
  4. Your agents see the conversation in the Inbox, under the customer's WeChat name and photo, and can reply there.

How replies look in WeChat​

These screenshots were taken in WeChat on a phone.

Quick replies​

WeChat shows quick replies as a menu message: the question, then each option as a blue line. When the customer taps an option, WeChat sends it back as the customer's reply, and your AI agent continues the conversation. An option with a link opens the link instead.

Quick replies in WeChat: the question, then the options Yes, No, Maybe and Open yellow.ai as blue lines
  • A menu shows up to 10 options. Any more are left out.
  • Option labels longer than 128 bytes (about 40 Chinese or 128 English characters) are cut.

Cards and carousels​

Each card arrives as its own menu message: the card's title and text, then its buttons as blue lines. A carousel with three cards arrives as three messages.

A three-card carousel in WeChat, shown as three separate messages, each with Select and Open yellow.ai as blue lines
  • Customers can't swipe through cards. They see one message per card.
  • Each card counts as one of the 5 replies allowed per customer message.
  • WeChat sometimes shows the cards in a different order, as in the screenshot above, where card 3 arrived before card 2.

Cards with pictures​

WeChat can't show a picture and buttons in the same message, so:

  • A card with only a picture arrives as the picture.
  • A card with a picture and exactly one link button arrives as a WeChat link card: the picture, the title and the text. Tapping it opens the link. Titles over 128 bytes and texts over 512 bytes are cut.
  • Any other card arrives as its title and text, with its buttons as blue lines, or as plain text if it has no buttons. Its picture isn't shown.
A card with only a picture arrives as the picture, and the next card, with a title, text and a Select button, arrives as a menu message

Text arrives as plain text, and formatting such as bold or headings isn't applied. Videos play in the chat, files arrive as a file to open, and web views arrive as their link.

A video, a PDF file named my report.pdf and a web view link, as they appear in WeChat

Who it's for​

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

Before you start​

You need:

  1. A WeCom organization, and an admin account that can manage its apps and WeChat Customer Service. The organization's super admin can do both.
  2. A WeChat Customer Service account in that organization, or the right to create one.
  3. At least one member signed in to the WeCom phone app with a phone number or with WeChat. A member who signed in with only an email address doesn't count. Until someone has signed in this way, WeChat doesn't deliver any reply.
  4. The region of your AI agent (r1 to r8), to allow the right IP addresses. Ask your Yellow.ai contact if you're not sure. WeChat isn't available for AI agents in the India region (r0).
  5. The AI agent and the environment that should answer WeChat, for example Staging while you test. Each environment has its own Webhook URL.

Keep the WeCom admin console (work.weixin.qq.com) and the platform open side by side. The WeCom admin console may be in Chinese, so the steps give each Chinese label in brackets.

The details you'll copy​

DetailWhat it isWhere you find it
Corp IDYour WeCom organization's ID, for example ww1a2b3c4d5e6f7a8b. WeCom calls it Company ID (企业ID).WeCom: My Company (我的企业) > Company Information, at the bottom
AgentIdThe number of the app you create, for example 1000002.WeCom: your app's page
SecretThe app's password.WeCom: your app's page. WeCom sends it to your WeCom phone app.
TokenA code that WeCom uses to sign the messages it sends. Up to 32 letters and digits.WeCom: your app's Receive messages (接收消息) settings
EncodingAESKeyA key that WeCom uses to encrypt the messages it sends. Exactly 43 letters and digits.WeCom: your app's Receive messages (接收消息) settings
Webhook URLThe address where WeCom tells the platform about new messages.The platform: the WeChat page

Connect WeChat​

Follow the steps in this order. WeCom checks the Webhook URL the moment you save it there, and the platform can answer that check only after it has your app's details.

Step 1: Create the app in WeCom​

  1. Go to work.weixin.qq.com, click Login, and scan the QR code with the WeCom phone app.

  2. Go to App Management (应用管理) > Apps. Under Self-built (自建), click Create an app (创建应用).

    The Apps page in the WeCom admin console, with Create an app under Self-built
  3. Upload an App Logo and enter an App Name. Under Allowed users (可见范围), click Add and choose who can use the app: include the people who answer your WeChat Customer Service chats (接待人员), or simply the whole company. If one of them isn't an allowed user, WeCom refuses the app's calls. Then click Create an app.

    The Create an app form, with an app logo, an app name and an allowed user
  4. The app's page opens. Copy the AgentId.

    The app's page, showing the AgentId, the Secret with a View link, the allowed users and the Receive messages card
  5. Next to Secret, click View (查看), then Send (发送). WeCom never shows the Secret on the website: it arrives in your WeCom phone app, in a message from WeCom Team. Copy it from there.

    The View Secret window, with the Send button that sends the Secret to the WeCom phone app
    note

    Use the Secret of the app you just created. The WeChat Customer Service app has a Secret of its own, and it doesn't work here.

  6. Go to My Company (我的企业) > Company Information, and copy the Company ID (企业ID) at the bottom of the page. The platform calls it Corp ID.

    The My Company page, with the Company ID at the bottom
  7. Go back to your app's page. On the Receive messages (接收消息) card, click Set to receive messages via API (设置API接收).

  8. On Message-receiving server configuration, click Get randomly (随机获取) next to Token, and again next to EncodingAESKey. Copy both values.

  9. Under Select the event types of messages you want to receive, tick WeChat Customer Service Messages and Events.

  10. Leave this page open, and don't click Save yet.

The Message-receiving server configuration form, with the URL, Token and EncodingAESKey fields and the event types to receive

Step 2: Connect the app on the platform​

  1. Open the AI agent and the environment that should answer WeChat.
  2. On the switcher, click Channels. Click Messaging, then click WeChat.
  3. Enter the Corp ID (the Company ID you copied), AgentId, Secret, Token and EncodingAESKey, and click Save.
  4. The platform checks the Corp ID and the Secret with WeCom. When they're right, you see WeChat connected successfully, and the page shows your Corp ID and AgentId under Connected account. If you see an error instead, look it up in Troubleshooting.
  5. At the top of the connected account, click Webhook URL to copy it.

The Webhook URL is your region's address followed by your AI agent's ID, for example https://r6.nexus.yellow.ai/integrations/weChat/receive/x1234567890123. It stays the same each time you connect this AI agent, and it's also shown in the blue box above the form before you connect.

Step 3: Save the Webhook URL in WeCom​

  1. Go back to the Message-receiving server configuration page that you left open.
  2. Paste the Webhook URL into URL.
  3. Check that Token and EncodingAESKey still show the values you saved on the platform, and click Save (保存).

WeCom checks the URL as soon as you save. If WeCom says that the check failed, see WeCom says the URL check failed in Troubleshooting. Once the URL is saved, the page shows it under Receive Messages via API, with the event types you ticked. To change the URL later, click Edit.

Receive Messages via API after saving: the URL, the hidden Token and EncodingAESKey, Edit and Delete, and the event types received, including WeChat Customer Service Messages and Events

Step 4: Allow the platform's IP addresses​

WeCom accepts calls only from the IP addresses that you trust. Without this step, customers' messages don't reach your AI agent, and no reply is sent.

  1. On your app's page, scroll down to Developer API. Under Company's Trusted IP (企业可信IP), click Settings.

    The Developer API section of the app's page, with Settings under Company's Trusted IP
  2. Enter the IP addresses of your region, separated by ;, and confirm:

    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
    The Company's Trusted IP window, with two IP addresses separated by a semicolon

WeCom can take about a minute to apply the change. Do this step before step 5: until the IP addresses are set, WeCom shows Trusted IP not configured next to your app there.

Step 5: Give your WeChat Customer Service account to the app​

  1. Go to App Management (应用管理) > Apps, and under Basic, click WeChat Customer Service (微信客服). If you don't have an account yet, click Create Account, and give it a name and a photo.

  2. Next to Apps that can call APIs (可调用接口的应用), click Setting.

    The WeChat Customer Service page, with Setting next to Apps that can call APIs
  3. Tick your app, and click Confirm.

    The Set apps that can call APIs window, with the app ticked
  4. You see Configured successfully. Click Set now.

    Configured successfully, with 1 app configured and the Set now link under Apps that can call APIs
  5. Under In-house development (企业内部开发), click … under Operation, then Configure Customer Service Account.

    The menu under Operation, with Configure Customer Service Account
  6. Select the WeChat Customer Service accounts that the app should manage, and click OK. Each account now appears next to your app.

    In-house development, showing the app and the customer service account that it manages
caution

Once the app manages an account, WeChat's own reception rules for that account stop, and every conversation goes to the platform. An account can be managed by only one app at a time.

Step 6: Test the channel​

  1. Open WeChat Customer Service (微信客服) again, and click your account. Its page says that the account is managed by your app. Next to Connection Link, click Copy Link or Generate QR Code.

    The Customer Service Account Details page, managed by the app, with Copy Link and Generate QR Code next to Connection Link
  2. On a phone, open the link or scan the QR code with WeChat, and send Hi.

  3. Your AI agent replies within a few seconds. The conversation also appears in the Inbox, under your WeChat name.

What customers can send​

Customer sendsWhat your AI agent and agents get
TextThe text. WeChat's own emoji arrive as words in brackets, for example [微笑] (smile).
A tap on a menu option that your AI agent sentThe option, as if the customer typed it.
ImageThe image.
Voice messageAn AMR audio file. Most browsers can't play AMR, so download the file to listen. Your AI agent gets the file, not the words, so it can't answer what was said.
VideoThe video. Some videos arrive as a file instead.
FileThe file.
LocationThe location.
LinkThe link's title, description and address, as text.
Contact card[Contact card] WeCom user, followed by the person's WeCom ID. WeCom doesn't share the name.
Mini Program[Mini Program], followed by its title, app ID and page.
WeChat Channels productFor example [Product] Running shoes, ¥299.00, Shop name, product 3600001.
WeChat Channels order[Order], followed by the products, price, status, shop and order number.
WeChat Channels post, live stream or profileFor example [WeChat Channels post], followed by its title and author.
Forwarded chat history[Chat history] and its title, then one line per message with the sender's name and the text. Pictures and files inside show as [image] or [file].
Meeting, calendar event or note[Meeting], [Calendar event] or [Note]. WeCom doesn't share the details.
Anything elseIts type in brackets, so no message is lost.

Each of these reaches your AI agent as a message that it can answer.

What your AI agent and agents can send​

ReplyHow it looks in WeChat
TextPlain text. WeChat allows 2,048 bytes per message, about 2,000 English or 680 Chinese characters, so a longer reply arrives as several messages.
Quick repliesA menu message, with each option as a blue line. See Quick replies.
Cards and carouselsOne menu message per card. See Cards and carousels and Cards with pictures.
ImagesJPG and PNG images up to 10 MB show as pictures. WebP images are changed to PNG first. GIFs and other formats arrive as a file, so they don't move.
VideosMP4 videos up to 10 MB play in WeChat. Other videos arrive as a file.
AudioAMR audio up to 2 MB arrives as a voice message. Other audio arrives as a file.
FilesFiles up to 20 MB.
LocationA WeChat location.
Web viewIts link, as text.

Images, videos, audio and files must be uploaded to the platform. Links to files on other websites aren't sent.

Limitations​

WeChat's rules for conversations​

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

  • The customer writes first. You can't start a conversation, or send notifications, reminders or campaigns, on WeChat. Your AI agent and agents can only reply.
  • Reply within 48 hours. You can reply only within 48 hours of the customer's last message.
  • 5 replies per customer message. Each message from a customer allows up to 5 replies, until the customer writes again. A long text that is split, and each card of a carousel, count as separate replies. In the screenshot below, the AI agent sent six replies to one message, and WeChat delivered five.
  • 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 limit.
Six replies sent to one customer message: WeChat delivered five

When WeChat refuses a reply, the reply is marked as failed in the conversation, with the reason. See Troubleshooting.

What WeChat doesn't show​

  • No buttons, quick reply chips or carousels. See How replies look in WeChat.
  • No typing indicator. Customers don't see that a reply is being typed.
  • No read receipts. You see whether a reply was sent or failed, but not whether the customer read it.
  • No greeting when the chat opens. Your AI agent replies once the customer writes. Opening the chat on its own doesn't bring a greeting.
  • No text formatting. Bold, italics and headings aren't applied.
  • No moving GIFs. A GIF arrives as a file.
  • Replies can arrive out of order. When a reply has several parts, such as a carousel, WeChat sometimes shows them in a different order.

Messages from customers​

  • WeChat's own emoji arrive as words in brackets, for example [微笑] (smile).
  • Voice messages arrive as AMR files. Most browsers can't play them, and your AI agent can't understand them.
  • Some videos arrive as a file instead of a video.
  • Contact cards show only a WeCom ID, and meetings, calendar events and notes arrive without their details, because WeCom doesn't share them.
  • A message that the customer withdraws stays in the conversation.
  • Messages sent before you connect aren't brought in.

Setup​

  • One app, one AI agent. A WeCom app has one Webhook URL, so it sends its messages to only one AI agent, in one environment. To move WeChat to another environment, for example from Staging to Live, connect WeChat there, save that environment's Webhook URL in WeCom, and then disconnect the old environment.
  • One account, one app. A WeChat Customer Service account can be managed by only one app at a time, and WeChat's own reception rules for it stop once the app manages it.
  • Not in the India region. WeChat isn't available for AI agents in r0.
  • To change the details, disconnect and connect again. The WeChat page doesn't edit a saved connection. If you get a new Token or EncodingAESKey in WeCom, save the same values on the platform. If you reset the Secret in WeCom, connect again with the new one.
  • Disconnecting doesn't change WeCom. It removes the app's details from the platform. Remove or change the Webhook URL in WeCom as well.

Troubleshooting​

When you save on the platform​

MessageWhyWhat to do
This Corp ID does not look right or WeCom does not recognise this Corp IDThe Corp ID has a typo.Copy the Company ID again from My Company (我的企业) > Company Information, and paste it into Corp ID.
WeCom refused this Secret for the Corp IDThe Secret is wrong or belongs to another app, or the app is disabled.Next to your app's Secret, click View again, copy the Secret from your WeCom phone app, and check that the app is enabled.
This AgentId is not the app the Secret belongs toThe AgentId and the Secret come from different apps.Copy both from the same app's page.
The AgentId is a numberThe AgentId has extra characters.Copy it again from your app's page.
The Token is up to 32 letters and digits or The EncodingAESKey is 43 letters and digitsThe value was cut short or has extra characters.Copy it again from your app's Receive messages (接收消息) settings.
WeCom refused these details 3 times. Wait 15 minutesAfter 3 refusals, the platform waits 15 minutes before it checks again.Wait 15 minutes, check the Corp ID and the Secret, and save again.
Could not reach WeCom or WeCom is busyWeCom didn't answer.Try again in a minute.

When you save the Webhook URL in WeCom​

ProblemWhyWhat to do
WeCom says the URL check failedThe details aren't saved on the platform yet; the Token or EncodingAESKey differs from the one on the platform, for example because you clicked Get randomly again; or the URL belongs to another AI agent or environment.Save the details on the platform first. Make the Token and EncodingAESKey the same on both sides: if you changed them in WeCom, disconnect on the platform and connect again with the new values. Copy the Webhook URL from the WeChat page of the AI agent that you connected.
WeCom doesn't accept the Webhook URL's domainSome WeCom organizations accept only domains that are registered (ICP) under their own company.Contact your Yellow.ai team.

After you connect​

ProblemWhyWhat to do
Customers' messages don't reach your AI agentThe IP addresses aren't trusted or are for another region, the account isn't given to the app, or the Webhook URL isn't saved in WeCom.Check steps 3, 4 and 5, and check that the IP addresses are for your AI agent's region.
A reply fails with No WeCom member has logged in to the WeCom appNobody in your organization has signed in to the WeCom phone app with a phone number or with WeChat.Sign in to the WeCom phone app with a phone number or with WeChat.
A reply fails with More than 48 hours since the customer last wrote or WeChat allows 5 replies per customer messageWeChat's rules.Wait for the customer to write again.
A reply fails with The WeCom company is not verifiedWeChat limits organizations that aren't verified.Verify your organization in WeCom.
A reply fails with The customer refused messagesThe customer turned off messages from your account.Nothing to do.
A reply fails with WeCom … failed: 60020WeCom doesn't trust the platform's IP addresses.Add your region's IP addresses, as in step 4.
A reply fails with WeCom … failed: 60030Someone who answers the account's chats can't see your app.Add them, or the whole company, under Allowed users (可见范围) on your app's page.
A reply fails with another WeCom … failed codeWeCom refused the call.Look up the code in WeCom's error codes.

References​

  1. WeChat Customer Service: overview
  2. WeChat Customer Service: receive messages and events
  3. WeChat Customer Service: send messages
  4. Callback configuration
  5. Upload temporary media
  6. Global error codes