Current Limitations and Future Improvements
This page documents known limitations in the current platform along with the improvements we are planning. We want to be transparent about what is not yet supported so you can design your integration accordingly.
1. Refresh Tokens
Current limitation: Access tokens have a very long expiry and do not require regular renewal in practice. However, there is no refresh token mechanism. If a token becomes invalid for any reason, the user must manually reconnect your app by going through the OAuth flow again.
Planned improvement: We plan to introduce refresh tokens so your app can silently renew access in the background without requiring any action from the user. This is standard OAuth 2.0 behavior. Once available, it will eliminate the need for the manual reconnect flow described in OAuth Flow.
2. App Uninstallation Webhook
Current limitation: There is currently no notification when a user uninstalls your app. Your backend has no way to know the app was removed from their workspace.
Planned improvement: We plan to fire an app.uninstalled webhook event when a user uninstalls your app. This will allow you to automatically clean up stored tokens, contact mappings, and any workspace-specific data on your end.
3. Webhook Retries
Update: Failed webhook deliveries can be retried with exponential backoff (up to 5 retries after the initial attempt, starting at ~30 seconds and capped at 15 minutes, with jitter). A 410 Gone response stops retries immediately. Retries are opt-in per app and off by default, turn on Enable webhook retry in Developer Configuration → Event Subscriptions. A retried delivery carries a metadata object (retry_count, retry_limit, retry_reason) that the first attempt does not. Each webhook also carries a top-level envelope id and created_at that are stable across retries, so you can deduplicate and order deliveries. See CRM Webhooks: Retries and Idempotency.
Remaining limitation: Once retries are exhausted, the event is dropped and not redelivered. For events you cannot afford to lose, keep a polling fallback as described in Error Handling.
4. Stable Error Slugs
Current limitation: The slug field in error responses is not stable and may change as the API evolves. For now, we recommend branching your error-handling logic on HTTP status codes rather than slugs.
Planned improvement: We plan to introduce a stable slug contract. Once in place, you will be able to rely on slugs for precise programmatic error handling: for example, distinguishing a scope-related 403 from other forbidden responses without parsing the message string.
5. Creating Channels via API
Current limitation: Your app cannot create CRM Channels through the API. Channels must be created manually by the user in the CRM Dashboard. Your app can discover existing channels by calling GET /v1/channels.
Planned improvement: We plan to add a POST /v1/channels endpoint so your app can create and configure channels programmatically during setup. This will simplify onboarding, particularly for apps that need to provision a dedicated channel per connected account.
6. Self-Service App Publishing
Current limitation: Publishing your app to the marketplace currently requires contacting us directly. There is no self-service option at this time.
Planned improvement: We plan to add a self-service publishing flow in the Developer Configuration dashboard. You will be able to submit your app for review, track its review status, and publish or unpublish it without needing to reach out to us. This will also include the ability to manage the unpublish flow described in Distribution.
7. SSO for Third-Party App Dashboards
Current limitation: There is no single sign-on support for third-party app dashboards. If a user wants to access your app's configuration page, your app has no way to verify their identity without building a separate authentication system of its own.
Planned improvement: We plan to provide an SSO mechanism that lets users log in to your app's dashboard using their CRM identity. Your app will be able to verify who they are and which workspace they belong to without requiring a separate login. This will also remove the need for the reinstall workaround described in #10.
8. conversation.failed Webhook Event
Current limitation: There is no conversation.failed webhook event. When a POST /v1/conversations request is accepted with a 202 but the conversation fails to be created on the backend, your app receives no notification. It will simply wait for a conversation.created event that never arrives.
Planned improvement: We plan to add a conversation.failed webhook event that fires when an async conversation creation fails. The payload will include the request_id from the original 202 response so your app can match it to the pending record and decide whether to clean up or retry.
9. request_id Missing from Conversation Webhook Events
Current limitation: Conversation webhook event payloads (such as conversation.created) do not include the request_id that was returned in the 202 Accepted response from POST /v1/conversations. The only way to correlate a creation request to its webhook event is by matching contact_id and channel_id, which can be unreliable when multiple messages arrive concurrently.
Planned improvement: We plan to include request_id in conversation webhook payloads (including conversation.failed, once added). This will give your app a direct and unambiguous way to match each webhook back to the API call that triggered it.
10. Reinstall Button Required to Access Third-Party App Dashboard
Current limitation: The only way a user can access your app's dashboard from the CRM is by clicking the Reinstall button on the app details page. This re-runs the full OAuth flow to give your app a fresh token, which your app can then use to create a session and redirect the user. There is no direct "Open Dashboard" link that works without going through OAuth again.
Planned improvement: Once SSO is available (see #7), we plan to provide a direct "Open Dashboard" link that passes an SSO token to your app. Your app can verify the token, establish a session, and let the user in, without requiring a full OAuth reinstall every time.
12. Third-Party App-Initiated OAuth Is Currently Broken
Current limitation: The OAuth Flow actually has another flow where your app initiates the OAuth flow from your own website. This flow is currently not working.
Planned improvement: We plan to fix the app-initiated OAuth flow so it works correctly end to end. In the meantime, please use the CRM-initiated flow, where the user clicks Install from the CRM Dashboard.
13. No Notification When Reinstallation Is Required for New Scopes
Current limitation: If you add new OAuth scopes to your app, existing users are not notified that they need to reinstall. Their current installation continues to work with the old scopes, but any features that depend on the new scopes will fail silently. There is no banner, prompt, or notification in the CRM to inform users that a reinstall is needed.
Planned improvement: We plan to surface a reinstallation prompt to users when an installed app's required scopes have changed. Until this is available, the recommended workaround is to check the granted scopes for each workspace installation, identify which ones are missing the new scopes, retrieve the agent's email address from their profile, and send them a direct notification asking them to reinstall the app from the CRM Dashboard to grant the updated permissions.
14. Announcements Are Not Returned by the Read API
Current limitation: Messages sent with message_type=ANNOUNCEMENT (see Sending Announcements as Your App) are persisted and delivered to the conversation, and subscribed apps receive them via the message.created webhook, but GET /v1/conversations/{id}/messages does not return them. If your app needs a record of the announcements it sent, store them on your side when you send them or when the message.created webhook arrives.
Planned improvement: Exposing announcements (and other app-visible message types) through the read API is under consideration. The same asymmetry currently exists for WHISPER / WHISPER_ATTACHMENT messages, which are delivered via webhook but hidden from GET.