Skip to main content

Apps & Channels

Apps are bidirectional connections to external platforms. They handle both receiving messages from a platform and delivering agent output back to it.

How Apps Work​

An App represents a connection to a specific platform (Slack, email, a custom service). Each App has:

  • Adapter — the protocol-specific logic for communicating with the platform (HTTP requests, email delivery, etc.).
  • Credentials — authentication for the platform's API.
  • MCP Tools — optional tools the App exposes (e.g., send_slack_message), discovered automatically.

Inbound Flow​

When an external platform sends a message to ORQO:

  1. The platform POSTs to the App's webhook endpoint (/api/v1/webhooks/:app_id).
  2. ORQO verifies the request signature.
  3. The message is parsed and routed — either to an agent waiting for a reply, or to Doorkeeper (the AI inbox) for a new conversation.

Outbound Flow​

When an agent needs to send a message to an external platform:

  1. The agent calls the user_message tool with the message content.
  2. The engine sends a delivery request to ORQO.
  3. ORQO identifies the correct App and dispatches the message via its adapter.
  4. The adapter delivers the message to the external platform.

Channels and Contacts​

Contacts are people or services ORQO communicates with. Each contact can have multiple Contact Channels — one per connected App. For example, a contact might have a Slack channel and an email channel.

Routing Rules determine which contact and channel receive messages based on the context of the conversation.

Registering an App​

Apps can be registered in two ways:

Manual Setup​

Go to Settings → Apps and create a new App. Configure the adapter type, credentials, and webhook settings.

Manifest URL​

Provide a manifest URL — ORQO fetches the App's configuration and creates the App, Skill, MCP Server, and credential stubs in a single transaction. This is the fastest way to register a well-configured integration.

OAuth Support​

Apps that require OAuth 2.0 handle the full flow:

  1. User initiates authorization from the App settings.
  2. ORQO redirects to the platform's OAuth consent screen.
  3. On callback, tokens are stored and linked to the App's credential.
  4. Tokens are refreshed automatically in the background.

App-Provided Tools​

Some Apps expose MCP tools via their adapter. For example, a Slack App might provide send_slack_message and list_slack_channels tools. These tools are discovered automatically when the App is verified, and can be assigned to agents via Skills.