Apps API · Agent Channels
Agent Channels: 17 endpoints
GET /api/v1/agents/{agent_member_id}/channels
List agent conversation channels
Scope: agents:channel:read · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Request body
application/json · PollAgentDingtalkScanRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
session_handle |
string | yes | The device code returned by the start-scan step |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Request body
application/json · PollAgentFeishuScanRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
session_handle |
string | yes | The device code returned by the start-scan step |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Request body
application/json · PollAgentLarkScanRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
session_handle |
string | yes | The device code returned by the start-scan step |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Request body
application/json · PollAgentWecomScanRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
session_handle |
string | yes | The scan code (scode) returned by the start-scan step |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Request body
application/json · StartAgentWhatsappBusinessRegistrationRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
cc |
string | yes | 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 | yes | National number without the country code (4-15 digits) |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
Request body
application/json · SubmitAgentWhatsappBusinessCodeRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
code |
string | yes | Verification code the user received (4-8 digits). Never stored or logged. |
phone_number_id |
string | yes | 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. |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
channel_type |
path | string | yes | Channel type (e.g. telegram, slack, feishu) |
Request body
application/json · BindAgentChannelRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
config |
object | yes | Channel form values keyed by field key. Sensitive values are forwarded to the agent runtime and are never persisted or logged by the platform. |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
channel_type |
path | string | yes | Channel type (e.g. telegram, slack, feishu) |
Request body
application/json · ConnectAgentChannelRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
config |
object | yes | Channel form values keyed by field key. Sensitive values are forwarded to the agent runtime and are never persisted or logged by the platform. |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
channel_type |
path | string | yes | Channel type (e.g. telegram, slack, feishu) |
Request body
application/json · UpdateAgentChannelCredentialsRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
config |
object | yes | 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. |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
channel_type |
path | string | yes | Channel type (e.g. telegram, slack, feishu) |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | yes | Agent member UUID |
channel_type |
path | string | yes | Channel type (e.g. telegram, slack, feishu) |
Responses
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 · Called with: appToken · operationId: confirm-chat-channel-connection
Required app scope: agents:channel:write.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
confirmation_id |
path | string (uuid) | yes |
Request body
application/json · ConfirmChannelConnectionRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
agent_member_id |
string (uuid) | yes | |
channel_type |
string: feishu, lark, dingtalk, wecom |
yes | |
conversation_id |
string (uuid) | yes |
Responses
200OK —application/json·DataResponseChannelConfirmationStatusBodydefaultError —application/problem+json·D8Error
