WeChat Gateway API Docs

Simple interactive docs. Click each endpoint to view details and examples.

Use Authorization: Bearer <ADMIN_TOKEN> for all protected routes.

export BASE_URL="${YOUR_WORKER_BASE_URL}"
export ADMIN_TOKEN="${YOUR_ADMIN_TOKEN}";

Public

GET /health public

Health check

Example:

curl -X GET "$BASE_URL/health"

GET / auth

Example:

curl -X GET "$BASE_URL/" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

GET /admin-ui auth

Example:

curl -X GET "$BASE_URL/admin-ui" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

GET /docs public

This API docs page

Example:

curl -X GET "$BASE_URL/docs"

Admin Overview + Login

GET /admin/overview auth

Example:

curl -X GET "$BASE_URL/admin/overview" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

POST /admin/login/start auth

Body:

{ "baseUrl": "https://ilinkai.weixin.qq.com", "botType": "3", "accountIdHint": "acc-a" }

Example:

curl -X POST "$BASE_URL/admin/login/start" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://ilinkai.weixin.qq.com", "botType": "3", "accountIdHint": "acc-a" }'

GET /admin/login/status auth

Query: sessionId=<SESSION_ID>

Example:

curl -X GET "$BASE_URL/admin/login/status?sessionId=<SESSION_ID>" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

POST /admin/login/confirm auth

Body:

{ "sessionId": "<SESSION_ID>", "accountId": "acc-a", "space": "default" }

Example:

curl -X POST "$BASE_URL/admin/login/confirm" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "<SESSION_ID>", "accountId": "acc-a", "space": "default" }'

Admin Accounts

POST /admin/accounts/upsert auth

Body:

{ "accountId":"acc-a","botToken":"...","botId":"...@im.bot","baseUrl":"https://ilinkai.weixin.qq.com","space":"default","enabled":true }

Example:

curl -X POST "$BASE_URL/admin/accounts/upsert" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accountId":"acc-a","botToken":"...","botId":"...@im.bot","baseUrl":"https://ilinkai.weixin.qq.com","space":"default","enabled":true }'

GET /admin/accounts auth

Example:

curl -X GET "$BASE_URL/admin/accounts" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

GET /admin/accounts/{accountId} auth

Example:

curl -X GET "$BASE_URL/admin/accounts/{accountId}" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

DELETE /admin/accounts/{accountId} auth

Example:

curl -X DELETE "$BASE_URL/admin/accounts/{accountId}" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

POST /admin/accounts/set-enabled auth

Body:

{ "accountId":"acc-a","enabled":true }

Example:

curl -X POST "$BASE_URL/admin/accounts/set-enabled" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accountId":"acc-a","enabled":true }'

POST /admin/accounts/set-space auth

Body:

{ "accountId":"acc-a","space":"default" }

Example:

curl -X POST "$BASE_URL/admin/accounts/set-space" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accountId":"acc-a","space":"default" }'

POST /admin/accounts/reset-sync auth

Body:

{ "accountId":"acc-a" }

Example:

curl -X POST "$BASE_URL/admin/accounts/reset-sync" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accountId":"acc-a" }'

Admin Agents / Spaces / Bindings

POST /admin/agents/upsert auth

Body:

{ "id":"openai-main","endpoint":"https://api.openai.com/v1/chat/completions","model":"gpt-5","apiKey":"...","enabled":true,"weight":1 }

Example:

curl -X POST "$BASE_URL/admin/agents/upsert" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id":"openai-main","endpoint":"https://api.openai.com/v1/chat/completions","model":"gpt-5","apiKey":"...","enabled":true,"weight":1 }'

GET /admin/agents auth

Example:

curl -X GET "$BASE_URL/admin/agents" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

GET /admin/agents/{agentId} auth

Example:

curl -X GET "$BASE_URL/admin/agents/{agentId}" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

DELETE /admin/agents/{agentId} auth

Example:

curl -X DELETE "$BASE_URL/admin/agents/{agentId}" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

POST /admin/spaces/upsert auth

Body:

{ "name":"default","defaultAgentId":"openai-main","strategy":"sticky_weighted" }

