FAQ
The questions asked most often during integration, grouped by topic. If you can't find an answer, contact us with the request_id of the failing request.
Integration and authentication
Do I need to get a new App Token before every call?
No. An App Token is valid for 7 days by default (change app_token_ttl_seconds in the runtime policy). Cache and reuse it on your server, and get a new one before it expires. Getting tokens too often uses up your call quota, and each IP can get at most 120 per minute. See Authentication and App Token.
What do I do about 401 unauthenticated?
The App Token has expired or is no longer valid; get a new one and retry. If details.reason in the response is app_deleted or tenant_closed, the app was deleted or the tenant was closed, so don't retry.
Why do I get 403 ip_not_allowed?
The app has an IP allowlist and the request's source IP isn't on it. Add your server's egress IP to the allowlist in the console; see Server credentials and IP allowlist.
Can a website or app call the server REST API directly?
No. An App Token carries admin rights over the whole app, so anyone who gets it can send messages as any user. The server REST API doesn't allow cross-origin calls from browsers; clients should use the user's own User Token.
What do I do about 429 rate_limited?
The request went over the app's call quota. Wait the number of seconds given in the Retry-After header and retry, and check for unnecessary repeated calls (such as getting an App Token every time). If your traffic really is high, contact us to raise the quota; see Rate limits and app status.
How do I separate testing and production?
Create an app for each, each with its own AppKey, credentials and data. You can allow client self sign-up in the test app to make debugging easier.
Users and sign-in
We already have our own accounts. How do users sign in to IM?
The recommended way: when a user signs up, your server creates an IM user with the same name (without a password); when the user needs to sign in to IM, your server verifies who they are and issues a one-time sign-in token, and the client signs in with it. That way IM never stores users' passwords. See Sign-in and devices.
What are the username rules? Can I use phone numbers?
Usernames are unique within the app and case-insensitive; for the rules, see Managing users. Use a user ID from your system that never changes, rather than a phone number or email, which can change and are personal data.
How many devices can a user be signed in on at once?
Up to 4 by default. You can change this in the runtime policy, and choose whether going over refuses the new sign-in or signs out the earliest device. You can also set limits per platform group (such as one phone and one computer); see Multi-device sign-in.
Messages
Can users message each other without being friends?
Yes, by default. If your business only allows one-to-one chat between friends, turn on "One-to-one chat requires friendship" (friend_check_enabled) in the runtime policy. Group chat isn't affected.
How long are messages kept?
90 days by default; change message_retention_days (1 to 3650 days) in the runtime policy. After shortening it, messages past the retention period are deleted and can't be recovered.
Can my server recall any message?
Yes. Users recalling their own messages are bound by the recall time limit (2 minutes by default), but your server calling the recall API isn't. See Recall, edit and pin.
How do I export chat history?
Your server can export all messages in the app page by page in message ID order (good for incremental sync to your own storage), or query one conversation's history or one user's sent messages by time range; see Querying and exporting messages and Conversations and history.
How do I send images, voice, video and files?
Upload the file to the IM service first to get a file URL, then put the URL in the body of a message of the matching type and send it. Uploading takes three steps: create the upload, upload the content straight to object storage, and complete the upload; see Uploading files and Message format.
How long are images and files in messages kept?
Attachments are kept for 30 days from upload by default; change attachment_retention_days in the runtime policy. After that the file is deleted but the message remains, and getting a download URL returns file_expired. Avatars are kept as long as they're in use; group files are kept as long as the group exists by default. See File overview.
Can anyone with a file URL download the file?
No. A file URL in a message can't be downloaded by itself; only users signed in to this app or your server can exchange it for a short-lived download URL, and only group members can for group files. Avatars are the exception: their public URLs can be opened directly.
Will retrying a send create duplicates?
Send with a client_msg_id you generate: when the same sender retries in the same conversation with the same client_msg_id, the message written the first time is returned and no duplicate is created; see Sending messages.
Callbacks
How do I sync chat history to my own system?
Set up event callbacks for the app in the console and subscribe to message events; the IM service then pushes each message to your server after it's sent. You can also export messages page by page with the server API. See Callback overview and Event callbacks.
Can I run my own business checks before users send messages or add friends?
Yes. With sync callbacks set up, the IM service asks your server before users send messages, add friends, join groups and so on, and you can allow, reject or rewrite the content. See Sync callbacks.
How do I know a callback request really came from the IM service?
Every callback request is signed. Check the signature and timestamp as in Verifying callback requests, and reject requests that fail.
Chat rooms, audio/video and push
What's the difference between chat rooms and groups?
A group has fixed members, and messages are kept while members are offline and filled in when they come back. A chat room has no fixed members; only users currently in the room get messages, and no offline messages are kept, which suits live streams and other crowded, fast-moving scenes. See Managing chat rooms.
Do audio/video calls need a separate audio/video service?
No. The IM service handles signaling such as calling, ringing and answering, plus call records, while audio and video travel through the platform's media service, ready to use once enabled. See Audio and video calls.
What if a user isn't getting offline pushes?
Check in turn: whether push credentials for the channel are set up in the console, whether the user's device registered a push token, whether the user turned on Do Not Disturb or conversation Do Not Disturb, and the failure reasons in the console's push stats. See Offline push and Troubleshooting missing pushes.
Billing
How is it billed?
There are two parts, both accounted per app:
- Plan: each app subscribes to a plan, which sets allowances such as users and storage. Bills are shown together per tenant, but each app's plan balance can only pay that app's fees. See Plans and billing.
- Audio/video: calls and standalone RTC channels use the app's own prepaid audio/video duration balance. The default price is CNY 7 per 1000 standard minutes (the console page is authoritative); video is converted to standard minutes by the resolution actually received, and each app's monthly total is rounded once. See Audio/video billing.
What happens when an allowance runs out or payment is overdue?
- A plan allowance is used up (such as users or storage): the matching new actions are rejected; existing data and features aren't affected.
- The audio/video balance is zero or negative: new calls and channels can't be started or joined, with
payment_required. Calls in progress aren't hung up and their usage is still settled, so the balance can go negative; a top-up first covers the negative part. - Overdue legacy tenant bills: still handled by the old rules; see Overdue payments.
Other
Are there client SDKs?
Yes, for websites (including React and Vue), Flutter (Android, iOS, desktop), native Android, Tauri desktop, WeChat mini programs, UniApp and Go. Native iOS (Swift) is still planned; use the Flutter SDK for iOS for now. To choose by platform, see Client SDKs; for versions and known limitations, see Versions and support.
Can a deleted app be restored?
No. Deleting an app clears all its users, friends, groups and messages, and its app_name can't be reused. If you just want to stop service for a while, disable the app instead; it can be re-enabled at any time.
How do I contact technical support?
Send us the failing request's X-Request-ID (the response header, or request_id in the error response), the time of the request and the app's AppKey; see About us.
Standalone RTC channels
Can several people do audio/video without creating a group?
Yes, with standalone RTC channels. Your server creates a channel with its own channel_id, and signed-in users join directly (open channels) or with a one-time ticket your server issues (ticket channels). Channels don't create IM groups, call invitations or call records.
Is knowing the channel ID enough to join?
No. Open channels require the user to be signed in to this app and pass admission checks; ticket channels also require a valid ticket your server issued to that user. Knowing only the channel ID or the media room name doesn't get past these checks.
Can a user be in a call and a channel at once?
No. A user can be in only one call or channel at a time, shared across one-to-one calls, group calls and channels. Right after leaving, media resources may still be cleaning up, and joining meanwhile says busy; wait a moment and retry with the same client_session_id rather than a new one each time.
Do mini programs and UniApp support channel audio/video?
UniApp does: H5 has a dedicated entry, which you can try with the H5 Demo; the app (Android / iOS) supports it through a UTS native bridge, tried on a real device with the App Demo. WeChat mini programs can currently only query channels, not join audio/video, and channels.supported is false. For every platform, see Standalone RTC channel support.
Does joining turn on the microphone, the system call screen or a background service automatically?
No. After joining, the microphone and camera are off by default and only turn on when the user acts; channels don't show CallKit or other system call screens either. Continuous capture in the background on Android and Flutter is something you need to implement yourself.
App balances and languages
I submitted a top-up. Why can't I make calls yet?
Creating a top-up order doesn't add to the balance; only the arrived payment does. WeChat Pay arrives automatically once the payment result is verified; bank transfers arrive once finance matches the bank record and confirms it. Check the order's status under "Top-up orders" in "Audio/video billing", and make sure it's this app's audio/video balance you topped up.
Once the balance is positive, the app's audio/video policy, channel switches, concurrency allowance and media service must also allow it before calls work; topping up doesn't turn those on. See Top-ups and Insufficient balance and failing to join.
Why do call stats minutes differ from charged minutes?
They're calculated differently: minutes in call stats are rounded per person per call, and channel reports are totaled per app per day; charges first convert to standard duration by the resolution actually received, then total per app per month and round once. So the two can't be added together, and you can't multiply stats minutes by the price to work out charges. See Comparing old and new data.
Does the English interface change the currency, time zone or user messages?
No. Language only changes what the interface shows; the currency (CNY), the billing time zone, error codes and user content stay the same. Email and SMS notifications need templates in that language, and English SMS also needs the provider's approval before it can be sent; see Language and localization.