Apps & Channels
Apps are connections to external platforms. They handle the world-facing concerns — receiving messages, delivering agent output, OAuth, webhook verification. Anything engine-facing — the tools agents call when interacting with the platform — lives in a separate primitive called a Skill. Most platform integrations pair an App with a Skill, but either side can stand alone (see Integration Hierarchy for the full picture).
Example integrations
ORQO ships with a growing catalog of ready-to-install Apps across categories like communication, storage, productivity, and development. A few representative examples:
- Slack — team chat with threads, channels, and DMs.
- Gmail — search, read, and send emails.
- Google Drive — list, search, and create files.
- Webhook — a generic HTTP integration for any external system.
This is not an exhaustive list — new integrations are added regularly. The live list of integrations available to your organization is in Settings → Integrations inside ORQO — that view is the source of truth for what you can install right now.
A public integrations catalog is planned for a future release. Until then, browse the catalog tab in Settings to see everything that is currently available.
All adapters run in a single consolidated container. Each adapter is mounted at its own path and handles protocol translation independently.
How Apps Work
An App represents a connection to a specific platform. The App itself owns two things:
- Adapter — the protocol-specific logic for communicating with the platform (HTTP requests, message formatting, webhook verification, OAuth flow if applicable).
- Credentials — authentication for the platform's API.
That's the App layer. Tools that agents can call when interacting with the platform are not part of the App — they live in a paired Skill. An App that bundles a Skill exposes platform-specific tools to agents (e.g., send_slack_message); an App with no Skill is pure message transport and is surfaced as a Channel (see below). A Skill itself can wrap an MCP server, bundle Python tools written by the Tool Builder, or expose Standard Library tools — those choices are independent of how the App handles auth and webhooks.
How they combine in practice:
| Shape | Example | App | Skill |
|---|---|---|---|
| OAuth platform with tools | Slack, Gmail, Google Drive | yes — adapter + OAuth | yes — exposes platform tools |
| Pure messaging (Channel) | Receive SendGrid Emails | yes — webhook in, SMTP out | none — agents don't call SendGrid tools |
| Static-API-key tools | Bannerbear | none needed | yes — credential is just an API key |
| Public MCP server | a community MCP | none needed | yes — wraps the MCP server |
Adapter HTTP Contract
Every adapter implements a standard set of HTTP endpoints. Credentials are passed per-request — adapters are stateless.
| Endpoint | Purpose |
|---|---|
GET /health | Health check |
POST /deliver | Send a message outbound to the platform |
POST /verify-webhook | Verify inbound webhook signature |
POST /parse-inbound | Normalize inbound webhook payload into ORQO's internal format |
POST /verify | Test connection with credentials |
POST /format | Format a message for the platform's display conventions |
POST /mcp | MCP JSON-RPC endpoint for tool discovery and execution (optional) |
This contract is the same for all adapters. ORQO never reads platform-specific fields from raw payloads — all routing decisions use the normalized output from /parse-inbound.
Inbound Flow
When an external platform sends a message to ORQO:
- The platform POSTs to the App's webhook endpoint (
/api/v1/webhooks/:app_id). - ORQO sends the raw payload to the adapter's
/verify-webhookendpoint for signature verification. - The adapter's
/parse-inboundnormalizes the payload into a standard format with routing flags (is_bot,is_dm,challenge_response,dedup_key). - ORQO checks whether the event is a reply to a question an agent is waiting on. If so, it is delivered to that agent.
- Otherwise, routing depends on the App's Route to Doorkeeper setting:
- On (default): the sender must be a registered Contact — unknown senders are ignored — and the message is handed to Doorkeeper for conversational handling.
- Off: the event is matched against app-event triggers on workflows in the organization. A matching trigger fires the workflow directly. No Contact is required.
See Inbound routing for the full picture, and toggle the setting on each App's drawer under Settings → Integrations.
Outbound Flow
When an agent needs to send a message to an external platform:
- The agent sends a message to the user.
- ORQO identifies the correct App and dispatches the message via its adapter.
- 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, a WhatsApp number, and a Telegram handle.
Only registered Contacts can interact with ORQO. Messages from unknown senders (those without a Contact record) are rejected before any AI processing occurs. Add contacts through Settings > Contacts to control who can communicate with your organization's AI.
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:
One-Click Install from Catalog
Navigate to Settings > Apps and browse the app catalog. Platform apps are available as pre-configured templates. Click Install to create the App with the correct adapter URL and capability settings.
After installation, you see a credentials checklist showing which credentials are required, which are configured, and which are still missing. The credential dropdown is filtered to show only credentials relevant to the app's platform.
Manual Setup
Go to Settings > Apps and create a new App. Configure the adapter type, credentials, and webhook settings manually. See Set Up an App for the full walkthrough.
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 custom integration.
OAuth Support
Apps that require OAuth 2.0 (like Slack, Reddit, Google Drive, Gmail, and Google Calendar) handle the full flow:
- User initiates authorization from the App settings.
- ORQO redirects to the platform's OAuth consent screen.
- On callback, tokens are stored and linked to the App's credential.
- Tokens are refreshed automatically in the background.
App-Provided Tools
Some Apps expose MCP tools via their adapter. For example, a Slack App provides 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.
Tool names are platform-prefixed to prevent collisions across the organization (e.g., send_slack_message not send_message).
App-Managed MCP Servers
When an App provides MCP tools, it creates a dedicated MCP Server to host them. These servers are:
- Owned by the App -- the card tile shows an "app: Name" badge identifying the parent App.
- Locked -- they cannot be edited or deleted by users. The App's sync process manages the server configuration automatically.
- Visible in Settings → MCP Servers -- they appear alongside your manually connected servers, but with a "Locked" badge.
To remove an app-managed MCP server, uninstall the parent App.
Channels
A Channel is a special type of App that handles message transport only — it receives inbound webhooks and delivers outbound replies, but does not expose any MCP tools for agents to call.
Channels appear alongside Apps in the catalog and in Settings > Apps. They are identified by a Channel badge instead of the usual App badge.
| App | Channel | |
|---|---|---|
| MCP tools | Yes — agents call tools like send_slack_message | None — pure message transport |
| Webhook handling | Yes | Yes |
| Message delivery | Yes | Yes |
| CI checks | Full pipeline including tool discovery | Health and manifest only (MCP checks skipped) |
Example: The Receive SendGrid Emails integration is a Channel. Inbound emails arrive via SendGrid webhooks, are routed to Doorkeeper for conversation, and replies go back through SMTP. Agents never call SendGrid tools directly.
For details on building a Channel, see the developer guide.
Badge Reference
Integration cards in Settings → Integrations carry small coloured badges that summarise the state and capabilities of each installation at a glance. The list below explains every badge you will see there.
Type badges
| Badge | Meaning |
|---|---|
| App | Adapter-based integration that can expose MCP tools, receive webhooks, or deliver messages to an external platform. |
| Skill | Engine-facing package that bundles tools, credentials, and knowledge for assignment to agents. A Skill has no adapter of its own. |
| Channel | A tool-less App — inbound/outbound message transport only (e.g. Receive SendGrid Emails). Appears in the Catalog tab when a listing declares send/receive capabilities. |
| Tools | A catalog listing that exposes one or more MCP tools. Appears in the Catalog tab next to the category. |
Ownership badges
| Badge | Meaning |
|---|---|
| Platform | A first-party ORQO integration — flagged by ORQO staff in the Developer Portal. Configuration is managed by ORQO; you cannot edit the adapter URL, manifest, or capabilities. You still provide your own credentials. |
| Community | A third-party integration published by an external developer. Community listings go through the public review lifecycle before becoming installable. All listings default to Community — the Platform flag is superadmin-only. |
| Locked | A Skill that has been hidden or locked by the platform or by an owning App. You cannot edit, remove, or reassign it directly. App-managed Skills become unlocked only when their parent App is uninstalled. |
Category badge
The category badge (titleised — e.g. Communication, Productivity, Storage, Development, Research, Social) comes from the integration's manifest. It is the same value used by the category filter pills at the top of the page.
Capability badges (Apps only)
An App shows one badge per declared capability:
| Badge | What the adapter can do |
|---|---|
| send | Delivers outbound messages from agents to the external platform. |
| receive | Accepts inbound webhooks from the external platform and routes them into ORQO. |
Apps that declare neither capability and expose no MCP tools are surfaced as plain informational listings — this is rare.
Status badges (Apps)
An App card reports the current health of the installation. The text and colour are derived from the adapter's most recent verification.
| Badge | When it appears | What it means |
|---|---|---|
| Connected (green) | status = verified | Credentials are present and the adapter responded successfully to the last /verify call. The App is ready to use. |
| Configured (blue) | status = configured | Credentials are saved but the adapter has not yet been verified in this state. Click Verify on the drawer to probe the connection. |
| Pending (yellow) | status = pending | The App has been created but credentials are missing or incomplete. |
| Error (red) | status = error | The last verification failed — inspect the App drawer for the error message. Common causes: invalid token, expired OAuth grant, unreachable adapter. |
Skill badges
A Skill card reports what the skill brings to an agent and whether its prerequisites are satisfied.
| Badge | Meaning |
|---|---|
| N tools | How many tools this Skill will hand to any agent it is assigned to. Includes the standard, ToolFactory, and MCP tools resolved by the manifest. |
CREDENTIAL_KEY (green) | The named credential exists in your organization and is wired to this skill. The skill is ready to run on this credential. |
CREDENTIAL_KEY (yellow) | The skill requires this credential but it has not been provided yet. Open the drawer and attach a credential before assigning the skill to an agent. |
| Runtime (green) | The skill needs a runtime (e.g. a local Python sandbox) and a valid runtime is connected. |
| Runtime (yellow) | The skill needs a runtime but none is currently satisfying the requirement. The skill will fail at execution until a runtime is connected. |
Badges you will only see in the Catalog tab
The Catalog tab lists integrations you have not yet installed. Cards there use a simplified badge set:
| Badge | Meaning |
|---|---|
| Channel | The listing declares send/receive capabilities. |
| Tools | The listing exposes at least one MCP tool. |
| Category | The listing's category (grey in the catalog, accent colour once installed). |
Installation-specific badges — Connected, credential-key badges, Runtime — only appear after you install the integration. Ownership badges (Platform / Community) appear on both catalog and installed cards.