Example:

curl -X POST "$BASE_URL/admin/spaces/upsert" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name":"default","defaultAgentId":"openai-main","strategy":"sticky_weighted" }'

GET /admin/spaces auth

Example:

curl -X GET "$BASE_URL/admin/spaces" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

GET /admin/spaces/{spaceName} auth

Example:

curl -X GET "$BASE_URL/admin/spaces/{spaceName}" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

DELETE /admin/spaces/{spaceName} auth

Example:

curl -X DELETE "$BASE_URL/admin/spaces/{spaceName}" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

POST /admin/bind/upsert auth

Body:

{ "space":"default","userId":"xxx@im.wechat","agentId":"openai-main" }

Example:

curl -X POST "$BASE_URL/admin/bind/upsert" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "space":"default","userId":"xxx@im.wechat","agentId":"openai-main" }'

GET /admin/bind/get auth

Query: space=default&userId=xxx@im.wechat

Example:

curl -X GET "$BASE_URL/admin/bind/get?space=default&userId=xxx@im.wechat" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

GET /admin/bind/list auth

Query: space=default

Example:

curl -X GET "$BASE_URL/admin/bind/list?space=default" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

DELETE /admin/bind/remove auth

Query: space=default&userId=xxx@im.wechat

Example:

curl -X DELETE "$BASE_URL/admin/bind/remove?space=default&userId=xxx@im.wechat" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Admin Runtime

GET /admin/conversations auth

Query: space=default

Example:

curl -X GET "$BASE_URL/admin/conversations?space=default" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

POST /admin/conversations/clear auth

Body:

{ "space":"default","userId":"xxx@im.wechat","agentId":"openai-main" }

Example:

curl -X POST "$BASE_URL/admin/conversations/clear" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "space":"default","userId":"xxx@im.wechat","agentId":"openai-main" }'

POST /admin/poll auth

Body:

{ "accountId":"acc-a" }

Example:

curl -X POST "$BASE_URL/admin/poll" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accountId":"acc-a" }'

POST /admin/send auth

Body:

{ "accountId":"acc-a","to":"xxx@im.wechat","text":"hello","contextToken":"" }

Example:

curl -X POST "$BASE_URL/admin/send" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accountId":"acc-a","to":"xxx@im.wechat","text":"hello","contextToken":"" }'

Gateway API (for your backend)

GET /api/accounts auth

Example:

curl -X GET "$BASE_URL/api/accounts" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

GET /api/contacts auth

Query: accountId=acc-a&limit=100

Example:

curl -X GET "$BASE_URL/api/contacts?accountId=acc-a&limit=100" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

GET /api/inbox auth

Query: accountId=acc-a&limit=100

Example:

curl -X GET "$BASE_URL/api/inbox?accountId=acc-a&limit=100" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

GET /api/inbox/media auth

Download archived media object from R2 (when archive enabled).

Query: accountId=acc-a&key=inbound/acc-a/xxx.jpg

Example:

curl -X GET "$BASE_URL/api/inbox/media?accountId=acc-a&key=inbound/acc-a/xxx.jpg" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

DELETE /api/inbox auth

Query: accountId=acc-a

Example:

curl -X DELETE "$BASE_URL/api/inbox?accountId=acc-a" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

DELETE /api/inbox/item auth

Delete one inbound message by id (and optional createdAt).

Query: accountId=acc-a&id=<MESSAGE_ID>&createdAt=<TIMESTAMP_MS>

Example:

curl -X DELETE "$BASE_URL/api/inbox/item?accountId=acc-a&id=<MESSAGE_ID>&createdAt=<TIMESTAMP_MS>" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

DELETE /api/accounts/{accountId} auth

Example:

curl -X DELETE "$BASE_URL/api/accounts/{accountId}" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

POST /api/send auth

Unified send API. Response includes upstream result.

Body:

{ "to":"xxx@im.wechat","text":"hello","accountId":"acc-a","contextToken":"" }

Example:

curl -X POST "$BASE_URL/api/send" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to":"xxx@im.wechat","text":"hello","accountId":"acc-a","contextToken":"" }'