Set Up an App
Connect an external platform (Slack, email, or a custom service) to your organization by setting up an App. Apps manage bidirectional communication -- receiving messages from external platforms and sending responses back through adapter containers.
Prerequisites
- Access to the Settings area of your organization
- The external platform's API credentials (bot token, OAuth credentials, or SMTP config)
- For adapter-based apps: the adapter container must be running and accessible
Steps
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., "Slack - Production", "Support Email")
- 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. An outbound-only email app might only have "Send".
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://adapter-slack:8000
http://adapter-email:8000
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. Add platform-specific settings
The App Config section accepts JSON for platform-specific settings. Each adapter defines what configuration it needs. For example, a Slack adapter might need:
{
"signing_secret": "your-slack-signing-secret",
"default_channel": "#general"
}
7. Configure inbound events
If the app has the "Receive" capability, configure how inbound events are handled in the Receive Config section. This tells ORQO how to parse and route incoming webhooks from the external platform.
8. Assign credentials
Assign the credentials this app needs (bot tokens, API keys, SMTP passwords) using the credential selector. These credentials are passed to the adapter during message delivery.
9. 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.
10. Set up channels
Once the app is verified, you can create contact channels that link contacts (users, groups) to this app. Channels enable targeted message delivery -- sending a response to a specific Slack channel or email address.
11. Follow setup instructions
Some apps include step-by-step setup instructions (displayed on the app card). These guide you through platform-specific configuration like creating a Slack bot, setting webhook URLs, or configuring email forwarding.
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