Connect a messaging channel

Associate an inbound connection with a selected agent or team. Discover advertised provider, channel type and receive mode before preparing credentials, creating the connection and reading its runtime state.

API operations

Paths are relative to the Product Endpoint. Use credentials from API call basics.

Method and path

Purpose

GET /workspaces/{workspace_id}/ingress-capabilities

Available provider, channel type and receive modes.

GET /workspaces/{workspace_id}/ingress-connections

Supply target_kind, target_workspace_id, and target_id together to query one target. The current list is not paginated.

POST /workspaces/{workspace_id}/ingress-connections

Create an inbound connection.

GET /workspaces/{workspace_id}/ingress-connections/{id}

Read versions and state.

PATCH /workspaces/{workspace_id}/ingress-connections/{id}

Update enabled state, model or credentials using both expected versions.

POST /workspaces/{workspace_id}/ingress-connections/{id}/test

Validates only callback connections. The JSON includes both current versions; Telegram also requires callback_url.

DELETE /workspaces/{workspace_id}/ingress-connections/{id}

Send both expected versions as query parameters to delete the association; body values are not used.

Requests and results

Creation includes target (kind, workspace_id, id), provider, channel_type, receive_mode and its matching configuration. managed_stream carries provider credentials; callback or mail_polling references an existing channel_instance_id. Select the configuration for that mode.

For the full Slack JSON and call sequence, see the CLI guide Messaging Channels and Plugins. For Go and Python examples, see the SDK guide Connect Messaging Channels.

Preserve id, association_version and config_version, using recently read versions for changes. Inspect desired_state, observed_state, last_receive_at, last_error_code and verify an actual external message and reply in the selected target.

The capability list describes supported combinations, not credential, network or receiver readiness. For managed_stream, let the receiver establish the connection and read its state. Do not call the callback-only /test operation. Callback verification checks channel configuration and enables the connection. The Telegram branch registers a Webhook with the provider: callback_url must use the deployment’s absolute HTTPS URL and match the detail’s callback_path. A rejected channel test may return HTTP 200 with ok:false; inspect that business result and read the connection again.

When updating managed_stream, submit only secret fields that the platform allows, without resubmitting account identity: app_token/bot_token for Slack, app_secret for Feishu, and secret for WeCom. Changing an App ID or Bot ID requires the account association flow. Read state again after disabling. An established connection does not prove that messages have been sent or received.

Last updated on