OpenMax
免费试用

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

回包

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

回包

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

回包

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

回包

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

回包

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

回包

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

回包

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

回包

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

回包

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)

回包

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.

回包

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.

回包

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.

回包

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.

回包

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)

回包

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)

回包

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) 是

回包