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 starting or reconnecting.

  • Fix external app credentials or scopes first if auth_failed or config_invalid is 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

agent verify-ingress-connection applies to callback receive modes only and is not used for Slack managed_stream connections.

Callback or mail-polling modes

Callback and mail-polling ingress connections reference an existing channel_instance_id rather than inline managed_stream tokens.

Disable or delete an ingress connection

Submit enabled: false with the two latest version fields via agent update-ingress-connection and read back status, or remove the connection with agent delete-ingress-connection.

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

list-connector-catalog, create-channel-instance, list-channel-instances, get-channel-instance, update-channel-instance, disable-channel-instance, bind-channel

Run get-channel-instance to inspect existing settings and bindings before updating or disabling an instance.

Test channel configurations and instances

test-channel-configuration, test-channel-instance

Sends live network requests to the external platform to validate credentials and connectivity.

Manage callback rules

create-callback-rule, list-callback-rules, get-callback-rule, update-callback-rule, delete-callback-rule

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')"

Start and poll OAuth authorization

Inspect current authorization state and start the OAuth flow with --expected-version:

moi-cli -auth pat -o agent get-plugin-authorization --workspace-id "$WORKSPACE_ID" --id "$CONNECTION_ID"

moi-cli -auth pat -o agent begin-plugin-oauth \
  --workspace-id "$WORKSPACE_ID" \
  --id "$CONNECTION_ID" \
  --expected-version "$CONNECTION_VERSION"

Complete authorization according to the returned grant type:

  • browser_handoff: Open authorization_url in a browser to complete sign-in on the external platform, then re-run get-plugin-authorization to verify state (this grant type does not issue a CLI-pollable attempt_id).

  • Grants returning a non-empty attempt_id (such as device authorization, where you also enter user_code as prompted): Save ATTEMPT_ID and poll poll-plugin-oauth at the poll_after interval with a bounded overall timeout:

moi-cli -auth pat -o agent poll-plugin-oauth \
  --workspace-id "$WORKSPACE_ID" \
  --id "$CONNECTION_ID" \
  --attempt-id "$ATTEMPT_ID" \
  --expected-version "$CONNECTION_VERSION"

moi-cli -auth pat -o agent get-plugin-authorization --workspace-id "$WORKSPACE_ID" --id "$CONNECTION_ID"

Warning

Each poll-plugin-oauth invocation performs one status check—pace retries using status, reason, next_action, and poll_after:

  • get-plugin-authorization can omit attempt_id even while an attempt remains active; keep using your saved ATTEMPT_ID when resuming.

  • If the connection version changes, stop polling the old attempt and re-inspect the connection and authorization state rather than pairing the new version number with the old ATTEMPT_ID.

After authorization succeeds, bind CONNECTION_ID and the selected profile to the plugin’s connection requirement via install-plugin, update-plugin-installation, and get-plugin-installation.

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) on ingress.json and 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, and get-plugin-installation independently when troubleshooting.

Last updated on