When the iframe and script tag integrations don’t fit — because you need a fully custom UI, server-driven flows, or programmatic management of flows, contacts, and transcripts — the Dialai REST API is the way in. This page is the developer’s starting point. For information on passing trusted user identity into a chat session, see Passing Context Securely — it covers the security model that applies to every API call carrying user context.Documentation Index
Fetch the complete documentation index at: https://docs.dialai.ca/llms.txt
Use this file to discover all available pages before exploring further.
The OpenAPI spec
Dialai is built API-first. Every operation in the platform is described in a single OpenAPI 3.2 document. After signing in, the Swagger UI is available at:https://{your-instance}.dialai.ca/api/swagger/openapi.json. Both endpoints require an authenticated session — get one via the Swagger UI’s sign-in flow.
The spec is what powers the generated TypeScript client used by the web app. Use it to generate clients in whatever language you target.
Authentication
Two patterns, depending on who’s calling.Operator / human callers — OAuth 2.0 (PKCE)
For interactive flows and operator-driven scripts, use the same OAuth flow the platform UI uses. Point a standard OAuth2 PKCE client at:Service / backend callers — Bearer JWT
Backend integrations pass a JWT in theAuthorization header:
- Issued by your own identity provider and verified against a JWKS endpoint you’ve configured on your tenant (see Passing Context Securely > External JWT).
- Minted via the tenant’s service-account client, if your deployment configures one.
X-DialAi-Chat-Link: Bearer <chat-link-uuid> header is also accepted in place of a user JWT — useful for client-side flows where the user just has a chat link UUID.
Tenant scoping
Most operations are scoped to a tenant. The tenant is templated into the path:{tenant} path segment. The token-exchange JWT must have an audience matching that tenant — exchange a fresh tenant-scoped token via the realm’s /token endpoint before each tenant call.
Operation surface
The API is large; here’s a navigational map by purpose.| Domain | Common operations |
|---|---|
| Chat (web) | POST /api/org/{tenant}/v2/webchat (create transcript), POST .../v2/webchat/{transcriptId} (send user message), POST .../v2/webchat/{transcriptId}/addCsrMessage, POST .../v2/webchat/{transcriptId}/CsrTakeOver, PUT .../v2/webchat/{transcriptId}/status (complete) |
| Transcripts | List, search, fetch by ID, fetch readable, edit tags |
| Flows | POST/PUT/DELETE /api/v1/{tenant}/flows/handlers/..., state and transition CRUD, publish snapshots, import/export |
| Functions | JS function CRUD, source export/import, test, snapshot management |
| Channels | Phone, SMS, email, web, Slack POC CRUD and configuration |
| Outbound campaigns | Campaign CRUD, manifest upload, dispatcher control, contact-level operations |
| Knowledge | Documents (upload, list, delete, S3/Confluence sync), FAQ CRUD, embeddings |
| Tenant admin | Branding, environment values, secrets, feature flags, users, roles, permissions |
| Telemetry | System health, mission-control metrics |
/api/swagger — every operation includes its request and response schemas, and you can try requests live with your current session.
Rate limits
The platform doesn’t enforce hard rate limits on the API per se — capacity is bounded by:- Telephony: outbound voice calls are capped by your configured per-tenant Twilio concurrency. Voice-related operations queue rather than fail under load.
- LLM concurrency: per-tenant LLM throughput is bounded by the model pool. Operations that drive LLM calls (creating transcripts, sending messages) experience back-pressure when the pool is saturated.
- Background indexing: document and embedding operations run async — the upload endpoint returns 202 immediately and indexing happens in the background.
Webhooks and callbacks
Per-channel callbacks are configured via the channel-configuration API. For example, a Twilio voice POC can be configured to call your webhook on call completion viaupdate-channel-specific-configuration. The exact callback shape depends on the channel — see the channel-specific operation schema for the configurable fields.
There is no generic “subscribe to all events” webhook. Push-style integration generally happens via:
- Per-channel callbacks (configured on a POC).
- Customer journey events (consumable via the customer-journey API for backfill/sync).
- Server-Sent Events on the in-flight conversation stream — used by Live View to render conversations in real time.
SDKs and tooling
- Swagger UI — interactive request builder served at
https://{instance}.dialai.ca/api/swaggerafter sign-in. Best for ad-hoc exploration and testing. - OpenAPI generators — point any of the openapi-generator tools at
https://{instance}.dialai.ca/api/swagger/openapi.json(after authenticating to download it) to scaffold a client in your language of choice.
When NOT to use the API
If your need is “embed a chat on my website”, use iframe or script tag integration. They’re built on top of this same API but handle session bootstrapping, auth, and rendering for you. If your need is “let my AI agent call my service”, the right primitive is a Function inside your flow — not an API integration. If your need is “I want to sync customer journey data to my CRM”, consider the customer-journey API which is purpose-built for backfill/sync.Related
Passing context securely
Verified user identity in API-driven sessions.
iframe integration
Embed-driven, no API client needed.
Script tag integration
Button-and-modal embed via a single script.
Functions and events
Let the AI agent call your services from inside a flow.