Overview
This guide covers the generic third-party app foundation shared by all types of Third-Party Apps built on the CRM platform. It covers core concepts, app registration, OAuth installation, webhook security, and distribution.
If you are building a chat integration app for customers, read the foundation docs first, then continue with the Customer Chat Integration.
What Is a Third-Party App?
A Third-Party App is an external service that integrates with the CRM by using its OAuth 2.0 system and REST API. You build and host the third-party app yourself. The CRM provides the platform and the APIs.
Some example use cases:
- Slack Notification - listens to CRM webhook events and pushes ticket or conversation alerts to a Slack channel for human agents to see.
- Telegram integration (customer chat integration) - routes two-way conversations between the CRM and a customer's external messaging platform.
Key Entities
App
An App is the registration you create in the CRM Dashboard. It has:
- A globally unique Client ID and Client Secret (for OAuth).
- A Signing Secret (for verifying webhooks the CRM sends to you).
- Configured Redirect URLs (where the CRM sends the user after authorization).
- A set of Permission Scopes that the app can request.
- A set of Webhook Event Subscriptions and a Webhook Event URL that the CRM will POST to.
Like a standard OAuth application, one published App can be installed into any number of workspaces.
Agent
An Agent is a user inside a CRM workspace. Agents with admin permissions can install and configure third-party apps, this is the person who goes through the OAuth flow shown in this guide. Agents without admin permissions handle day-to-day customer conversations from the CRM Dashboard.
Workspace
A Workspace is an isolated environment in the CRM. Each workspace is independent - it has its own agents, contacts, channels, and conversations.
When a agent installs your app via the OAuth flow, the CRM issues an Access Token scoped to that workspace. The third party app server should store this token per workspace - never share tokens between workspaces.
Access Token
The per-workspace Access Token you receive after OAuth installation. Include it as Authorization: Bearer <token> on all CRM API requests on behalf of that workspace.
Important: Currently, there is no refresh token mechanism. The access token has an extended expiration period and does not expire in practice.
Webhook Event
A Webhook Event is a notification the CRM sends to your registered webhook URL when something happens. Webhook events are signed with HMAC-SHA256 using your app's Signing Secret and delivered as HTTP POST requests with a X-Data-Signature header.
See CRM Webhooks for how to receive and verify them.
Signing Secret
A secret string generated by the CRM Dashboard for your app. Use it to verify that incoming webhooks actually came from the CRM. It is not the same as client_secret - keep them separate.
Entity Relationships
One App can be installed into many workspaces. Each install (or reinstall) produces a new workspace-scoped Access Token; old tokens are not automatically revoked and remain valid until explicitly revoked or expired. The token is what your backend uses to call the CRM API on behalf of that workspace. Each workspace has one or more Channels (which might still be named as "Web Widget Channel" at the dashboard).
| Entity | What you store | Identified by |
|---|---|---|
| App | Registered once in the CRM Dashboard. client_id, client_secret, and signing_secret come from here. Store them in environment variables. | app_id, client_id (for OAuth) |
| Workspace | An isolated CRM environment with its own agents, contacts, channels, and conversations. You learn the workspace_id from the OAuth token exchange response. | workspace_id |
| Installation | One row per workspace that has installed your app, represents that agent's consent grant. Reinstalling the same workspace upserts this row rather than creating a new one. | workspace_id |
| Access Token | A new token is issued on every install or reinstall. Old tokens remain valid until explicitly revoked. Store only the latest token, but be aware multiple tokens may be active simultaneously after a reinstall. Passed as Authorization: Bearer <token> on every CRM API call for that workspace. | - |
| CRM Channel | A named inbox inside a workspace (e.g. "Telegram Support TH", "Telegram Sales"). Every conversation belongs to exactly one channel. Channels are created by the agent in the CRM dashboard. | channel_id |
If you are building a chat integration (e.g. Telegram), additional entities layer on top of this foundation, Platform Accounts (e.g. a Telegram bot) each linked to a CRM Channel, and Conversations that track which Platform Account they originated from. See Customer Chat Integration - Entity Relationships.
Best Practices
Before you start building, read the Best Practices guide. It covers how to handle non-breaking API changes and other integration guidelines that apply across all third-party app types.
The App Lifecycle
- Third-party App Developer creates App in the CRM Dashboard (see App Setup in the CRM Dashboard)
- Third-party App Developer configures scopes, redirect URLs, webhook event URL, signing secret (see App Setup in the CRM Dashboard)
- Agent clicks "Install" on developer's app page (see OAuth Flow)
- Agent is redirected to CRM OAuth consent screen (see OAuth Flow)
- Agent approves → CRM redirects to developer's callback URL with a code (see OAuth Flow)
- Developer's backend exchanges the code for an access_token (see OAuth Flow)
- Developer's backend stores access_token keyed by workspace_id (see OAuth Flow)
- Agent configures platform credentials in the developer's third-party app settings page (see Customer Chat Integration)
- The third party app is now ready to use
Notes: Currently, we do not have an app uninstallation flow, but we may introduce one in the future.
Documents in This Guide
| # | Document | What It Covers |
|---|---|---|
| 1 | App Setup in the CRM Dashboard | Step-by-step walkthrough of app setup in the CRM Dashboard: names, redirect URLs, scopes, webhook events, secrets |
| 2 | OAuth Flow | Building the Install button, state/CSRF, token exchange, storing tokens, session handling |
| 3 | API Requests | Authentication, request format, response structure, pagination, async operations, sending announcements as your app, and the OpenAPI reference |
| 4 | CRM Webhooks | Receiving CRM webhook events, signature verification, delivery retries, idempotency, and event routing |
| 5 | Customer Chat Integration | Chat integration guide for customers (e.g. Telegram) |
| 6 | Distribution | Private (workspace-only) vs public (marketplace), publishing prerequisites, scope changes after publishing, multi-tenant considerations |
| 7 | Best Practices | Assume non-breaking changes, do not restrict webhook endpoints by IP address |
| 8 | Common Mistakes | redirect_uri mismatch, localhost restrictions, wrong base URLs for token exchange vs API calls |
| 9 | Current Limitations and Future Improvements | Known platform limitations to design around today, with planned improvements: refresh tokens, stable error slugs, uninstallation events, and more |