API & Developers
By Conversa Labs
By Conversa Labs
REST API, tokens, webhooks, Custom Scripts SDK and per-module events.
API & Developers overview
Overview ConversaLabs offers developer capabilities to integrate external systems: a REST API to read and write data, webhooks to receive events in real time, a Custom Scripts SDK to extend the interfaces, and per-module events to react to changes. Prerequisites - An account with permission to generate API tokens. - Basic HTTP/JSON knowledge. Step by step 1. Generate an access token in your profile/account settings. 2. Call the REST API authenticating with the token. 3. Configure webhooks to receive events at your endpoint. 4. Use Custom Scripts to customize the dashboard, the portal and the widget. Settings & options - Tokens: per user/account, with access scope. - Webhooks: subscribe to events per inbox/account. - Custom Scripts: JS/CSS injected into the supported surfaces. Use cases - Sync contacts and conversations with an external CRM. - Trigger automations in your system when something changes on the platform. Tips, limits & best practices - Treat tokens as secrets; never expose them in the front-end. - Respect rate limits and handle errors/retries. Troubleshooting - 401/403: check the token and permissions. - Webhook not arriving: verify the URL, the endpoint status and the signature. See also - REST API, tokens and webhooks - Custom Scripts SDK
REST API, tokens and webhooks
Overview The REST API lets you read and write platform data (contacts, conversations, messages and more). Authentication uses an access token, and webhooks deliver events to your system in real time. Prerequisites - A valid access token. - An HTTPS endpoint to receive webhooks. Step by step 1. Generate an access token in settings. 2. Include the token in the auth header of your API calls. 3. Make requests to API resources (e.g., list contacts, create a conversation). 4. Configure a webhook with the URL and the events you want. 5. Validate the webhook signature/secret before processing the payload. Settings & options - Token scope: limit access to what's needed. - Webhook events: subscribe only to the events you use. - Redelivery: handle retries and idempotency on your endpoint. Use cases - Mirror conversations into a data warehouse. - Notify an external system when a conversation is created or resolved. Tips, limits & best practices - Always verify the webhook signature before acting. - Ensure idempotency (dedup by event identifier). - Respect rate limits and use backoff on 429/5xx errors. Troubleshooting - 401/403: invalid token or missing permission. - Duplicate webhook: implement dedup by event ID. See also - API & Developers overview - Per-module events
Custom Scripts SDK
Overview Custom Scripts let you inject JavaScript/CSS into specific platform surfaces — the dashboard, the Help Center portal and the chat widget. They're useful for small behavior and style customizations without changing the codebase. Prerequisites - Administrator permission to manage Custom Scripts. - JavaScript/CSS knowledge. Step by step 1. Open the Custom Scripts module. 2. Create a script and choose the surface (dashboard, portal or widget). 3. Set the type (JS or CSS) and when it should run. 4. Use the ctx context provided by the runtime to interact with the surface safely. 5. Implement teardown to clean up what the script created, when applicable. Settings & options - Surface: dashboard / portal / widget. - Type: JS or CSS. - Execution: rules for when the script runs. Use cases - Add a button or notice on a specific screen. - Tweak targeted styles of a surface. - Log usage events for internal analysis. Tips, limits & best practices - Write idempotent scripts with teardown to avoid duplication. - Avoid heavy dependencies; prefer lean code. - Test in a controlled environment before publishing. Troubleshooting - Script doesn't run: confirm the surface and execution rules. - Duplicated behavior: check teardown and idempotency. See also - API & Developers overview - Custom Scripts (Administration)
Per-module events
Overview Many platform modules emit events when something changes — a conversation is created, a payment is confirmed, a deal changes stage, etc. You can react to these events via webhooks or through the internal automation rules. Prerequisites - Configured webhooks (for external consumption) or Automation access (for internal reactions). Step by step 1. Identify the module event you want to consume (e.g., conversation created, payment paid). 2. For external consumption: subscribe to the event in the webhook and handle the payload at your endpoint. 3. For internal reactions: create an automation rule with the matching trigger. 4. Validate and process the payload idempotently. Settings & options - Webhooks: subscription per inbox/account. - Automation: per-event triggers, with conditions and actions. - Payload: contains the event context (ids and relevant data). Use cases - Update an external system when a payment is confirmed. - Trigger a follow-up cadence when a deal changes stage. Tips, limits & best practices - Always check the real payload source before mapping fields (don't invent the format). - Ensure idempotency by event identifier. Troubleshooting - Event not arriving: confirm the subscription and the endpoint status. - Unexpected fields: review the actual received payload and adjust the mapping. See also - REST API, tokens and webhooks - Automation rules