Apps API · Agent Channels
Agent Channels: 17 个接口
GET /api/v1/agents/{agent_member_id}/channels
List agent conversation channels
权限(scope): agents:channel:read · 调用方式: appToken · operationId: list-agent-channels
Required app scope: agents:channel:read.
Returns the channel catalog (channel definitions and their form schemas) merged with the agent's per-channel binding status. Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
200OK —application/json·DataResponseListAgentChannelCatalogItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/dingtalk/scan
Start DingTalk QR-code connection (wizard step 1)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: start-agent-dingtalk-scan
Required app scope: agents:channel:write.
Starts a server-side DingTalk device-authorization scan session (the scan authorizes and yields the newly created robot's own credentials; no shared platform credential is used) and renders the authorization QR. Returns the session_handle (device code) to pass back to the poll step, plus the QR PNG, the authorization URL, the short user code fallback, and the session TTL. Start creates no binding and dispatches nothing to the runtime. Returns 412 when DingTalk is not configured on the server. Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
200OK —application/json·DataResponseStartAgentDingtalkScanDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/dingtalk/scan/poll
Poll a DingTalk QR-code connection (wizard step 2)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: poll-agent-dingtalk-scan
Required app scope: agents:channel:write.
Checks the scan session identified by session_handle (the device code). While the user has not finished scanning/authorizing the status is "pending" (keep polling). On success the status is "connected" and the binding is created (idempotent: repeated success polls return the same binding). A timed-out device code returns "expired"; an explicit user cancel/deny returns "cancelled"; a terminal DingTalk failure returns "error". Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · PollAgentDingtalkScanRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
session_handle |
string | 是 | The device code returned by the start-scan step |
回包
200OK —application/json·DataResponsePollAgentDingtalkScanDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/feishu/scan
Start Feishu QR-code connection (wizard step 1)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: start-agent-feishu-scan
Required app scope: agents:channel:write.
Starts a server-side Feishu (China) device-authorization scan session (the Feishu app registration endpoint is called server-side; the scan authorizes and yields the newly created app's own credentials; no shared platform credential is used) and renders the authorization QR. Returns the session_handle (device code) to pass back to the poll step, plus the QR PNG, the authorization URL, the short user code fallback, and the session TTL. Start creates no binding and dispatches nothing to the runtime. Returns 412 when Feishu is not configured on the server. Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
200OK —application/json·DataResponseStartAgentFeishuScanDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/feishu/scan/poll
Poll a Feishu QR-code connection (wizard step 2)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: poll-agent-feishu-scan
Required app scope: agents:channel:write.
Checks the scan session identified by session_handle (the device code). While the user has not finished scanning/authorizing the status is "pending" (keep polling). On success the status is "connected" and the binding is created (idempotent: repeated success polls return the same binding). A timed-out device code returns "expired"; an explicit user cancel/deny returns "cancelled"; a terminal Feishu failure returns "error". Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · PollAgentFeishuScanRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
session_handle |
string | 是 | The device code returned by the start-scan step |
回包
200OK —application/json·DataResponsePollAgentFeishuScanDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/lark/scan
Start Lark QR-code connection (wizard step 1)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: start-agent-lark-scan
Required app scope: agents:channel:write.
Starts a server-side Lark (international) device-authorization scan session (the Lark app registration endpoint is called server-side; the scan authorizes and yields the newly created app's own credentials; no shared platform credential is used) and renders the authorization QR. Returns the session_handle (device code) to pass back to the poll step, plus the QR PNG, the authorization URL, the short user code fallback, and the session TTL. Start creates no binding and dispatches nothing to the runtime. Returns 412 when Lark is not configured on the server. Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
200OK —application/json·DataResponseStartAgentLarkScanDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/lark/scan/poll
Poll a Lark QR-code connection (wizard step 2)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: poll-agent-lark-scan
Required app scope: agents:channel:write.
Checks the scan session identified by session_handle (the device code). While the user has not finished scanning/authorizing the status is "pending" (keep polling). On success the status is "connected" and the binding is created (idempotent: repeated success polls return the same binding). A timed-out device code returns "expired"; an explicit user cancel/deny returns "cancelled"; a terminal Lark failure returns "error". Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · PollAgentLarkScanRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
session_handle |
string | 是 | The device code returned by the start-scan step |
回包
200OK —application/json·DataResponsePollAgentLarkScanDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/wecom/scan
Start WeCom QR-code connection (wizard step 1)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: start-agent-wecom-scan
Required app scope: agents:channel:write.
Starts a server-side WeCom scan session with OpenMax's own WeCom app credentials and renders the authorization QR. Returns the session_handle (scode) to pass back to the poll step, plus the QR PNG, the authorization URL, and the session TTL. Start creates no binding and dispatches nothing to the runtime. Returns 412 when WeCom is not configured on the server. Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
回包
200OK —application/json·DataResponseStartAgentWecomScanDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/wecom/scan/poll
Poll a WeCom QR-code connection (wizard step 2)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: poll-agent-wecom-scan
Required app scope: agents:channel:write.
Checks the scan session identified by session_handle (the scode). While the user has not finished scanning/authorizing the status is "pending" (keep polling). On success the status is "connected" and the binding is created (idempotent: repeated success polls return the same binding). A timed-out scode returns "expired"; an explicit user cancel/deny returns "cancelled"; a terminal WeCom failure returns "error". Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · PollAgentWecomScanRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
session_handle |
string | 是 | The scan code (scode) returned by the start-scan step |
回包
200OK —application/json·DataResponsePollAgentWecomScanDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/whatsapp_business/registration
Start hosted WhatsApp Business registration (wizard step 1)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: start-agent-whatsapp-business-registration
Required app scope: agents:channel:write.
Adds the phone number to OpenMax's hosted WhatsApp Business account at Meta and requests a verification code. Returns the phone_number_id session handle for the submit-code step plus the pending binding. Retrying with the SAME number resends the code; a DIFFERENT number while one is in flight or connected returns 409 (disconnect first). Returns 412 when WhatsApp Business is not configured on the server. Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · StartAgentWhatsappBusinessRegistrationRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cc |
string | 是 | Country calling code (1-4 digits), e.g. "1" |
code_method |
string | OTP delivery method: sms | voice (case-insensitive; empty defaults to sms) | |
display_name |
string | Business display name shown on WhatsApp (Meta verified_name, 1-75 chars) | |
phone_number |
string | 是 | National number without the country code (4-15 digits) |
回包
200OK —application/json·DataResponseStartAgentWhatsappBusinessRegistrationDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/whatsapp_business/registration/code
Submit the WhatsApp Business verification code (wizard step 2)
权限(scope): agents:channel:write · 调用方式: appToken · operationId: submit-agent-whatsapp-business-code
Required app scope: agents:channel:write.
Verifies the code, registers the number and sets the per-number webhook override, completing the binding as connected. The webhook base URL is taken first from an explicit request override, then the agent's bound platform domain; when neither is present the number is connected with inbound disabled (non-blocking). A rejected code returns 400. Requires the caller to be the agent's owner or an org admin. The code is never persisted or logged.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
请求体
application/json · SubmitAgentWhatsappBusinessCodeRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
code |
string | 是 | Verification code the user received (4-8 digits). Never stored or logged. |
phone_number_id |
string | 是 | The stateless session handle returned by the start-registration step |
webhook_base_url |
string | Optional explicit webhook base URL override. When empty the platform resolves it from the agent's bound platform domain; when neither is present the number is connected with inbound disabled. |
回包
200OK —application/json·DataResponseSubmitAgentWhatsappBusinessCodeDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/{channel_type}/bind
Bind an agent conversation channel
权限(scope): agents:channel:write · 调用方式: appToken · operationId: bind-agent-channel
Required app scope: agents:channel:write.
Validates the channel bind request's form values (credentials included) and dispatches the install command to the agent runtime. Accepted asynchronously (202): the returned binding starts as pending; poll the status endpoint. Requires the caller to be the agent's owner or an org admin. Credential values are never persisted or logged.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
channel_type |
path | string | 是 | Channel type (e.g. telegram, slack, feishu) |
请求体
application/json · BindAgentChannelRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
config |
object | 是 | Channel form values keyed by field key. Sensitive values are forwarded to the agent runtime and are never persisted or logged by the platform. |
回包
202Accepted —application/json·DataResponseAgentChannelBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/{channel_type}/connect
Connect an agent conversation channel
权限(scope): agents:channel:write · 调用方式: appToken · operationId: connect-agent-channel
Required app scope: agents:channel:write.
Validates the channel connect request's form values (credentials included) and dispatches a single idempotent connect command through the agent's openmax runtime (the runtime decides install-vs-upgrade). Accepted asynchronously (202): the returned binding starts as pending; poll the status endpoint until connected/error. Supersedes bind + update-credentials (one action, no bind-vs-update decision). Requires the caller to be the agent's owner or an org admin. Credential values are never persisted or logged.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
channel_type |
path | string | 是 | Channel type (e.g. telegram, slack, feishu) |
请求体
application/json · ConnectAgentChannelRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
config |
object | 是 | Channel form values keyed by field key. Sensitive values are forwarded to the agent runtime and are never persisted or logged by the platform. |
回包
202Accepted —application/json·DataResponseAgentChannelBindingItemBodydefaultError —application/problem+json·D8Error
PATCH /api/v1/agents/{agent_member_id}/channels/{channel_type}/credentials
Update an agent channel's credentials
权限(scope): agents:channel:write · 调用方式: appToken · operationId: update-agent-channel-credentials
Required app scope: agents:channel:write.
Dispatches the update-credentials command with the updated channel credentials to the agent runtime. Accepted asynchronously (202); poll the status endpoint. Requires the caller to be the agent's owner or an org admin. Credential values are never persisted or logged.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
channel_type |
path | string | 是 | Channel type (e.g. telegram, slack, feishu) |
请求体
application/json · UpdateAgentChannelCredentialsRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
config |
object | 是 | Updated channel form values keyed by field key. Sensitive values are forwarded to the agent runtime and are never persisted or logged by the platform. |
回包
202Accepted —application/json·DataResponseAgentChannelBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/agents/{agent_member_id}/channels/{channel_type}/disconnect
Disconnect an agent conversation channel
权限(scope): agents:channel:write · 调用方式: appToken · operationId: disconnect-agent-channel
Required app scope: agents:channel:write.
Dispatches a disconnect command through the agent's openmax runtime; the binding is removed once the runtime confirms the disconnect. Accepted asynchronously (202); poll the status endpoint (the binding returns to not-connected). Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
channel_type |
path | string | 是 | Channel type (e.g. telegram, slack, feishu) |
回包
202Accepted —application/json·DataResponseDisconnectAgentChannelDataBodydefaultError —application/problem+json·D8Error
GET /api/v1/agents/{agent_member_id}/channels/{channel_type}/status
Get an agent channel's binding status
权限(scope): agents:channel:read · 调用方式: appToken · operationId: get-agent-channel-status
Required app scope: agents:channel:read.
Returns the current binding status for one channel; poll it after bind/credential updates. Requires the caller to be the agent's owner or an org admin.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
channel_type |
path | string | 是 | Channel type (e.g. telegram, slack, feishu) |
回包
200OK —application/json·DataResponseAgentChannelBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/channel-connection-confirmations/{confirmation_id}/confirm
Human owner/admin confirms the displayed Agent channel connection
权限(scope): agents:channel:write · 调用方式: appToken · operationId: confirm-chat-channel-connection
Required app scope: agents:channel:write.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
confirmation_id |
path | string (uuid) | 是 |
请求体
application/json · ConfirmChannelConnectionRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
agent_member_id |
string (uuid) | 是 | |
channel_type |
string: feishu, lark, dingtalk, wecom |
是 | |
conversation_id |
string (uuid) | 是 |
回包
200OK —application/json·DataResponseChannelConfirmationStatusBodydefaultError —application/problem+json·D8Error
