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 |
|---|---|---|---|
|
object |
Yes |
Agent or team receiving messages. |
|
string |
Yes |
agent or team. |
|
string |
Yes |
Workspace owning the target. Teams belong to the current Workspace; agents may belong to the current or system Workspace. |
|
string |
Yes |
Target ID returned by the directory. |
|
string |
Yes |
Choose a platform from the capabilities list. |
|
string |
Yes |
Channel type matching the platform and receive mode. |
|
string |
Yes |
managed_stream, callback, or mail_polling. |
|
string |
Conditionally required |
An agent target requires an available model; team behavior depends on member configuration. |
|
object |
Conditionally required |
Managed mode supplies credentials for the selected platform; objects for other modes cannot also be supplied. |
|
string |
Conditionally required |
Callback mode references an existing, enabled channel instance in the current Workspace that supports ingress. |
|
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 |
|---|---|---|
|
integer |
0 on success. |
|
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.