OpenMax
Free Trial

Apps API · Agent Channels

Agent Channels: 17 endpoints

← All groups

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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