WeChat Voice Notes | Svara Docs

Overview

Svara sends native voice messages on WeChat through the WeChat Official Account API. Voice messages appear as playable audio in the recipient's WeChat conversation, identical to recording a voice message directly in the app.

Your WeChat Official Account acts as the sender. The recipient must be a follower of your Official Account, and messages can only be sent within a 48-hour customer service window after the user's last interaction with your account.

Important: WeChat Official Accounts require a verified Chinese business entity. International businesses can apply through a WeChat-authorized third-party agency.

Required session data

| Field | Type | Description | |---|---|---| | access_token | string | A valid WeChat API access token obtained from the token endpoint |

How to get credentials

1. Register a WeChat Official Account

Go to mp.weixin.qq.com and register for an Official Account.
Choose Service Account (required for messaging APIs) or Subscription Account.
Complete the verification process with your Chinese business license.

2. Get your AppID and AppSecret

In the WeChat Official Account admin panel, go to Development > Basic Configuration.
Note your AppID and AppSecret.
Add your server's IP to the IP Whitelist.

3. Obtain an access token

WeChat access tokens expire every 2 hours. Request a new one from the token endpoint:

curl "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=YOUR_APP_ID&secret=YOUR_APP_SECRET"

Response:

{
  "access_token": "76_abc123def456...",
  "expires_in": 7200
}

export WECHAT_ACCESS_TOKEN="76_abc123def456..."

Important: Cache the access token and refresh it before it expires. WeChat rate-limits token requests to 2,000 per day.

4. Get the recipient's OpenID

The recipient is identified by their OpenID — a unique identifier for each user relative to your Official Account. You receive OpenIDs through:

The OAuth 2.0 authorization flow when users log in via your app.
Webhook events when users follow your account or send messages.
The user list API (/cgi-bin/user/get).

The 48-hour customer service window

WeChat enforces a 48-hour messaging window:

You can send customer service messages within 48 hours of the user's last interaction (message, menu click, scan, etc.).
After 48 hours, you cannot send messages until the user interacts with your account again.
Template messages have separate rules and are not subject to this window.

Audio format

WeChat voice messages use AMR format. Svara handles conversion automatically:

| Input format | Behavior | |---|---| | AMR | Sent directly, no conversion needed | | MP3 | Auto-converted to AMR | | M4A / AAC | Auto-converted to AMR | | OGG / OPUS | Auto-converted to AMR | | WAV | Auto-converted to AMR | | WebM | Auto-converted to AMR |

Audio files must be under 2 MB. Voice messages are limited to 60 seconds on WeChat.

Example request

curl -X POST https://api.svarapi.io/v1/send \
  -H "Authorization: Bearer $SVARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "wechat",
    "recipient": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
    "audio_url": "https://cdn.example.com/notes/update.m4a",
    "session": {
      "access_token": "76_abc123def456..."
    }
  }'

const response = await fetch("https://api.svarapi.io/v1/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SVARA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: "wechat",
    recipient: "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
    audio_url: "https://cdn.example.com/notes/update.m4a",
    session: {
      access_token: process.env.WECHAT_ACCESS_TOKEN,
    },
  }),
});

const result = await response.json();
console.log(`Voice note queued: ${result.id}`);

import requests

response = requests.post(
    "https://api.svarapi.io/v1/send",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "platform": "wechat",
        "recipient": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
        "audio_url": "https://cdn.example.com/notes/update.m4a",
        "session": {
            "access_token": access_token,
        },
    },
)

result = response.json()
print(f"Voice note queued: {result['id']}")

Common errors

| Error | Cause | Solution | |---|---|---| | invalid_token | The access token is expired or invalid | Request a new access token from the token endpoint | | recipient_not_found | The OpenID is invalid or the user does not follow your account | Verify the OpenID and ensure the user follows your Official Account | | messaging_window_closed | More than 48 hours since the user's last interaction | Wait for the user to interact with your account again | | audio_too_large | The audio file exceeds 2 MB | Compress or shorten your audio (max 60 seconds) | | audio_too_long | The audio exceeds 60 seconds | Trim your audio to under 60 seconds | | audio_fetch_failed | Could not download the audio from the URL | Ensure the URL is publicly accessible | | account_not_verified | Your Official Account has not completed verification | Complete the business verification process in the admin panel |