Messaging Integration API

Feishu and WeChat iLink expose two layers of HTTP contracts: administration configures the shared app, capability switches, directory/knowledge sync, and notification tests; personal endpoints act only on the caller's own connections, purposes, and Agent preferences. Both use JWT sessions; an API key cannot substitute.

Endpoint overview

Feishu (administration)

Feishu (personal) and callback

WeChat iLink (personal)

Feishu administration

App credentials

GET  /api/v1/admin/integrations/feishu/config
PUT  /api/v1/admin/integrations/feishu/config

PUT body:

Response fields: app_id, app_secret_configured, is_enabled, department_ids. The App Secret is never returned in plaintext.

POST /connection-check obtains a tenant token with the app credentials and returns {"status": "ok"}; failures map to the Feishu error and never echo the app secret in logs or responses.

Directory sync

• GET /departments returns the department tree visible to the app, including children.
• PUT /department-scope takes {"department_ids": ["0", "od-xxx"]} — 1–500 entries that must belong to the visible tree; the root department ID is 0.
• POST /sync syncs members for the saved scope and returns created/updated/skipped account counts plus created team counts. Without a saved scope it returns a validation error.

Notification tests

• GET /test-recipients?search= requires the notification capability. It returns up to 20 {id, username, email} entries where id is the user ID.
• POST /test-message takes {"user_id": "...", "title": "...", "content": "..."} with a 1–200 title and 1–2000 body. The recipient must be Feishu-bound and active; otherwise it returns feishu_test_recipient_unavailable.

Agent chat receive mode

GET  /api/v1/admin/integrations/feishu/agent-chat/config
PUT  /api/v1/admin/integrations/feishu/agent-chat/config

PUT body (all fields optional; omission keeps the current value):

Non-empty secrets need at least 8 characters. Response fields: connection_mode, event_verification_token_configured, event_encrypt_key_configured, is_enabled, capability_enabled, receiver_status.

receiver_status.state values:

managed reports whether the platform hosts the connection. With long connection selected, a worker consuming the agent queue maintains a singleton receiver; no extra service is required. Disabling the capability or switching back to callback stops reception.

Callback endpoint

POST /api/v1/integrations/feishu/callback

A public endpoint protected by Feishu signatures; it does not accept API keys or JWTs. It requires X-Lark-Request-Timestamp, X-Lark-Request-Nonce, and X-Lark-Signature; timestamps more than 300 seconds from server time are rejected, and bodies are capped at 64 KiB. The endpoint is inactive while connection_mode is long_connection. A URL verification challenge is answered with a signature only when the Verification Token matches.

Feishu knowledge sync

All endpoints are superuser-only and use app credentials rather than a signed-in user's token.

Create body:

Source output includes status, last_synced_at, last_error, last_result, created_at, and updated_at. When a sync is already running, update/sync/delete returns 409 (feishu_knowledge_source_busy); an unavailable space returns feishu_knowledge_space_unavailable.

curl -X POST "https://your-domain.com/api/v1/admin/integrations/feishu/knowledge/sources" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id":"KB_UUID","space_id":"SPACE_ID","name":"Product docs","interval_minutes":60}'

Feishu personal preferences

GET  /api/v1/feishu-agent/config
GET  /api/v1/feishu-agent/agents
PUT  /api/v1/feishu-agent/config

GET /config returns {enabled, is_enabled, linked, agent_id, agent_name, agent_available}: enabled is channel availability, is_enabled is the user's own switch, and linked reports whether a Feishu identity is bound. Unavailable Agent names are not disclosed.

GET /agents returns {id, name, description, team_name} for published Agents the user can access in teams they belong to; it returns an empty array when the channel is unavailable or the identity is unlinked.

PUT /config fields are all optional:

Turning off or clearing the selection is allowed while the channel is paused. Changes affect only later messages, not accepted receipts, running tasks, or their conversations.

WeChat iLink personal endpoints

Every endpoint requires the current user's JWT and offers no administrator impersonation. When the platform capability is off, the endpoint returns 403 (integration_feature_disabled).

Capabilities and connections

GET /api/v1/wechat-knowledge/features
GET /api/v1/wechat-knowledge/bindings

features returns {"agent_chat": boolean, "knowledge_collection": boolean}. bindings returns every connection for the caller, each with id, bot_id, purpose (none / knowledge_collection / agent), agent_config, collection, status, last_error, last_received_at, and created_at.

QR authorization

POST /api/v1/wechat-knowledge/logins
POST /api/v1/wechat-knowledge/logins/{identifier}/poll

logins returns {id, status, qrcode_content, expires_at}; a user may have at most 3 unfinished authorizations at once, beyond which it returns 429 (wechat_login_limit). poll takes {"verify_code": "123456"} (optional, digits only, ≤32). A confirmed authorization returns the connection summary; an identity already bound to another account returns 409 (wechat_identity_in_use).

Purpose switching

PUT /api/v1/wechat-knowledge/bindings/{identifier}/purpose

Body:

Purposes are mutually exclusive: sending agent with knowledge-base fields, or knowledge_collection with Agent fields, fails validation. Omitted optional fields keep their saved values. The target knowledge base needs write access; unavailable or read-only targets return 400. Switching is rejected while accepted work is unfinished.

DELETE /bindings/{identifier} disconnects the connection, writes an audit record, and returns {"id": "..."}. Collected documents remain.

Collection and Agent receipts

• GET /receipts?binding_id= returns the latest 50 collection receipts: id, binding_id, knowledge_base_id, status, results[] (per-attachment outcomes with localized errors), last_error, reply_status, created_at.
• GET /agent-receipts?binding_id= returns the latest 50 Agent receipts: id, binding_id, status, agent_name, agent_id, conversation_id, run_id, run_status, error, delivery_status[], created_at.
• Passing binding_id first checks ownership; a connection owned by someone else returns 404 (wechat_binding_not_found).

GET /items/{identifier}/original downloads a collected original as a file stream (application/octet-stream) rather than the unified envelope. The caller still needs access to the original target knowledge base; a missing record, unexpected original path, or absent file returns 404 (file_not_found).

Collection targets and models

GET /api/v1/wechat-knowledge/targets
GET /api/v1/wechat-knowledge/models?knowledge_base_id=UUID
GET /api/v1/wechat-knowledge/agents
GET /api/v1/wechat-knowledge/agent-models?agent_id=UUID

targets returns only active knowledge bases the caller can write to, as {id, name, team_name}; models returns that base's available vision and speech recognition models. agents returns {id, name, team_name, variables, enable_attachments, attachment_config}; agent-models returns {"stt": [...]}.

Permissions and errors

Delivery query endpoints are documented in Admin API; configuration and usage steps are in Messaging Integrations.