Set Up an App
Connect an external platform to your organization by setting up an App. Apps manage bidirectional communication — receiving messages from external platforms and sending responses back through adapter containers.
This page shows how to do it manually. The faster, more common way is to tell the Integration Builder what capability you need — it researches the platform, writes and verifies any code, wires up the credentials and webhooks, and bundles everything into an installable integration, then you fine-tune by hand using the steps below.
For supported platforms, see the dedicated integration pages:
| Platform | Guide |
|---|---|
| Slack | Slack |
| Telegram | Telegram |
| Google Drive | Google Drive |
| Gmail | Gmail |
| Google Calendar | Google Calendar |
| Webhook | Webhook |
This guide covers general App setup for custom integrations.
Prerequisites
- Access to the Settings area of your organization
- The external platform's API credentials (bot token, API key, etc.)
- For adapter-based apps: the adapter container must be running and accessible
Install from the App Catalog
The fastest way to set up a supported platform:
- Navigate to Settings → Integrations.
- Browse the app catalog for pre-configured platform apps.
- Click Install on the app you want.
After installation, the app card shows a credentials checklist with status indicators:
| Status | Meaning |
|---|---|
| Configured | Credential is assigned and has a value |
| Not configured | Credential is assigned but empty |
| Missing | Required credential not yet assigned |
The credential dropdown is filtered to show only credentials relevant to the app's platform, making it easy to assign the right ones.
Connect Multiple Accounts of the Same Service
Some services — Gmail, Google Drive, Google Calendar, and GitHub — can be installed more than once, so a single organization can connect several accounts of the same service and use them side by side. For example, you might connect two Gmail mailboxes, a few Google Drives, or multiple GitHub accounts.
To add a second (or third) account:
- Open the service in the catalog (Settings → Integrations → Catalog) and click Install again.
- Give the new install a distinct name so you can tell the accounts apart — for example, "Gmail – Personal" or "Sales Inbox". The name field appears automatically for services that support multiple installs, and is what distinguishes one account from another.
- Each install gets its own credential. For OAuth services, click Connect with OAuth on that install and authorize the specific account you want — every install is authorized independently, so connecting a second mailbox never touches the first.
In a workflow, different agents can use different accounts. Each install's tools are kept separate automatically, so an agent assigned the "Sales Inbox" tools acts on that mailbox only.
Name the install when you create it. The name is what tells the accounts apart — both in the installed list and when assigning tools to agents.
Manual Setup
For custom integrations that aren't in the catalog:
1. Navigate to Apps
Open the sidebar and click Settings, then Apps. You see a grid of app cards showing any apps already configured.
2. Create a New App
Click New App. The app creation form opens with the following fields:
- Name — A unique name for this app (e.g., "Custom Webhook", "Internal API")
- Description — What this app connects to and its purpose
- Icon — Select a Heroicon to represent the app in the UI
- Category — Organize apps by type:
communication,integration, or custom
3. Configure Capabilities
Select what this app can do:
| Capability | Meaning |
|---|---|
| Send | The app can deliver outbound messages to the external platform |
| Receive | The app can accept inbound messages from the external platform |
Most apps have both capabilities.
4. Set the Adapter URL
Enter the URL of the adapter container that handles protocol translation for this platform. The adapter converts between the platform's native format and ORQO's internal message format.
http://adapters:8080/slack
http://adapters:8080/whatsapp
http://adapters:8080/telegram
If no adapter URL is provided, ORQO uses a built-in DirectAdapter for simple integrations that do not need protocol translation.
5. Configure OAuth (If Applicable)
For platforms that use OAuth (like Slack), fill in the OAuth configuration:
- Authorize URL — The platform's OAuth authorization endpoint
- Token URL — The platform's token exchange endpoint
- Scopes — Required OAuth scopes (comma-separated)
After saving, use the OAuth flow to authorize ORQO with the external platform.
6. Assign Credentials
Assign the credentials this app needs (bot tokens, API keys, signing secrets) using the credential selector. These credentials are passed to the adapter during message delivery and webhook verification.
7. Save and Verify
Click Create App. ORQO saves the configuration and attempts to verify the connection by reaching the adapter URL. The app status updates to:
| Status | Meaning |
|---|---|
| Pending | Created but not yet verified |
| Configured | Settings saved, awaiting verification |
| Verified | Connection tested successfully |
| Error | Verification failed (check adapter URL and credentials) |
After verification, ORQO automatically creates an MCP server for the adapter's tools and discovers them. The app's tools become available for agent assignment via skills.
8. Add Contacts
Add Contacts in Settings > Contacts for each person or service that should communicate through this app. Create a Contact Channel linking them to the app with their platform-specific address.
Only registered Contacts can send messages to ORQO. Unknown senders are rejected before any AI processing occurs.
What's Next
- Configure Webhooks to handle inbound events from the app
- Add a Credential if you need to store platform secrets
- Create a Skill to bundle the app's tools for agents