Messaging Channels and Plugins¶
Use the messaging channel and plugin connection subcommands under moi-cli agent to create inbound messaging connections for agents or teams, manage external channel instances and callback rules, and authorize or disconnect external plugin OAuth accounts. Complete Configuration and Authentication before running commands.
Connect inbound messaging channels¶
See Two-way messaging for platform-side app creation and permission requirements. Before creating an inbound connection from the CLI, inspect supported (provider, channel_type, receive_mode) combinations in your deployment and check existing connections on the target agent:
moi-cli -auth pat -o agent list-ingress-capabilities --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o agent list-ingress-connections \
--workspace-id "$WORKSPACE_ID" \
--target-kind agent \
--target-workspace-id "$AGENT_WORKSPACE_ID" \
--target-id "$AGENT_ID"
When slack, slack_app, and managed_stream are listed in the deployment capabilities and no suitable connection exists yet, write the target agent, model, and Slack credentials to a restricted local file ingress.json (inspect field definitions via moi-cli schema agent create-ingress-connection):
{
"target": {
"kind": "agent",
"workspace_id": "<agent-workspace-id>",
"id": "<agent-id>"
},
"provider": "slack",
"channel_type": "slack_app",
"receive_mode": "managed_stream",
"agent_model": "<available-model>",
"managed_stream": {
"app_id": "<slack-app-id>",
"app_token": "<slack-app-token>",
"bot_token": "<slack-bot-token>"
}
}
Create the connection and inspect its runtime state:
INGRESS_JSON="$(moi-cli -auth pat -o agent create-ingress-connection \
--workspace-id "$WORKSPACE_ID" \
--json-file ingress.json)"
export CONNECTION_ID="$(printf '%s' "$INGRESS_JSON" | jq -r '.id')"
moi-cli -auth pat -o agent get-ingress-connection \
--workspace-id "$WORKSPACE_ID" \
--connection-id "$CONNECTION_ID"
Creating a Slack managed stream connection starts receiver provisioning automatically. Re-run get-ingress-connection and check desired_state, observed_state, and last_error_code:
Continue bounded observation while the connection is
startingorreconnecting.Fix external app credentials or scopes first if
auth_failedorconfig_invalidis reported.Once healthy, send a test message in Slack and verify the target agent’s task history and reply in the conversation.
Maintenance scenario |
Command and behavior |
|---|---|
Verify callback-mode ingress |
|
Callback or mail-polling modes |
Callback and mail-polling ingress connections reference an existing |
Disable or delete an ingress connection |
Submit |
Manage channel instances and callback rules¶
Use the subcommands below to maintain tool channel instances and external callback routing rules (inspect JSON schemas via moi-cli schema agent <subcommand>, and store credentials in restricted --json-file inputs):
Scenario |
Subcommands |
Description |
|---|---|---|
Browse catalog and maintain channel instances |
|
Run |
Test channel configurations and instances |
|
Sends live network requests to the external platform to validate credentials and connectivity. |
Manage callback rules |
|
Create, inspect, update, or remove routing rules for inbound external callbacks. |
Connect plugin accounts and complete OAuth¶
See Connect plugin accounts and recover authorization for console authorization workflows. From the CLI, list available plugin releases and existing workspace connections, then inspect connections on the selected release:
moi-cli -auth pat -o agent list-plugin-releases --workspace-id "$WORKSPACE_ID" --namespace system
moi-cli -auth pat -o agent list-plugin-connections --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o agent get-plugin-release \
--workspace-id "$WORKSPACE_ID" \
--release-id "$RELEASE_ID" \
--namespace "$RELEASE_NAMESPACE"
If a matching connection already exists in the workspace, check its authorization status directly. Otherwise, select an entry with the oauth driver from connections in the get-plugin-release output, record its requirement and profile, and prepare connection.json (external account passwords are never placed in this payload):
{
"release_namespace": "system",
"release_id": "<plugin-release-id>",
"requirement": "<connection-requirement-key>",
"profile": "<oauth-profile-key>",
"name": "My Plugin Account"
}
Create the plugin connection and save its returned id and version:
CONN_JSON="$(moi-cli -auth pat -o agent create-plugin-connection \
--workspace-id "$WORKSPACE_ID" \
--json-file connection.json)"
export CONNECTION_ID="$(printf '%s' "$CONN_JSON" | jq -r '.id')"
export CONNECTION_VERSION="$(printf '%s' "$CONN_JSON" | jq -r '.version')"
Disconnect a plugin account¶
Read generation from the latest get-plugin-authorization output, confirm impact on active agents, and disconnect:
moi-cli -auth pat -o agent disconnect-plugin-connection \
--workspace-id "$WORKSPACE_ID" \
--id "$CONNECTION_ID" \
--expected-generation "$GENERATION"
moi-cli -auth pat -o agent get-plugin-authorization --workspace-id "$WORKSPACE_ID" --id "$CONNECTION_ID"
Once disconnected, plugin tool calls that rely on this external account require re-authorization before running again.
Limitations and notes¶
Restrict local file permissions (for example
chmod 600) oningress.jsonand any files containing external App Tokens or Bot Tokens, and never commit live tokens, authorization URLs, OAuth callback parameters, or secrets to version control or shared logs.Inbound receiver health, plugin account authorization, and plugin installation bindings are tracked separately; inspect
get-ingress-connection,get-plugin-authorization, andget-plugin-installationindependently when troubleshooting.