Create an incoming message connection

Create an incoming message connection.

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/ingress-connections

Before you call this API

Prepare a personal access token with access to the target Workspace and permission for the operation. The path Workspace must match X-Workspace-ID. Examples use jq. See Shared information for variables, objects, and states.

Request body

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/ingress-connections" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg AGENT_WORKSPACE_ID "$AGENT_WORKSPACE_ID" --arg AGENT_ID "$AGENT_ID" --arg AGENT_MODEL "$AGENT_MODEL" --slurpfile MANAGED_CREDENTIALS_FILE "$MANAGED_CREDENTIALS_FILE" '
{
  "target": {
    "kind": "agent",
    "workspace_id": $AGENT_WORKSPACE_ID,
    "id": $AGENT_ID
  },
  "provider": "slack",
  "channel_type": "slack_app",
  "receive_mode": "managed_stream",
  "agent_model": $AGENT_MODEL,
  "managed_stream": $MANAGED_CREDENTIALS_FILE[0]
}
')"

The example reads a local managed-credentials JSON object. Slack creation requires app_id/app_token/bot_token; Feishu requires app_id/app_secret; WeCom AI Bot requires bot_id/secret. A new managed connection enters starting. Callback connections start disabled and require separate validation; mail mode waits for its first input.

Field

Type

Required

Description

target

object

Yes

Agent or team receiving messages.

target.kind

string

Yes

agent or team.

target.workspace_id

string

Yes

Workspace owning the target. Teams belong to the current Workspace; agents may belong to the current or system Workspace.

target.id

string

Yes

Target ID returned by the directory.

provider

string

Yes

Choose a platform from the capabilities list.

channel_type

string

Yes

Channel type matching the platform and receive mode.

receive_mode

string

Yes

managed_stream, callback, or mail_polling.

agent_model

string

Conditionally required

An agent target requires an available model; team behavior depends on member configuration.

managed_stream

object

Conditionally required

Managed mode supplies credentials for the selected platform; objects for other modes cannot also be supplied.

callback.channel_instance_id

string

Conditionally required

Callback mode references an existing, enabled channel instance in the current Workspace that supports ingress.

mail_polling.channel_instance_id

string

Conditionally required

Mail polling references the corresponding channel instance; cannot be combined with callback or managed_stream.

Successful response

{
  "code": 0,
  "data": {
    "id": "ingress_example",
    "workspace_id": "workspace_example",
    "target": {
      "kind": "agent",
      "workspace_id": "workspace_example",
      "id": "agent_example"
    },
    "provider": "slack",
    "channel_type": "slack_app",
    "receive_mode": "managed_stream",
    "agent_model": "model_example",
    "association_version": 1,
    "connected_by_user_id": "user_example",
    "enabled": true,
    "account_identity": "slack:app:app_example",
    "config_version": 1,
    "desired_state": "enabled",
    "observed_state": "starting",
    "created_at": "2026-11-11T00:00:00Z",
    "updated_at": "2026-11-11T00:00:00Z"
  }
}

Field

Type

Description

code

integer

0 on success.

data

object

Result object; see the shared object descriptions for fields.

Error responses

Handle HTTP status, business results, and error fields separately. See Errors and environments. On source or version conflicts, read the current state; do not automatically retry with a different identity, resource, or request ID.

Last updated on