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.
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 > Apps.
- 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.
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