# Agent Voices
Source: https://docs.dialai.ca/agent-voice

Pick the synthetic voice your AI agent uses on voice channels and per-flow variants

<Frame>
  <img alt="Voices tab in Building Blocks (light mode)" />

  <img alt="Voices tab in Building Blocks (dark mode)" />
</Frame>

The synthetic voice an AI agent uses on phone calls (and on voice-enabled web chats) is configured in two places:

1. **The voice catalog** — every voice available to your tenant. Managed under [Building Blocks > Voices](/building-blocks#voices).
2. **Per-POC voice assignment** — which voice each Phone or Web POC uses, set on the [Points of Contact > Edit > Variants tab](/points-of-contact#variants).

This page is the operator's guide to both.

## The voice catalog

Navigate to **Build > Building Blocks > Voices** to see every voice configured for your tenant.

Each voice has:

* **Display Name** — what shows in dropdowns (e.g., "Clara").
* **Description** — voice characteristics (e.g., "Female, Multilingual, Fast").
* **Sample** — a play button to preview the voice with the configured sample text.
* **Download** — save the sample audio to disk.

### Previewing voices

Click the play button on any row. The sample plays with whatever text you've configured via **Voice Sample** at the top of the page.

### Editing the sample text

Click **Voice Sample** to change the text that previews use. Useful for hearing specific brand phrases, customer-facing names, or terminology your agent will actually say.

### Adding and removing voices

* **Create** — add a new voice from the supported voice catalog.
* **Delete** — remove a voice. Any POC currently using the deleted voice falls back to the tenant default.

## Assigning a voice to a POC

A voice is selected per Variant on a Phone or Web POC:

<Steps>
  <Step title="Open the POC">
    Navigate to **Agent > Points of Contact**, find the POC, click **Edit**.
  </Step>

  <Step title="Switch to the Variants tab">
    The first variant (`A`) is selected by default; create more variants for A/B testing different voices.
  </Step>

  <Step title="Pick a voice">
    Use the **Voice** dropdown to select from the catalog.
  </Step>

  <Step title="Save">
    Submit the variant changes; the new voice applies to subsequent calls.
  </Step>
</Steps>

## Tips

* **Match voice to brand.** A clinical hospital line wants a different voice than a casual retail line. Listen to a few options with realistic sample text before deciding.
* **Test multilingual voices on multilingual flows.** Some voices speak only one language well; pick a clearly multilingual voice if your flow handles `Multilingual` as a language setting.
* **A/B test before standardizing.** Use Variants on a Phone POC to split traffic across two voices and compare downstream metrics (handle time, customer satisfaction proxy).
* **Re-sync sample text after major copy changes.** When you update the agent's standard greeting, update the Voice Sample to match — easier to evaluate voices against words you actually use.

## Related

<CardGroup>
  <Card title="Building blocks" icon="cubes" href="/building-blocks">Manage the full voice / tag / parameter catalog.</Card>
  <Card title="Points of Contact" icon="phone" href="/points-of-contact">Assign a voice to a specific Phone or Web POC.</Card>
  <Card title="Flow configuration" icon="sliders" href="/flow-configuration">Configure the speaker language a voice expects.</Card>
</CardGroup>


# Agents
Source: https://docs.dialai.ca/agents

Internal AI agents that help your team analyze conversations, build flows, and run back-office tasks

<Frame>
  <img alt="Explore Agents panel in light mode" />

  <img alt="Explore Agents panel in dark mode" />
</Frame>

**Agents** are internal AI assistants your team uses *inside* the platform. They search transcripts, summarise conversations, run reports, draft flows, schedule background work, and generally let you point natural language at the product instead of clicking through menus. They never face customers — for customer-facing AI, build a [Flow](/flows).

## Where agents live

Internal agents are not on the Flows page anymore — they're surfaced through four fixed buttons at the **bottom-right of every page**:

| Button | What it opens |
| - | - |
| **Chat with Agent** | The chat panel for whichever agent you last used. |
| **Chat History** | Past chat threads, searchable and resumable. |
| **Explore Agents** | The list of every agent in your tenant, plus the **+** button to create a new one. |
| **Scheduled Agent Tasks** | Background jobs you've handed off to agents (e.g., "every Monday, summarise last week's flagged transcripts"). |

The Explore Agents panel slides out from the right and shows each agent with its name, one-line description, and a kebab menu (`⋮`) for edit / delete actions.

## Talking to an agent

Click any agent to open the chat pre-targeted at that agent, or click **Chat with Agent** to resume the last-used agent. Send a message; the agent uses its configured prompt and functions to respond.

<Frame>
  <img alt="The redesigned agent chat (light mode)" />

  <img alt="The redesigned agent chat (dark mode)" />
</Frame>

The chat is a full-page workspace: an agent picker in the top-left switches between your agents without leaving the page, **History** (top-right) reopens earlier threads, and the compose bar supports text, voice (speech-to-text), and file attachments. Replies render Markdown (headings, bullets, tables, links), and when a visual helps, the agent renders artifacts inline: tables, charts, flow graphs, PDFs, and decks.

## Creating an agent

Click the **+** button at the top of the Explore Agents panel (or navigate to `/Agents/New`). The editor opens to the **Prompt** tab.

## Configuring an agent

<Frame>
  <img alt="Agent Prompt tab in light mode" />

  <img alt="Agent Prompt tab in dark mode" />
</Frame>

Each agent has five tabs.

### Prompt

The system instructions that define the agent's role, capabilities, and behavior. Includes:

* **Name** — shown in Explore Agents and the breadcrumb.
* **Description** — one-line summary, also shown in Explore Agents.
* **Model Type** — pick the model variant. Fast (lower latency, lighter reasoning) vs reasoning-tier (slower, deeper).
* **Prompt** — rich-text editor for the agent's instructions. Supports headings, bullets, bold/italic.
* **Suggested Messages** — clickable starter prompts shown when a user opens a fresh chat. Each suggestion has a **label** (what the user sees) and a **prompt** (what gets sent).

A workable structure for the prompt:

```text theme={null}
Act as a <ROLE> within our AI contact center platform. You will help internal staff <PURPOSE>.

Workflow & Capabilities
- <capability 1>
- <capability 2>
- <capability 3>

Steps for <COMMON TASK>
1. Call <toolA> to gather…
2. Call <toolB> to filter…
3. Return a short summary.

Formatting
- Use Markdown headings and bullets
- Keep responses brief
- Never return raw data dumps unless requested
```

<Tip>Use direct verbs ("must", "will") instead of suggestions ("should", "can"). Agents follow declarative instructions more reliably than aspirational ones.</Tip>

### Functions

<Frame>
  <img alt="Agent Functions tab in light mode" />

  <img alt="Agent Functions tab in dark mode" />
</Frame>

Pick which JS functions the agent can invoke. Click **Add Functions** to open the picker, then select the functions to grant. Each enabled function becomes a tool the agent can call during a conversation.

Common picks for a Conversation Analyst Agent:

* `listTranscripts`, `countTranscripts` — search and count.
* `getTranscriptReport`, `getReadableTranscript` — inspect.
* `getTagsForTranscript`, `setTagsForTranscript` — read and write tags.
* `searchDocuments` — ground in playbooks and SOPs.

<Note>The fewer functions you enable, the more predictable the agent's behaviour. Resist the urge to grant every function "just in case" — every extra function adds reasoning load.</Note>

### Memory

Long-lived facts the agent should always know. Add entries for things like "the company's fiscal year ends in March", "our SLA is 24 business hours", "we never discount more than 10% without manager approval". Memory entries persist across every chat and apply to every conversation the agent has.

### Variables

Static parameter values that the enabled functions require. When you add a function that needs configuration (an API key, a tenant ID, a base URL), that requirement surfaces here so you can supply the value once instead of per-call.

### Branding

PDF and PowerPoint export styling for agents that produce documents. Set a company name, primary/secondary colours, upload a logo (PNG/JPEG/SVG ≤ 2 MB), and optionally write free-form logo-usage instructions ("logo top-right, page 1 only"). Leave blank to use platform defaults.

## Scheduled agent tasks

Agents can also run on their own, with no manual kickoff. **Scheduled agent tasks** turn any internal agent into a recurring job: daily review passes, routine checks, regular reports.

<Frame>
  <img alt="Editing a scheduled agent task (light mode)" />

  <img alt="Editing a scheduled agent task (dark mode)" />
</Frame>

Open **Scheduled Agent Tasks** (bottom-right of every page) and click **New task**. Each task has:

* **Base agent**: the internal agent that runs. Locked once the task is created.
* **Name**: what the task is called in the list and in past runs.
* **First message**: the prompt the agent receives at the start of every run. Write it like a standing work order: what to do, what a good run leaves behind, and where the boundaries are.
* **Schedule**: repeat cadence and one or more times of day.
* **Active**: the on/off switch. Runs start once the task is initialized and active.

Use **Run now** to trigger a run immediately (useful while tuning the first message), and **View past runs** to audit what each run did.

<Tip>Pair a scheduled task with [Issues](/issues): a daily review task that files its findings as issues and proposed changes leaves your team an actionable queue each morning, with a human approval gate before anything is applied.</Tip>

## Use cases

| Agent purpose | Functions typically enabled | Notes |
| - | - | - |
| **Conversation Analyst** | `listTranscripts`, `countTranscripts`, `getTranscriptReport`, `getTagsForTranscript`, `setTagsForTranscript` | QA and reporting. |
| **Flow Builder** | `searchFlows`, `createFlow`, `createState`, `editState`, `createTransition` | Drafts flows from a natural-language brief. |
| **Campaign Reporter** | `listOutboundCampaigns`, `getCampaignStats`, `searchTranscripts` | Pull-the-numbers reports on outbound results. |
| **Knowledge Curator** | `searchDocuments`, `listFaqs`, `createFaq` | Find gaps in your knowledge base and propose new FAQs. |

## Agents vs Flows

| | Agent | Flow |
| - | - | - |
| Who talks to it | Your team, inside the platform. | Your customers, on a channel. |
| Surface | Chat panel (bottom-right). | Voice, SMS, email, web chat, etc. via a [Point of Contact](/points-of-contact). |
| Logic shape | Single prompt + tool list. | Stateful graph with transitions, events, and per-state thoughts. |
| Published? | Always live for everyone in your tenant. | Has draft and published versions. |
| Testable how | Just chat with it. | [Chat sandbox + Test Scenarios](/testing-flows). |

If you're not sure which to build: would a customer ever talk to this? If yes, build a Flow. If only internal staff, build an Agent.

***

## Related

<CardGroup>
  <Card title="Functions and events" icon="code" href="/functions-and-events">Authoring the JS functions agents call.</Card>
  <Card title="Flows" icon="diagram-project" href="/flows">Customer-facing equivalent.</Card>
  <Card title="Documents" icon="book" href="/manage-documents">Ground your agents in real source-of-truth content.</Card>
  <Card title="Schedule" icon="calendar" href="/schedule">When the tenant is open — relevant for scheduled agent tasks.</Card>
</CardGroup>


# API Integration
Source: https://docs.dialai.ca/api-integration

Direct programmatic access to the Dial AI platform when the embedded widget isn't enough

When a [web widget](/web-widgets) does not fit — because you need a fully custom UI, server-driven flows, or programmatic management of flows, contacts, and transcripts — the Dial AI REST API is the way in.

This page is the developer's starting point. To tell a web widget who the signed-in customer is, see [Signed-in visitors](/web-widget-sign-in). For the legacy chat links, see [Passing Context Securely](/integration-context).

## The OpenAPI spec

Dial AI 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
```

…and the raw spec is 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:

```
https://auth.{instance}.dialai.ca/realms/dial-ai/protocol/openid-connect/auth
```

After acquiring a user token, mint tenant-scoped JWTs via [RFC 8693 token exchange](https://datatracker.ietf.org/doc/html/rfc8693) against the same realm's token endpoint. Pass the resulting tenant-scoped JWT as a Bearer token on each request.

### Service / backend callers — Bearer JWT

Backend integrations pass a JWT in the `Authorization` header:

```http theme={null}
GET /api/v1/transcripts HTTP/1.1
Authorization: Bearer <your-jwt>
```

JWTs can be:

* Issued by your own identity provider and verified against a JWKS endpoint you've configured on your tenant (see [Passing Context Securely > External JWT](/integration-context#approach-1-external-jwt-with-public-key-verification)).
* Minted via the tenant's service-account client, if your deployment configures one.

For chat-link operations, the `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:

```
POST /api/v1/{tenant}/flows/handlers
GET  /api/v1/{tenant}/transcripts
```

Pass the tenant slug as the `{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 |

The fastest way to discover an operation is the Swagger UI at `/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.

For high-throughput automation (e.g. nightly bulk transcript imports), reach out to your account contact — quotas are tunable per tenant.

## 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 via `update-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/swagger` after sign-in. Best for ad-hoc exploration and testing.
* **OpenAPI generators** — point any of the [openapi-generator](https://openapi-generator.tech) 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 a [web widget](/web-widgets). It handles sessions, auth, and rendering for you. The legacy [iframe](/iframe-integration) and [script tag](/script-tag-integration) integrations are deprecated.

If your need is "let my AI agent call my service", the right primitive is a [Function](/functions-and-events) 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](/integration-context) which is purpose-built for backfill/sync.

***

## Related

<CardGroup>
  <Card title="Web Widgets" icon="comment" href="/web-widgets">Put chat on your website with one script tag.</Card>
  <Card title="Signed-in visitors" icon="user-check" href="/web-widget-sign-in">Verified customer identity in a web widget.</Card>
  <Card title="Passing context securely" icon="shield" href="/integration-context">Verified user identity for legacy chat links.</Card>
  <Card title="Functions and events" icon="code" href="/functions-and-events">Let the AI agent call your services from inside a flow.</Card>
</CardGroup>


# Building Blocks
Source: https://docs.dialai.ca/building-blocks

Manage tags, voices, parameters, and test scenarios shared across your flows

<Frame>
  <img alt="Building Blocks Tags tab in light mode" />

  <img alt="Building Blocks Tags tab in dark mode" />
</Frame>

The **Building Blocks** page is a centralized hub for the reusable components that power your flows: **Tags** (the structured data you capture during conversations), **Voices** (the synthetic voices your AI agents use), **Parameters** (the typed JSON schemas your functions consume), and **Test Scenarios** (the recorded conversations that assert flow behavior).

To access Building Blocks, navigate to **Build > Building Blocks** in the left navigation menu.

<Note>The **Test Scenarios** tab only appears for users who have the `test-scenarios:list` permission scope. Ask an administrator if you don't see it.</Note>

***

## Tags

Tags structure and enrich the data captured during conversations. Use them to label intents, classify outcomes, surface fields the AI extracted, or any other key/value you want consistently attached to transcripts.

### What's in the table

Each row in the Tags table shows:

| Property | Description |
| - | - |
| **Tag Name** | The name used to label the captured data. |
| **Answer Format** | The expected format of the tag value (e.g., Text, True or False). |
| **Flow** | The flow this tag is configured on. |
| **Auto Fill** | Whether the tag is automatically populated during the conversation. |

### Working with tags

* **Create** — opens the new-tag form. Pick a name, format, and target flow.
* **Delete** — removes a tag definition. Existing transcripts that already have the tag set keep their data; future conversations won't write to it.

***

## Voices

<Frame>
  <img alt="Voices tab in light mode" />

  <img alt="Voices tab in dark mode" />
</Frame>

The Voices tab manages the synthetic voice options available to your flows.

### What's in the table

| Property | Description |
| - | - |
| **Display Name** | The name shown when selecting a voice. |
| **Description** | Voice characteristics (e.g., "Female, Multilingual, Fast"). |
| **Sample** | Preview button — plays a short sample with the configured sample text. |
| **Download** | Save the voice sample to disk. |

### Working with voices

* **Voice Sample** — set the sample text used for preview playback. Edit and save to update what every voice previews against.
* **Create** — add a new voice from the catalog. Voices added here become selectable on every flow's Variables tab.
* **Delete** — remove a voice from your tenant. Flows currently using the voice fall back to the tenant default.

***

## Parameters

<Frame>
  <img alt="Parameters tab in light mode" />

  <img alt="Parameters tab in dark mode" />
</Frame>

Parameters are typed JSON schemas reused across functions and flows. Define a parameter once here; reference it from any function input or static-parameter slot.

### What's in the table

| Property | Description |
| - | - |
| **Name** | The parameter's identifier (e.g., `ZipCode`, `TwilioAuthToken`). |
| **Schema** | The JSON schema definition (e.g., `{ "type": "string" }`). |

### Working with parameters

* **Filter** — narrow the list by name.
* **Create** — add a new parameter. Pick a name and provide its JSON schema.
* **Edit** — update an existing parameter's schema. All functions referencing it see the new schema on next call.

<Note>Parameters are also accessible inline from the flow editor and function editor — anywhere you can attach a parameter, you can also create or edit one. The Building Blocks page is the only place to see them all at once.</Note>

***

## Test Scenarios

The **Test Scenarios** tab gives administrators a tenant-wide view of recorded test scenarios across every flow. Each scenario is a captured conversation with assertions that can be replayed against future flow versions to catch regressions.

Most operators interact with test scenarios from within an individual flow's editor; the Building Blocks tab is the cross-flow inventory and bulk-management view. For the full workflow — creating scenarios, adding assertions, and reviewing versioned results — see [Testing Flows](/testing-flows).

***

## Related

<CardGroup>
  <Card title="Functions and events" icon="code" href="/functions-and-events">Wire parameters into function inputs.</Card>
  <Card title="Flow configuration" icon="sliders" href="/flow-configuration">Set static parameter values per flow.</Card>
  <Card title="Agent voice" icon="volume-high" href="/agent-voice">Configure per-flow voice selection.</Card>
</CardGroup>


# Conversations
Source: https://docs.dialai.ca/conversations

Monitor and evaluate AI agent interactions with customers

<Frame>
  <img alt="Conversations list in light mode" />

  <img alt="Conversations list in dark mode" />
</Frame>

The **Conversations** page is the searchable archive of every interaction your AI agent has had with a customer — voice calls, web chats, SMS threads, and email conversations. Use it to spot-check quality, investigate flagged calls, build training datasets, and surface trends.

For in-flight conversations that need a human right now, see the [Inbox](/inbox). For real-time monitoring of conversations as they happen, see [Live View](/live-view).

## Accessing Conversations

Navigate to **Monitor > Conversations** in the left sidebar.

## The conversations table

Each row in the table is one conversation. Columns include:

| Column | What it shows |
| - | - |
| **ID** | The conversation's unique identifier. |
| **Platform** | Voice / SMS / Web / Email / Slack icon. |
| **Contact** | Phone number, email address, or contact name. |
| **Status** | See the [status reference](#call-status-indicators) below. |
| **Flow** | The flow this conversation ran through. Click "View Flow" to open it. |
| **Duration** | Total time from start to end. |
| **Last Message** | When the most recent message was sent. |
| **Date** | When the conversation started. |
| **Flagged** | A flag icon means the conversation was marked for review. |
| **Functions** | Function calls the agent made during the conversation. |
| **Parameters** | Internal parameter key/value pairs (e.g., account IDs). |
| **Tags** | Metadata like Call Reason, Language, Issue, and function outputs. |

Click any conversation to open the detail view.

### Call status indicators

* **Completed** — the conversation was successfully concluded.
* **Abandoned** — the customer ended the conversation prematurely.
* **Failed** — the conversation hit a technical issue.
* **Human Handoff** — handed off to a human, by the AI or by a supervisor.
* **In Progress** — currently active.
* **Reported** — flagged via the reporting workflow.
* **Restarted** — the conversation was restarted.
* **Unsubscribed** — the contact unsubscribed during the conversation.
* **No Answer** — the contact did not pick up.
* **Answering Machine — Message Left** / **No Message Left** — voicemail detected, with or without leaving a message.

## Conversation detail view

Selecting a conversation opens the detail view, which gives you a granular look at the interaction. The right-hand panel shows:

* **Platform** and **Point of Contact** — the channel and which POC the customer used to reach you.
* **Contact ID** — unique customer identifier (clickable to see all conversations from this contact).
* **Status** — the final outcome.
* **Tags** — Call Reason, Language, Issue, and any function-derived tags.
* **Sentiment** — top emotions detected during the conversation.
* **Flow** — which flow ran, with a link to open it.
* **Voice** — the synthetic voice used (for voice conversations).
* **Duration**, **Start**, **End** — timing.
* **Reason** — the AI's classification of why the customer called.
* **Summary** and **Analysis** — narrative and evaluation of how the conversation went.

The center panel shows the full transcript alongside the flow graph, with timestamps, function call results, and audio playback (for voice calls).

### Internal agent artifacts

When the AI agent generates artifacts during a conversation — CSVs, charts, PDFs, etc. — they appear inline in the transcript detail view. Click an artifact to preview it or download it locally. Artifacts are served from a CSP-locked subdomain so they can be safely embedded in the transcript.

### Export and download

The three-dot menu in the top-right of the detail view opens transcript management options:

* **Export transcript** — exports the full text transcript for documentation or training data.
* **Download audio** — saves the call recording (voice conversations only).
* **Delete** — removes the conversation from the list. Useful for clearing test conversations or obsolete records.

### Call monitoring actions

> These controls are available **only while an AI Agent call is in progress**. If a call is **queued** or **assigned** to a human, these actions are not shown.

### Listen In

Silent monitoring of the live call. The caller and the agent do not hear you.

**How to use**

1. Open the **⋯ Actions** menu on the active call.
2. Select **Listen In**.

**What happens**

* You can hear the conversation in real time.
* Your microphone is not connected to the call.

***

### Take Over

Assume live control of the call. You can hand control back later.

**How to use**

1. Open **⋯ Actions**.
2. Select **Take Over**.

**What happens**

* You are connected as the speaking participant.
* When finished, hand control back to the previous participant (AI Agent or original agent).

***

### Transfer

Send the live call to an **external phone number**.

**How to use**

1. Open **⋯ Actions**.
2. Select **Transfer**.
3. Enter the destination phone number.
4. Confirm to transfer.

**What happens**

* The system dials the destination number and bridges the caller.
* After transfer, control moves to the external destination.

***

### Enqueue

Move the live call into the **human agent queue**.

**How to use**

1. Open **⋯ Actions**.
2. Select **Enqueue**.

**What happens**

* The call is placed back into the queue to be assigned to a human agent.
* The AI Agent stops handling the call.

***

### End

Immediately hang up the call for all parties.

**How to use**

1. Open **⋯ Actions**.
2. Select **End** and confirm.

**What happens**

* The call ends immediately.
* Post-call processes (wrap-up, logging, transcript, etc.) continue as configured.

***

### Add Coaching

Send **coaching notes** to the agent only (not visible to the caller) while the call is active.

**How to use**

1. Open **⋯ Actions**.
2. Select **Add Coaching**.
3. Enter your coaching note and send.

**What happens**

* The note appears to the agent as an internal coaching message during the call.
* The caller never sees coaching notes.

***

### Summary (for quick scan)

| Action | Purpose | Notes |
| - | - | - |
| Listen In | Silent monitoring | No whisper audio |
| Take Over | You become the speaking participant | You can hand control back later |
| Transfer | Send caller to an **external** phone number | Replaces any prior inline refs |
| Enqueue | Return caller to the **human agent queue** | For assignment by a human agent |
| End | Hang up for all parties immediately | Triggers post-call handling |
| Add Coaching | Side-channel guidance to the agent (text only) | Not visible to the caller |

These controls only appear when the conversation is currently in progress.

### Sentiment and flags

Real-time sentiment analysis tags each conversation with the customer emotions detected — gratitude, curiosity, confusion, etc. Flags are set by the AI review agent based on anomalies or custom call-review criteria. Use them to triage which conversations are worth a closer look.

When a flag needs an actual fix rather than just a look, the review agent can open an [Issue](/issues) with a proposed change attached, so the finding becomes tracked, approvable work instead of a flag someone has to remember.

### Functions and parameters

The transcript shows each function call the agent made, with its inputs and outputs. Use this to verify the agent invoked the right tools at the right time and got the right responses back.

## Escalation-risk detection

<Frame>
  <img alt="Escalation risk on a transcript with a Transfer Suggested marker (light mode)" />

  <img alt="Escalation risk on a transcript with a Transfer Suggested marker (dark mode)" />
</Frame>

On voice calls, **escalation-risk detection** listens to the customer in real time and scores how frustrated they sound every few seconds, using a running score history so a sustained rise counts more than a one-off spike. It is voice-native: it reads tone, not just words.

When risk climbs, the system acts on a two-level ladder:

* **Level 1 (default): coaching nudge.** The agent gets a private prompt to acknowledge the frustration and offer a human transfer. The agent decides how to act on it.
* **Level 2 (opt-in, off by default): forced transfer.** If the customer stays escalated after the nudge, the call is handed to a live person automatically.

On the conversation transcript, the messages and the call recording wash red as risk climbs, and an expandable **Transfer Suggested / N% risk** marker shows the risk score and why it fired (for example, raised voice, expletive, abrupt tone). A Level 2 forced transfer shows a **Forced Transfer / N% risk** marker instead. Risk is also flagged live in [Live View](/live-view), where an escalating call turns red so a supervisor can step in.

### Configuring escalation-risk detection

It is **per flow, opt-in, and off by default**, so only enabled flows do any scoring. In the flow editor you can set:

* **Enable escalation-risk detection**: the on/off switch.
* **Threshold**: the score (0 to 100) that counts as a breach (default 70).
* **Consecutive chunks**: how many back-to-back breaches (about 20 seconds) trigger a nudge (default 2).

Level 2 forced transfer, the hard-transfer number, and the audio model are tenant-level settings; ask your account team to enable them.

## Post-transfer journey

<Frame>
  <img alt="Post-transfer journey on a conversation (light mode)" />

  <img alt="Post-transfer journey on a conversation (dark mode)" />
</Frame>

Open a conversation and you can see the customer's full journey: every interaction the contact has had, each with a plain-language summary, its outcome, and its reason, tied together by a journey summary at the top. A transfer no longer ends the story, and the **assigned flow** is shown on handed-off conversations so you always know which flow was running.

Reviewing is richer too:

* **Multi-select flow filter**: filter Conversations by more than one flow at once.
* **Review-category icons**: see at a glance what a review flag was about.
* **Summarized reasoning**: in review mode, the model's summarized reasoning is shown inline, so you can see why it did what it did.

***

## Filtering

Click **Filter** in the top-right to open the filters panel. Each filter has a radio toggle to activate it; the table updates as you go.

| Filter | Use it to find |
| - | - |
| **ID** | A specific conversation by ID. |
| **Status** | One or more outcome statuses. |
| **Date** | A date range. |
| **Platform** | Voice, SMS, Web, Email, Slack, Human Phone. |
| **Flow** | A specific flow. |
| **Direction** | Inbound or outbound. |
| **Used For** | Production vs Test environment. |
| **Flagged** | Flagged-for-review only, or unflagged only. |
| **Repeat contacts** | A range of how many times the contact has interacted. |
| **Contact** | All conversations from a specific contact. |
| **Content** | A keyword or phrase in the transcript. |
| **Function** | Conversations where a specific function was called. |
| **Tags** | Conversations matching one or more tag key/value pairs (AND or OR via the **Match all tags** toggle). |
| **Parameters** | Internal parameter key/value pairs. |

A **View** selector at the top of the filters panel lets you load a saved combination of these filters — see [Views](#views) below.

## Views

A **View** is a saved combination of filters. The **View** dropdown at the top of the filters panel lets you switch between saved views; the three-dot menu next to it lets you set any view as the org-wide default.

Built-in views:

* **All Conversations** — no filters, the default.
* **Production Calls** — production-environment conversations only.
* **Test Calls** — test-environment conversations only.

Configure your own filters and save them as a custom view for quick reuse — for example, "Flagged voice calls in the last 7 days."

## Exporting

The **Export** button in the top-right exports the currently filtered table to CSV. Useful for offline analysis, BI tools, or sharing with stakeholders who don't have platform access.

***

## Related

<CardGroup>
  <Card title="Live View" icon="eye" href="/live-view">Watch in-progress conversations.</Card>
  <Card title="Inbox" icon="inbox" href="/inbox">Take over conversations that need human help.</Card>
  <Card title="Dashboard" icon="chart-line" href="/dashboard">Aggregate metrics and reporting.</Card>
  <Card title="Issues" icon="clipboard-list" href="/issues">Turn review flags into tracked, fixable work items.</Card>
</CardGroup>


# Dashboard
Source: https://docs.dialai.ca/dashboard

View real-time and historical metrics for conversations and agent performance

<Frame alt="Daily Dashboard" />

The **Dashboard** page is your operational hub: it surfaces the day's volume and outcomes, a live snapshot of in-flight work, and configurable historical reporting. Accessed via **Monitor > Dashboard**, it's the place to land when you want a single answer to "how are things going right now?"

## Accessing the Dashboard

Navigate to **Monitor > Dashboard** in the left sidebar. The page opens to a set of tabs (the ones you see depend on your permissions):

1. **Daily Dashboard** — real-time and day-to-date metrics
2. **Success Metrics** — historical quality, volume, and flow-behaviour trends over a custom date range
3. **Conversation Reasons** — what customers are contacting you about, clustered per flow
4. **Custom Reporting** — configurable analytics with custom date ranges
5. **Scheduled Report** — automated report delivery on a recurring schedule

## Daily Dashboard tab

The Daily Dashboard balances today's accumulating numbers (Today, plus Outbound and Conversation Reasons when there's data) with a live operational pulse (Snapshot, By Channel, Lifecycle, Live Skill Queues, Agent Workload).

### Today (day-to-date)

Cards along the top show what has accumulated since the start of today:

* **Total inbound** — every inbound interaction received today, excluding still-in-progress conversations and auto-transferred calls.
* **AI resolved** — share of today's resolved inbound interactions that the AI fully handled.
* **Human handled** — share that required a human agent.
* **Abandon rate** — share that were abandoned before resolution.
* **Auto transferred** — inbound conversations auto-routed to a human outside the AI flow. Tracked separately and not counted in Total inbound.
* **Routed by DNI list** — inbound callers on the Do-Not-Interact list, routed straight to a human without the AI. A subset of Auto transferred.
* **Average handle time** — mean time from assignment to completion for today's human-handled conversations.
* **Flagged conversations** — share of resolvable inbound conversations flagged for review today.

### Outbound (day-to-date)

When the tenant has placed outbound calls today, an **Outbound** group appears with its own day-to-date cards:

* **Total outbound** — outbound calls placed since the start of today, excluding any still in progress.
* **Human pickups** — share where a human answered (completed, handed off, or abandoned mid-conversation).
* **Voicemails left** — share that left a voicemail after detecting an answering machine.
* **No answer / busy / failed** — share that didn't reach a person and didn't leave voicemail.
* **Flagged conversations** — share of resolvable outbound conversations flagged for review today.

### Conversation Reasons (day-to-date)

A bar chart of what today's conversations were about, shown when reason data has been captured for the day. For historical trends and clustering, use the dedicated **Conversation Reasons** tab.

### Snapshot (live)

Real-time operational status across the whole platform:

* **Total live** — active interactions across AI, queued, assigned, and wrap-up.
* **AI handled rate** — share of live interactions currently handled by AI.
* **Eligible agents** — human agents online and eligible to take interactions.
* **Urgency** — Low / Medium / High based on queued load vs available agents (no queue = Low, no agents = High).
* **Active skill groups** — distinct skill sets across queued and assigned work.

### By Channel

Per-channel cards (Voice, Web Chat, SMS, Email) show Live, Queued, Oldest wait time, and a per-channel urgency badge. Channel urgency thresholds: Voice and Web Chat at 1m/3m, SMS at 5m/15m, Email at 30m/2h (Medium / High respectively).

### Lifecycle

A pipeline visualization of in-flight work: **In AI → Queued → Assigned → Wrap-up**, plus a **Completed (30m)** column showing how many wrapped in the last 30 minutes.

### Live Skill Queues

A queue list filtered by channel — tabs for All, Voice, SMS, Email, and Web Chat. Shows individual conversations waiting for assignment, useful for supervisors managing agent assignment manually.

### Agent Workload

Current work distribution across human agents. Each row shows the agent, their status (Available / Busy / Wrap-up / Offline), and current counts per channel.

## Success Metrics tab

Historical quality and volume trends over a date range you choose. Pick a **Start** and **End** date and, optionally, filter to one or more **Flows**. Figures reflect production conversations only — test conversations are excluded. The tab is organized into three groups:

* **Performance** — a summary KPI row (Total conversations, Resolution rate, Human handoff rate, Avg conversation duration, Routed by DNI list) plus a **Resolution Trends** chart breaking down how finished conversations ended (AI Handle, Escalation, Abandoned, Other, and Auto-transfer).
* **Conversation Volume** — **Total conversations** per day (toggle line/bar), **Inbound** and **Outbound conversations per day** stacked by terminal status, and a **Conversation duration distribution** histogram.
* **Flow Behaviour** — **State Outcomes** (for the most-visited flow states, the eventual outcome of conversations that passed through them) and **Routed by DNI list per day**.

## Conversation Reasons tab

A clustered view of what customers are contacting you about, derived from conversation content. Pick a **flow** and a **time window** to see reasons grouped and visualized, useful for spotting emerging topics or high-volume intents. (The Daily Dashboard's Conversation Reasons chart is the day-to-date snapshot; this tab is the historical, per-flow analysis.)

## Custom Reporting tab

<Frame alt="Custom Reporting tab" />

Use Custom Reporting for deeper analysis and historical trending.

* **Dashboard selector** — pick a reporting template. The **Default Dashboard** comes pre-configured; any custom dashboards saved in your organization also appear here.
* **Start Date / End Date** — pick the analysis window. Useful for week-over-week or month-over-month comparisons, or investigating a specific historical event.
* **Configurable widgets** — once a range is selected, the dashboard populates with line charts, bar charts, pie charts, and tables filterable by channel, skill group, agent, and other dimensions. Most widgets export to CSV.

## Scheduled Report tab

<Frame alt="Scheduled Report tab" />

Set up recurring reports that are delivered automatically, so stakeholders don't have to remember to pull them.

<Steps>
  1. **Click Schedule Report**

     Opens the configuration dialog.

  2. **Configure the report**

     * **Report name** — what shows up in the recipient's inbox.
     * **Template** — pick a pre-built report or any custom dashboard.
     * **Frequency** — daily, weekly, monthly.
     * **Delivery time** — the time of day the report runs.
     * **Recipients** — email addresses.
     * **Format** — PDF, Excel, or email summary.

  3. **Review and edit later**

     Scheduled reports can be viewed, edited, paused, or deleted from the same tab.
</Steps>

## Related

<CardGrid>
  <LinkCard icon="comment" title="Conversations" href="/conversations" description="Search and review individual transcripts." />

  <LinkCard icon="desktop" title="Live View" href="/live-view" description="Real-time monitoring of in-flight conversations." />

  <LinkCard icon="phone" title="Inbox" href="/inbox" description="Take over conversations that need human help." />
</CardGrid>


# Dialpad
Source: https://docs.dialai.ca/dialpad

Connect Dialpad so inbound calls pop the caller's context to the right agent

The **Dialpad integration** connects your Dialpad phone system to Dial AI so your agents have the caller's context the moment a call lands. When a call comes in, Dial AI pops the relevant information to the right person and can pass call details into your flow.

## What it does

* **Screen pop on inbound calls**: when a call arrives, the caller's context pops to the target agent automatically, via Dialpad call-event webhooks.
* **Call context in your flow**: call details are passed through as parameters your flow can use (for example, on call answer).
* **Observe-only mode**: run the integration in a watch-only mode first, so you can confirm it fires correctly before it changes anyone's screen.
* **Allow-list rollout**: gate screen pops to specific users by email, so you can turn it on for a few people and expand when you are ready.

## Rolling it out

<Steps>
  1. **Start in observe-only mode**

     Enable the integration in observe-only so it logs what it would pop without changing any agent's screen. Confirm the events look right.

  2. **Add users to the allow-list**

     Add the target agents by email. Only allow-listed users get screen pops, so you control who is in the pilot.

  3. **Expand**

     Once the pilot looks good, widen the allow-list to the rest of the team.
</Steps>

<Note>Getting Dialpad connected is an account-level setup. Consult your account representative to enable the integration for your tenant.</Note>

***

## Related

<CardGroup>
  <Card title="Points of Contact" icon="phone" href="/points-of-contact">Connect the channels customers reach you on.</Card>
  <Card title="Live View" icon="eye" href="/live-view">Watch calls in real time.</Card>
  <Card title="Conversations" icon="messages" href="/conversations">Review call transcripts and outcomes.</Card>
</CardGroup>


# Document Search
Source: https://docs.dialai.ca/document-search

Ask questions across every document and FAQ indexed in your tenant

<Frame>
  <img alt="Document Search page in light mode" />

  <img alt="Document Search page in dark mode" />
</Frame>

The **Document Search** page lets you ask natural-language questions against every document and FAQ indexed in your tenant. Instead of browsing files by name, you describe what you're looking for and the AI answers with cited sources.

This is the same retrieval that powers your AI agents' answers during conversations — Document Search is just the standalone operator-facing interface to it.

## Accessing Document Search

Navigate to **Docs > Search** in the left sidebar.

## Asking questions

Type a question in the **Ask me anything...** input and press Enter (or click the send button).

A few examples that work well:

* "What's our refund policy?"
* "How do I report a power outage in the Springfield service area?"
* "Summarize the rebate program eligibility rules."

The AI processes your question, retrieves relevant material from the indexed documents and FAQs, and returns a natural-language answer.

## Understanding responses

Each response includes:

* **The answer** — a synthesized natural-language response, formatted with bullets and bold where it improves clarity.
* **Source documents** — a list of the documents that contributed to the answer. Click a document name to open it inline and verify the source.

Clicking a source opens a side-by-side viewer with the chat on the left and the document on the right. The viewer supports tab switching across multiple cited documents, page navigation, and zoom.

## Chat history

The **Chat History** floating button (bottom-right) lists your previous Document Search sessions so you can revisit a prior answer or continue a thread.

## How Document Search relates to flows

Documents you attach to a specific flow under [Flow Documentation](/flow-documentation) are read by the AI agent during conversations. Document Search uses the **whole tenant's index** — every document, regardless of which flows it's attached to, plus every FAQ entry. Use Search when you want to look up something across the entire library; attach documents to flows when you want the agent to use them mid-conversation.

## Tips

* **Be specific.** "What are the technical specifications for the Series 3 unit?" beats "Tell me about the unit."
* **One question at a time.** Multi-part questions sometimes get partial answers — split them into separate queries.
* **Verify against the source.** When accuracy matters, open the cited document and check the original passage.

## Troubleshooting

**Search returns no results.** Confirm the relevant document is indexed (under [Manage Documents](/manage-documents)) and that indexing has completed. New uploads take a few seconds to a few minutes depending on size.

**Answers seem incomplete.** Look at the cited sources — the agent can only answer from what was retrieved. Add a more specific FAQ or attach an additional document.

**The cited document isn't what you expected.** The retrieval is similarity-based; sometimes it picks something tangentially related. Re-phrase the query, or check whether multiple documents cover overlapping ground.

***

## Related

<CardGroup>
  <Card title="Manage documents" icon="folder-open" href="/manage-documents">Add, sync, and delete documents.</Card>
  <Card title="Flow documentation" icon="book-open" href="/flow-documentation">Attach documents to a specific flow.</Card>
  <Card title="FAQ" icon="circle-question" href="/faq">Manage Q\&A pairs.</Card>
</CardGroup>


# AI Email Agent
Source: https://docs.dialai.ca/email-agent

How the AI agent answers inbound email, handles attachments, and hands off to a human CSR

<Frame>
  <img alt="AI email agent answering an inbound email (light mode)" />

  <img alt="AI email agent answering an inbound email (dark mode)" />
</Frame>

The **AI email agent** runs an inbox end to end. It reads inbound mail, replies in a natural thread grounded in your knowledge and flows, handles attachments, and hands off to a human CSR when a conversation needs one. This is the same agent you configure as a [Flow](/flows); this page covers the email-specific behavior.

<Note>Email is now a first-class production channel. Set one up on the Email tab of [Points of Contact](/points-of-contact).</Note>

## What the email agent does

* **Answers inbound email** in a natural, threaded reply, using your knowledge base and flow logic.
* **Handles attachments both ways**: it reads attachments a customer sends and can send agent-drafted files back.
* **Threads correctly**, keeping a conversation together across replies rather than starting fresh each time.
* **Hands off to a human CSR** cleanly when needed, and picks a conversation back up when a CSR hands it back.
* **Routes edge cases to a person** automatically, so odd mail does not get an odd answer.

## Answering email

Inbound mail is matched to a conversation and answered by the flow you assigned to the email [Point of Contact](/points-of-contact). Replies are threaded, so a customer's follow-up continues the same conversation instead of opening a new one. Multi-person threads are kept coherent, and out-of-band human replies (someone on your side replying directly from Outlook) are recorded on the conversation so the agent stays in sync.

## Human handoff

The email agent and your CSRs share the same mailbox, and handoff works by moving a conversation between folders:

<Steps>
  1. **Hand off to a CSR**

     Use **Move to CSR** (or drag the conversation out of the agent's folder). The agent stops answering, the conversation is marked handed off, and the CSR owns it. The assigned flow stays visible on the conversation.

  2. **A CSR takes over**

     The CSR replies as themselves. Threaded replies, attachments, and the ticket subject are all preserved, and the agent will not pick the thread back up while a CSR owns it.

  3. **Hand it back (drag-to-adopt)**

     Drag the conversation back into the agent's folder and the agent adopts it again. Reopen-on-reply also brings a wrapped-up or closed conversation back to life when a new message arrives. Throughout, replies are never dropped or duplicated.
</Steps>

## Routing and guardrails

Not every message should get an AI answer. The email agent routes edge cases to a human and gives you controls to keep it in bounds:

* **Oversized mail**: messages too large for the model are routed to a CSR instead of failing.
* **Ticketless and forwarded mail**: a `Re:` with no matching ticket is held for a CSR rather than answered as a fresh conversation; unowned forwarded mail is answered as a new conversation with the full body.
* **Auto-responder detection**: out-of-office and other auto-replies are detected and skipped. This is tenant-configurable.
* **Do Not Interact (DNI)**: flag certain customers or organizations that always need a human touch. Mark a contact **Do Not Interact** on a channel and the AI stops engaging them on that channel, routing them to a person instead. DNI is **per channel**, so it applies only to the channel you set it on.
* **Suppression list**: keep specific addresses out of the agent's reach entirely.

<Tip>Watch the first real email conversations in [Live View](/live-view) and the [Inbox](/inbox); that is where any routing or handoff tuning surfaces fastest.</Tip>

***

## Related

<CardGroup>
  <Card title="Inbox" icon="inbox" href="/inbox">Where CSRs take over email conversations.</Card>
  <Card title="Conversations" icon="messages" href="/conversations">The searchable archive of every email thread.</Card>
  <Card title="Points of Contact" icon="phone" href="/points-of-contact">Connect a mailbox on the Email tab.</Card>
  <Card title="Manage Documents" icon="book" href="/manage-documents">Ground the agent's answers in your content.</Card>
</CardGroup>


# Email Campaigns
Source: https://docs.dialai.ca/email-campaigns

Send AI-drafted outbound email campaigns to a recipient list

<Frame>
  <img alt="Email Campaign create form in light mode" />

  <img alt="Email Campaign create form in dark mode" />
</Frame>

**Email Campaigns** are outbound mailings sent through one of your configured email Points of Contact. The agent drafts and sends emails using the same flow context your inbound conversations use — useful for follow-ups, announcements, renewals, and re-engagement.

## Accessing Email Campaigns

Navigate to **Outbound > Email Campaigns** in the left sidebar.

## What's on the page

The campaigns table shows every email campaign in the tenant.

| Column | What it shows |
| - | - |
| **ID** | The campaign's unique identifier. |
| **Target Email** | The recipient address (or list summary). |
| **Agent Email** | The configured email POC the campaign sends from. |
| **Status** | Pending / Sent / Failed. |
| **Last Modified** | When the campaign was last touched. |

**Create** in the top-right opens the campaign-creation form.

## Creating a campaign

<Steps>
  <Step title="Click Create">
    Opens the **Create Email Campaign** form.
  </Step>

  <Step title="Pick the Agent Email">
    The dropdown lists every Email Point of Contact configured for your tenant. The chosen address is the **From** for the campaign. Configure email POCs under [Points of Contact > Email](/points-of-contact#email) first if the dropdown is empty.
  </Step>

  <Step title="Enter a Subject">
    The email subject line. Customers see this in their inbox preview, so make it specific and recognizable.
  </Step>

  <Step title="Enter the recipients">
    Paste one email address per line into the **Emails** field. The campaign sends a separate, agent-drafted email to each recipient — recipients don't see each other.
  </Step>

  <Step title="Click Send">
    The campaign appears in the table with a **Pending** status. Each recipient's send transitions to **Sent** on success or **Failed** if delivery doesn't go through.
  </Step>
</Steps>

<Note>The body of each email is composed by the AI agent using your flow's instructions — the campaign form sets the subject and recipient list; the body is generated per recipient. To control body content, edit the flow attached to the sending Email POC.</Note>

## How Email Campaigns relate to Email POCs

An **Email Point of Contact** is the configured `From:` address — it has Microsoft 365 / SendGrid wiring and a flow attached. An **Email Campaign** is a one-shot batch send through that POC to a recipient list. The POC's flow drafts each message; the campaign just provides the recipients and subject line.

This means inbound replies to a campaign land back in the same Email POC's flow — so make sure that flow is configured to handle both initial-send and inbound-reply contexts.

## Multi-channel outreach

Pair email campaigns with [voice campaigns](/outbound):

* **Email first, voice follow-up** — send an opt-in email, then call the recipients who clicked through. Use the customer-journey data on each contact to coordinate.
* **Voice first, email follow-up** — for important calls, send an email summary the next day so the customer has a record.

## Best practices

* **Clear subject lines.** The subject is the only thing the customer reads before opening — make it concrete ("Your March invoice is ready" beats "An update").
* **Test on a single recipient first.** Add one test address before launching a large campaign so you can verify the agent's tone and links.
* **Keep recipient lists scoped.** Send focused campaigns to relevant segments rather than blasting your whole list — better deliverability, fewer unsubscribes.
* **Watch the Status column.** Many recipients stuck in **Pending** longer than expected usually means the sending POC's auth has expired — run a Health Check on the Email POC.
* **Respect compliance rules.** Email marketing regulations vary by jurisdiction. The platform doesn't enforce CAN-SPAM / GDPR / CASL for you — that responsibility is yours.

## Use cases

| Use case | Recipient list source |
| - | - |
| Product announcements | Filtered customer segment |
| Promotional offers | Loyalty-program members, churn-risk contacts |
| Appointment reminders | Today's scheduled appointments |
| Follow-up after a call | Yesterday's transcripts where AI flagged a follow-up |
| Re-engagement | Inactive contacts beyond N days |

***

## Related

<CardGroup>
  <Card title="Outbound voice campaigns" icon="phone-arrow-up-right" href="/outbound">Voice version of the same idea.</Card>
  <Card title="Email POC" icon="envelope" href="/points-of-contact#email">Configure the sending address.</Card>
  <Card title="Flow documentation" icon="book-open" href="/flow-documentation">Attach knowledge the agent uses to draft each email.</Card>
</CardGroup>


# Environment
Source: https://docs.dialai.ca/environment

Manage tenant-scoped environment variables and secrets

<Frame>
  <img alt="Environment workspace in light mode" />

  <img alt="Environment workspace in dark mode" />
</Frame>

The **Environment** workspace is where you view and override the platform configuration values that apply to your tenant — timeouts, allow-lists, integration API keys, and other knobs that change platform behavior without touching a flow. Two tabs: **Environment** (your tenant's overrides) and **Global Manager** (cross-tenant rollouts).

## Accessing Environment

Navigate to **Settings > Environment** in the left sidebar.

## Environment tab

The Environment tab lists every config entry visible to your tenant, grouped by namespace (e.g., `Initializers`, `Javascript`, `OpenAi`, `Speechmatics`).

| Column | What it shows |
| - | - |
| **Key** | Dotted-path name of the entry (e.g., `Initializers.TimeoutSeconds`, `Javascript.AllowedDomains`). |
| **Type** | `Value` for plain config; `Secret` for values pulled from the secret manager. |
| **Source** | Where the current value comes from — `Tenant override` (set here), `Secret Manager` (provisioned externally), or platform default. |
| **Status** | `Configured` once an override is in place. |
| **Value** | The current value. Secrets show as **Hidden**. |
| **Actions** | **Update value** (for plain values) or **Update secret** (for secrets). |

Click the **information** icon next to a key to see its description and accepted format.

### Adding an override

<Steps>
  <Step title="Click Add Override (top right)">
    Opens the override dialog.
  </Step>

  <Step title="Pick the key">
    Choose the variable from the catalog. The catalog lists every variable the platform recognises.
  </Step>

  <Step title="Set the value">
    For plain values, type the new value. For secrets, you'll be prompted to write to the configured secret manager.
  </Step>

  <Step title="Save">
    The override takes effect immediately for new conversations.
  </Step>
</Steps>

<Warning>Changes to integration credentials (e.g., `Speechmatics.ApiKey`, `OpenAi.*`) propagate to live infrastructure on the next request — if the new value is invalid, live conversations will start failing. Validate against a non-production tenant first.</Warning>

## Global Manager tab

The Global Manager applies the same change to multiple tenants at once. Useful for platform-wide rollouts where you don't want to click through tenants individually.

<Steps>
  <Step title="Pick scope">
    Toggle **All** to target every tenant, or turn it off and pick specific tenants from the multi-select.
  </Step>

  <Step title="Pick a key">
    Choose the variable to roll out.
  </Step>

  <Step title="Set the value">
    Enter the new value in the **Action** panel.
  </Step>

  <Step title="Review the per-tenant table">
    The table below shows the current value for each selected tenant — useful for spotting tenants where an override is intentional and shouldn't be clobbered.
  </Step>

  <Step title="Apply">
    Pushes the change to every tenant in scope.
  </Step>
</Steps>

<Note>Global Manager is typically restricted to platform admins. Most tenant operators don't have access — and shouldn't need it.</Note>

## Environment vs flow Variables

Don't confuse this page with [flow Variables](/flow-configuration#variables) (the per-flow knobs on the flow editor's Variables tab):

| Surface | Scope | Who sets it | Used by |
| - | - | - | - |
| **Environment** (this page) | Tenant-wide. | Tenant admins. | Platform infrastructure — timeouts, allow-lists, API keys. |
| **Flow Variables** | One flow. | Flow author. | Function code and prompt templating inside that flow only. |

If a value is shared across multiple flows, it belongs here. If a value is specific to one flow's behavior, it belongs on the flow's Variables tab.

***

## Related

<CardGroup>
  <Card title="Theme" icon="palette" href="/theme-editing">Tenant branding — display name, logos, palette.</Card>
  <Card title="Flow configuration" icon="diagram-project" href="/flow-configuration">Per-flow Variables, Wrap Up, Start Up, and more.</Card>
  <Card title="Permissions" icon="lock" href="/permissions">Roles that can read or modify these values.</Card>
</CardGroup>


# FAQ
Source: https://docs.dialai.ca/faq

Curate the question / answer pairs your AI agents return for common questions

<Frame>
  <img alt="FAQ page in light mode" />

  <img alt="FAQ page in dark mode" />
</Frame>

An **FAQ** is a single question / answer pair the AI agent can return verbatim when a customer asks something close to the question. FAQs complement [Documents](/manage-documents): documents are for long-form reference material, FAQs are for short, definitive answers to questions you've already seen many times.

FAQs are tenant-wide. Once configured, every flow that has FAQs enabled under [Flow Documentation](/flow-documentation) can use them.

## Accessing the FAQ page

Navigate to **Docs > FAQ** in the left sidebar.

## What's on the page

A two-pane layout:

* **Left panel**: the list of every FAQ in your tenant, showing the question and answer for each. New tenants see "No FAQs found. Please create a new FAQ." until the first one is added.
* **Right panel**: the edit panel for the currently selected FAQ. When nothing's selected, it shows "Choose an FAQ — Click an FAQ in the list to edit it."
* **Create** in the top-right opens a new FAQ form.

## Creating an FAQ

<Steps>
  <Step title="Click Create">
    Opens the new-FAQ form.
  </Step>

  <Step title="Write the question">
    The exact phrasing matters less than the meaning — the matcher uses similarity, not literal string match. But the question should be a real question a customer would ask.
  </Step>

  <Step title="Write the answer">
    Keep it tight — 1 to 3 sentences. The agent will paraphrase the answer to fit the conversation, but giving it a short, definitive baseline keeps the responses consistent.
  </Step>

  <Step title="Save">
    The FAQ appears in the list.
  </Step>
</Steps>

## Editing and deleting

* **Edit**: click any row in the list to load it into the right panel. Make changes; save.
* **Delete**: select the FAQ and use the delete action in the edit panel. Confirm.

## How FAQs reach the AI agent

FAQs are only used by flows that have at least one FAQ attached on the Documentation tab of Configure Flow — see [Flow Documentation](/flow-documentation). When a customer's message resembles an FAQ question, the matched FAQ is provided to the agent alongside any retrieved documents.

FAQs also show up in [Document Search](/document-search) results — the standalone search interface treats FAQs and documents as one combined index.

## What makes a good FAQ

* **Concrete.** "What are your business hours?" beats "Tell me about availability."
* **Definitive.** Save FAQs for things with a single right answer. Things that vary by context belong in a thought or a function, not an FAQ.
* **Short.** If the answer needs more than three sentences, it's probably a document, not an FAQ.
* **Singular.** One question per FAQ. Don't combine.
* **Currency.** Stale FAQs are worse than missing ones. Review the list whenever a policy changes.

## When to use FAQs vs documents vs thoughts

| Use | When |
| - | - |
| **FAQ** | Common one-line questions with a definitive answer. |
| **Document** | Reference material the customer might ask many questions about. |
| **Thought** | Process or behavior at a specific state in the flow. |

If you find yourself adding the same FAQ across many flows, the question may belong in a document instead.

***

## Related

<CardGroup>
  <Card title="Manage documents" icon="folder-open" href="/manage-documents">Upload PDFs and sync from S3 / Confluence.</Card>
  <Card title="Flow documentation" icon="book-open" href="/flow-documentation">Attach FAQs to a flow.</Card>
  <Card title="Document search" icon="magnifying-glass" href="/document-search">Search across documents and FAQs together.</Card>
</CardGroup>


# Building Your First Flow
Source: https://docs.dialai.ca/first-flow

Step-by-step guide to creating and configuring your first AI agent flow

Building your first flow on the platform is a straightforward process. This guide will walk you through each step, from creating a new flow to configuring its states and actions.

## Introduction to Flows

Flows are essential to directing your AI agent's conversation with customers. Each flow is composed of **States** and **Transitions** that guide the agent's responses based on customer input. Setting up flows effectively ensures your AI agent can handle various scenarios and provide an optimal customer experience.

***

## Step 1: Creating a New Flow

To start, navigate to **Build > Flows** in the sidebar.

<Frame>
  <img alt="Flows page in light mode" />

  <img alt="Flows page in dark mode" />
</Frame>

1. Click **Create Flow** in the top-right corner.
2. Enter a **Name** and **Description** for your flow. The name should be something descriptive, like "Car Cleaning Appointment Flow," to help identify the flow's purpose.

After you create the flow, it will appear in your list of flows as a card. Now, you can begin adding states and configuring the flow.

***

## Step 2: Configuring Flow Settings

On the new flow's card click **More actions > Configure** — or open the flow editor and click **Configure** in the top-right toolbar.

<Frame>
  <img alt="Configure Flow page in light mode" />

  <img alt="Configure Flow page in dark mode" />
</Frame>

The Configure Flow page has **ten tabs**, each controlling a different aspect of the flow:

* **Description**: Set the Private Name, Public Name, and Description for the flow.
* **Documentation**: Attach reference documents and FAQs, configure query rewriting, and set how much documentation the AI receives per message.
* **Call Review** *(Beta)*: Configure how calls are reviewed and flagged.
* **Call Reasons**: Define the intents the AI may classify a conversation under.
* **Files**: Upload and manage files (PDF, text, HTML, CSV) attached directly to the flow.
* **Agent Memory**: Enable or disable long-term memory so the agent can reference past conversations.
* **Language**: Set the primary language the flow expects from the speaker.
* **Variables**: Set the AI model, streaming behavior, and static parameter values.
* **Start Up**: Select functions that run at the beginning of the workflow (e.g., caller ID lookup).
* **Wrap Up**: Select finalizer functions that run at the end of the conversation (these do not take parameters).

For a complete reference of every field on each tab, see [Flow Configuration](/flow-configuration).

When you're done, click **Save** on each tab to apply your settings.

***

## Step 3: Adding and Editing States

### Creating the Initial State

The **Initial State** is where the flow begins. By default, a flow starts with an "Initial" state that you can edit to define how the agent introduces itself or begins the interaction.

<Frame>
  <img alt="State editor in light mode" />

  <img alt="State editor in dark mode" />
</Frame>

1. Double-click on the **Initial** state node to open the Edit Thought panel.
2. In the **Thought** section, enter the instructions that guide the agent's response. For instance, "Welcome the customer and ask how you can assist with their car cleaning needs." For an in-depth guide on designing thoughts, see [Designing Thoughts](/thoughts).
3. Switch to the **Functions** tab to add any functions (predefined or custom) the agent should perform at this state. For example, if you need the agent to verify customer information, attach a relevant function.
4. Switch to the **Tags** tab to assign tags. Tags help categorize and visually group states in the flow.

When you're finished, click **Save** to finalize the state.

***

## Step 4: Adding More States

Each additional state lets you structure the conversation further, guiding the agent based on customer responses.

<Frame>
  <img alt="Flow editor in light mode" />

  <img alt="Flow editor in dark mode" />
</Frame>

1. Click **Add State** in the top-right toolbar.
2. Name the state descriptively (e.g., "Confirm Appointment" or "Provide Pricing").
3. Double-click the new state to open the Edit Thought panel and fill in its **Thought**, **Functions**, and **Tags**.
4. To delete a state, select it and press Delete.

Each state should represent a clear step in the conversation, directing the agent on what to say, ask, or do based on the conversation context.

***

## Step 5: Connecting States with Transitions

Transitions between states are controlled by **Events**. Events are triggered by function calls. When an event is triggered, the flow moves to the next state based on the event's conditions.

1. Drag a line from one state to another to create a transition.
2. A dialog will appear to configure the event that triggers the transition. The options are limited to possible events output by the functions of the upstream state.

For example, if the customer confirms their address, that function will emit the 'Address Verified' event that then triggers a transition to the "Verify Appointment Details" state.

***

## Step 6: Testing the Flow

Testing is crucial to ensuring your flow behaves as expected. To test:

1. From the **Flows** page, click **Test** on the flow card.
2. Choose the channel you want to emulate — Voice, Web, SMS, Email, or Advanced.
3. Begin typing responses as if you were the customer to verify that the agent follows the flow correctly.

During testing, watch for:

* **Accurate transitions** — the flow moves to the correct next state for each customer response.
* **Proper function execution** — every function attached to a state fires when expected with the right inputs.
* **Response clarity** — the agent's language is clear, on-brand, and aligned with your thoughts.

For deeper testing including recorded Test Scenarios you can replay across versions, see [Testing Flows](/testing-flows).

***

## Step 7: Publish the Flow

Publishing creates an immutable version of the flow that Points of Contact can reference, so editing the draft never disrupts production.

1. Click the **Publish** button in the top-right of the flow editor.
2. Give the version a title and description.
3. After publish, the **Versions** menu on the flow card shows both Current Draft and the new published version.

***

## Step 8: Deploying the Flow

To deploy the flow, you will need to configure a Point-Of-Contact (POC) that connects the flow to a communication channel like Voice, SMS, or Web.
Here, you can choose the published version of the flow you wish to deploy.

Check out our guide on [Creating a Point of Contact](/points-of-contact) for detailed instructions on setting up a POC for your flow.

***

## Key Concepts Reference

### States

* **Definition**: A point in the conversation where the AI agent performs actions or gives responses.
* **Configuration**: Set the **Thoughts** (instructions) and **Functions** (actions) to guide the agent’s responses at each stage.

### Functions

* **Purpose**: Functions allow the AI to perform tasks like data retrieval or notifications.
* **Customization**: Users can create custom functions via webhooks, defining them on external servers.

### Parameters

* **Types**: Normal parameters (passed to functions) and internal parameters (set by functions).
* **Usage**: Used to maintain data consistency across the flow and perform specific tasks based on the conversation.

### Events

* **Definition**: Triggers that determine when the conversation moves from one state to another.
* **Example**: An event could move the flow from "Confirm Address" to "Confirm Appointment" once the address is verified.

By following this guide, you can set up a flow that effectively manages customer interactions. Building flows with well-defined states, functions, and events will help your AI agent provide consistent and valuable support across various customer scenarios.


# Flow Configuration
Source: https://docs.dialai.ca/flow-configuration

Complete reference for configuring AI conversation flows — every tab, every field

<Frame>
  <img alt="Configure Flow page in light mode" />

  <img alt="Configure Flow page in dark mode" />
</Frame>

The **Configure Flow** page is the central place to set up every aspect of a flow. It is organized into **ten tabs**, each controlling a different dimension of how your AI agent behaves during conversations.

## Accessing the Configuration Page

1. Navigate to **Build > Flows**.
2. On the flow card, click **More actions > Configure** — or open the flow editor and click **Configure** in the top-right toolbar.

The page header reads **Configure Flow — Set up each section of this flow in one place**. An **Organize Flow** link in the top-right corner returns you to the flow diagram editor.

***

## Tab 1: Description

Set the names and description people see for this flow across your workspace.

### Fields

* **Private Name**: The internal name displayed within the platform. Keep this clear for internal teams.
* **Public Name**: The name displayed to customers in external-facing contexts.
* **Description**: A text area to explain what the flow does. Use the description to give context to team members.

### Tips

* Keep the private name clear for internal teams.
* Use public name and description for external contexts.
* Save updates before moving to another section.

***

## Tab 2: Documentation

Choose what knowledge this flow uses and how strongly it relies on that content. This tab controls the reference materials available to the AI during conversations.

### Fields

* **Amount of Documentation**: A slider (0–10) that controls how many documentation and FAQ segments are given to the AI after each customer message. Higher values provide richer context; lower values keep responses faster and more focused.
* **Enable Query Rewriting**: A toggle that enables the query rewriting agent to improve document search in all non-voice conversations. Useful when customers phrase questions differently from how documentation is written.
* **Query Rewriter Context**: A text area for additional information the query rewriter should use to improve search results (e.g., industry-specific terminology, synonyms, or common customer phrasing).
* **Documents**: The documents the AI should have access to during the conversation. Click **+ Create New** to attach documents from your organization's document library.
* **Frequently Asked Questions**: The FAQs the agent should reference during conversations. Click **+ Create New** to attach FAQ sets.

### Tips

* Attach the right documents and FAQs for this flow.
* Tune how much reference content is used per response.
* Enable query rewriting only when you need stronger search.

For a detailed guide on documentation configuration, see [Flow Documentation](/flow-documentation).

***

## Tab 3: Call Review *(Beta)*

Control how calls are reviewed and when follow-up flagging should happen.

### Fields

* **Standard behavior (already included)**: A read-only text area showing the built-in review behavior. This standard behavior updates automatically and decides whether a call was successful, marks it for follow-up when issues are detected (e.g., frustrated customers, conversation loops, system errors), and writes a plain-language review.
* **Enable extra guidance**: A toggle to add team-specific review instructions on top of the standard behavior. When off, only the standard behavior is used.

### Tips

* Read the standard behavior first.
* Add short team-specific guidance only if needed.
* Changes affect future call reviews only.

***

## Tab 4: Call Reasons

Define the call reasons the AI may classify a conversation under. Each reason becomes a tag that's set on conversations matching it, making it easy to slice analytics by intent.

### Fields

* **Reasons**: A list of call reasons. Each reason has a name and a short description that tells the AI when to apply it. Add new reasons as your call mix evolves; retire reasons that are no longer useful.

### Tips

* Keep reasons mutually exclusive — overlapping reasons make analytics ambiguous.
* Keep the list focused; too many reasons slow the AI's classification and dilute the data.
* Update reason descriptions when you notice the AI consistently mis-classifying.

***

## Tab 5: Files

Manage files attached directly to this flow for retrieval and downstream processing.

### Fields

* **Upload Files**: A drag-and-drop area (or "Choose a file" button) to upload files. Supported formats: **PDF, text, HTML, and CSV**.
* **Attached Files**: A list of files currently attached to the flow, with a count of total files.

### Tips

* Upload only files this flow should own directly.
* Remove outdated attachments so agents use current content.
* Confirm downloads and retrieval behavior after file changes.

***

## Tab 6: Agent Memory

Choose whether this flow can use past conversation context while responding.

### Fields

* **Enable Long Term Memory**: A toggle that gives the agent access to past conversations with a customer. When enabled, the agent can reference previous interactions for continuity across contacts.

### Tips

* Turn memory on to improve continuity across contacts.
* Turn memory off when each conversation should stand alone.
* Save before testing behavior changes.

***

## Tab 7: Language

Set the primary language this flow expects from the speaker.

### Fields

* **Speaker Language**: A dropdown to select the expected language. Options include a wide range of languages and regional variants, such as: Multilingual, Bulgarian, Catalan, Chinese (Mandarin Simplified/Traditional), Chinese (Cantonese Traditional), Czech, Danish, Dutch, English (generic, US, Australia, UK, New Zealand, India), Estonian, Finnish, and many more.

### Tips

* Pick the language that best matches your callers.
* Use one default language per flow for consistency.
* Update this if your team handles a new audience.

***

## Tab 8: Variables

Configure core runtime settings for this flow, including model and static parameters.

### Fields

* **Model**: A dropdown to select the AI model type used in the flow (e.g., "Basic"). Model configuration is applied when the flow is published.
* **Enable Streaming**: A toggle that controls how AI messages are delivered. When enabled, messages stream into the chat area word by word. When disabled, full messages appear all at once. This setting is applied when the flow is published.
* **Static Parameters**: Any parameters defined as "static" in the flow's parameter configuration appear here. Each shows:
  * **Parameter Name** (e.g., TwilioAuthToken, TwilioAccountSid)
  * **How to get the parameter**: A dropdown (String, Secret, etc.)
  * **The literal value to use**: A text field for the value. Secret values are masked.

### Tips

* Choose model and streaming behavior for response style. These settings take effect on the published flow.
* Review static parameter values for each environment.

***

## Tab 9: Start Up

Select the functions that should run when this flow starts.

### Fields

* **Startup Functions**: A list of functions that run at the beginning of the workflow. Functions can be selected from existing functions or created new with the **+ Create New** button. Each function can be removed with the **×** button.

### Tips

* Use startup functions to prepare required context (e.g., checking caller ID).
* Keep this list focused on essential setup actions.
* Re-test flow startup after function changes.

***

## Tab 10: Wrap Up

Select the functions that should run when this flow finishes.

### Fields

* **Wrap Up Functions**: Functions called at the end of a conversation. These functions do not take in parameters. Select from existing functions or create new ones with the **+ Create New** button.

### Tips

* Use wrap-up functions for final logging or handoff work.
* Keep only functions that should always run at the end.
* Save and test to confirm end-of-call behavior.

***

## See Also

* [Flows](/flows) — Overview of flow creation and management
* [Building Your First Flow](/first-flow) — Step-by-step flow creation guide
* [Flow Documentation](/flow-documentation) — Deep dive into the Documentation tab
* [Functions and Events](/functions-and-events) — Reference material for functions
* [Agents](/agents) — Agent configuration

***

*The Configure Flow page gives you centralized control over every aspect of your AI agent's behavior — from what it knows, to how it reviews calls, to what happens at the start and end of every conversation.*


# Flow Documentation
Source: https://docs.dialai.ca/flow-documentation

Give your AI agent the knowledge it needs to answer customer questions accurately

The **Documentation** tab on Configure Flow controls what reference material your AI agent can search during a conversation. Attach documents, FAQs, and search-tuning configuration so the agent answers from your sources of truth instead of inventing answers.

This page is the deep dive on the Documentation tab. For the rest of the configuration tabs, see [Flow Configuration](/flow-configuration).

## Accessing the Documentation tab

1. Navigate to **Build > Flows**.
2. Open the flow you want to configure.
3. Click **Configure** in the top-right.
4. Select the **Documentation** tab.

<Note>The Documentation tab is one of nine tabs on the [Configure Flow](/flow-configuration) page.</Note>

## Fields

### Amount of Documentation

A slider (0–10) that controls how much documentation and FAQ content is provided to the AI after each customer message.

* **Default**: 5.
* **Higher values**: more documentation segments are included with each response. Richer context, slower responses, more tokens.
* **Lower values**: fewer segments. Faster responses, tighter context, agent may miss information that's actually relevant.

Start at 5 and tune from there based on how often the agent says "I don't know" for questions that *are* in your documentation.

### Enable Query Rewriting

A toggle that activates the query rewriting agent for non-voice conversations. The rewriter turns each customer message into a search query optimized for finding relevant documents, even when the customer's phrasing doesn't match how the documents are written.

Enable when your customers and documentation use different vocabularies. Example: documentation says "Energy Rebate Program"; customers say "discount on power bill". Query rewriting bridges that gap.

Note: query rewriting adds latency to document retrieval. Leave it off when responses need to be fastest and your customer/document vocabularies already match.

### Query Rewriter Context

A free-form text area for hints to the query rewriter — industry-specific terminology, synonyms, common customer phrasing variations, abbreviations.

Example:

> Customers refer to "solar panels" as "PV systems" or "sun panels". "Rebate programs" include both federal and state incentives. Customers often say "my bill" when they mean monthly invoice.

### Documents

The reference documents the agent can search. Click **+ Create New** to attach documents from your organization's document library.

* Documents are managed under [Manage Documents](/manage-documents). You can upload files directly or sync from S3 / Confluence.
* Multiple documents can be attached; the agent searches across all of them.
* Attached documents are indexed once; updates to a document re-index automatically.

### Frequently Asked Questions (FAQs)

Pre-configured question/answer pairs the agent should reference. FAQs are managed under [FAQ](/faq).

* Click **+ Create New** to attach FAQ sets.
* When the agent decides a customer message is similar to an FAQ question, the FAQ answer is provided alongside any retrieved documents.
* FAQs are best for short, definitive answers to common questions. For longer policy or procedure documents, use Documents instead.

## Workflow

<Steps>
  <Step title="Inventory your reference material">
    Collect every document, guide, policy, and procedure relevant to the flow you're configuring. Identify which questions come up often enough to deserve an FAQ.
  </Step>

  <Step title="Upload documents and create FAQs">
    Add documents under **Docs > Manage**. Create FAQ pairs under **Docs > FAQ**.
  </Step>

  <Step title="Attach to the flow">
    Open the flow's Documentation tab. Attach the relevant documents and FAQs. Set the Amount of Documentation slider to 5 to start.
  </Step>

  <Step title="Tune query rewriting">
    If your customers use vocabulary that differs from your documents, enable Query Rewriting and add a Query Rewriter Context that lists the common synonyms.
  </Step>

  <Step title="Test">
    Run a test conversation (see [Testing Flows](/testing-flows)) and ask questions that should be answered from your documentation. If the agent says "I don't know" for things that are in your docs, increase the Amount of Documentation slider or expand your Query Rewriter Context.
  </Step>
</Steps>

## Best practices

**Keep documents current.** Stale documents are worse than no documents — the agent will confidently quote outdated policy. Set a review cadence.

**Prefer concise documents to monolithic PDFs.** Smaller, focused documents retrieve more accurately. A 200-page handbook is a worst-case for retrieval; ten 20-page sections are much better.

**Use FAQs for one-line answers.** "What are your hours?" → FAQ. "How do I file a claim?" → Document.

**Test before you ship.** Every change to the Documentation tab can change agent behavior. Walk through a few realistic conversations after each change.

## Troubleshooting

### The agent isn't finding documents it should

* Enable Query Rewriting if it isn't already on.
* Expand Query Rewriter Context with the customer phrasings you're seeing.
* Confirm the document is actually attached (not just uploaded to the library).
* Increase the Amount of Documentation slider.

### Response times are slow

* Lower the Amount of Documentation slider.
* Split very large documents into smaller, focused pieces.
* Disable Query Rewriting temporarily to isolate the latency source.

### Answers are inconsistent

* Look for duplicate or conflicting documents — both can be returned by retrieval.
* Verify FAQ answers are clear and don't contradict the attached documents.
* Check that the Query Rewriter Context isn't subtly misleading the rewriter.

***

## Related

<CardGroup>
  <Card title="Flow configuration" icon="sliders" href="/flow-configuration">Every Configure Flow tab.</Card>
  <Card title="Manage documents" icon="folder-open" href="/manage-documents">Upload, sync from S3/Confluence, and organize source material.</Card>
  <Card title="FAQ" icon="circle-question" href="/faq">Manage Q\&A pairs.</Card>
  <Card title="Document search" icon="magnifying-glass" href="/document-search">Search across attached documents.</Card>
</CardGroup>


# Flows
Source: https://docs.dialai.ca/flows

Create, manage, test, and publish AI conversation flows

<Frame>
  <img alt="Flows page in light mode" />

  <img alt="Flows page in dark mode" />
</Frame>

The **Flows** page is your hub for AI conversations. Every customer-facing flow your tenant owns is here as a card — open it, edit it, test it on any channel, or publish a new version.

## Accessing the Flows page

Navigate to **Build > Flows** in the left sidebar.

## What's on a flow card

Each card represents one flow and shows:

* The flow's **name** and an auto-generated **thumbnail**.
* Whether the latest version is **Draft** or **Published**.
* The **last edited** timestamp.
* The **Points of Contact** linked to this flow, with quick links to each.

Four action buttons live on every card:

| Button | What it does |
| - | - |
| **Edit** | Open the flow editor — the visual canvas of states and transitions. |
| **Test** | Pop a menu to test the flow on a specific channel (Voice, Web, SMS, Email, or Advanced). |
| **Versions** | Switch between the current draft and any published versions. |
| **More actions** | Configure, Export, Generate AI Image, Duplicate, Delete. |

## Test menu

The **Test** menu lets you run a real-time conversation against the flow without involving a real customer or channel.

<Frame>
  <img alt="Test menu options" />

  <img alt="Test menu options" />
</Frame>

* **Voice** — simulates a phone call. Use spaced letters (e.g., `B r i a n`) to imitate the customer spelling something out, just like over a real voice line.
* **Web** — runs the flow as a web chat session with the same UI a customer would see.
* **SMS** — short, single-message turns.
* **Email** — async, formatted-body conversation.
* **Advanced** — opens a configurable test interface with platform-specific parameters.

For deeper testing — including recorded scenarios you can replay against future versions — see [Testing Flows](/testing-flows).

## More actions menu

<Frame>
  <img alt="More actions menu in light mode" />

  <img alt="More actions menu in dark mode" />
</Frame>

* **Configure** — open the Configure Flow page. See [Flow Configuration](/flow-configuration) for the full reference of every tab.
* **Export** — download the flow as a portable JSON file.
* **Generate AI Image** — re-roll the auto-generated thumbnail.
* **Delete** — irreversibly remove the flow. Disabled if any POC still references it.
* **Duplicate Flow** — make a copy. Useful for testing experimental changes against a known baseline.

## Importing a flow

The **Import** link in the top-right brings in a flow exported from this or another Dial AI workspace.

<Steps>
  <Step title="Click Import">
    Opens the import dialog.
  </Step>

  <Step title="Pick the exported file">
    Drag-and-drop or **Upload a file**. Only files exported from a Dial AI instance work — hand-edited JSON is unsupported and will likely fail validation.
  </Step>

  <Step title="Upload">
    The flow appears in your grid as a fresh draft. Open it to confirm states, transitions, and function references resolved correctly.
  </Step>
</Steps>

## Filtering

Click **Filter** in the top-right to open a sidebar that lets you narrow the visible flows by name. Useful when your tenant has tens of flows and you want to find one quickly.

## Creating a new flow

Click **Create Flow** in the top-right. You'll land on the new-flow form to set the private/public name and description. After save, the flow opens in the editor with a single **Initial** state, ready for you to fill in.

For a step-by-step walkthrough, see [Building Your First Flow](/first-flow).

## Tips

* Keep flow private names clear for internal teams; reserve the public name for customer-visible contexts (auto-generated emails, voice greetings).
* Use **Duplicate Flow** before any large structural change — gives you a known-good rollback point.
* Spelling/phonetic accuracy matters most on voice calls: when testing Voice, watch for the AI agent reading numbers digit-by-digit and spelling names letter-by-letter where appropriate.

***

## Related

<CardGroup>
  <Card title="Build your first flow" icon="pen-to-square" href="/first-flow">Step-by-step guide for a brand new flow.</Card>
  <Card title="Flow configuration" icon="sliders" href="/flow-configuration">Every Configure Flow tab.</Card>
  <Card title="Testing flows" icon="flask" href="/testing-flows">Test Platform, Test Scenarios, and version-aware regression checks.</Card>
  <Card title="Points of contact" icon="phone" href="/points-of-contact">Wire a flow to a channel.</Card>
</CardGroup>


# Functions and Events
Source: https://docs.dialai.ca/functions-and-events

Give your AI agent the power to take actions and branch the conversation

**Functions** are the way an AI agent reaches outside its own conversation — to look up account data, push an update to your CRM, send a notification, or anything else. **Events** are the signals that functions emit to drive state transitions inside a flow.

Together, functions and events are how a flow goes from "an LLM talking to a customer" to "an LLM that gets things done and routes intelligently between its own states".

## Where functions live

Functions are managed under **Build > Functions**. From there you can:

* List existing functions, filter by tag or integration.
* Create a new function (either a JavaScript-backed function or an integration-typed one).
* Open an individual function to edit its source, parameters, declared events, and tests.
* View **Snapshots** — published versions of a function used by published flows.

To make a function available to the agent at a specific state, open the flow editor, select the state, and add the function under the **Functions** tab.

<Note>Functions remain available even after the conversation has left the state that introduced them. If a state needs a function, attach it there; once it's been seen, it can be called again later in the conversation.</Note>

## Creating a function

From the Functions page, click **Create**. You'll land on the function editor, where you configure:

* **Name** and **description** — what the agent sees when deciding whether to call this function.
* **Inputs** — three kinds (see below).
* **Outputs** — the response shape, declared events, and declared context additions.
* **Source code** — JavaScript that runs when the function is called.

### Inputs

A function can take three kinds of input:

**Parameters** are values the agent collects from the customer and passes in at call time. For a `Lookup Account by Phone` function, the agent would supply the phone number as a parameter.

**Internal parameters** (also called context parameters) come from the conversation's context — set by a previous function, by the runtime, or by the platform. Common examples: the customer's contact ID, parameters set by a Caller ID Lookup that runs at startup.

**Static parameters** are configured per-flow under **Configure Flow > Variables**. Use them for API keys, base URLs, environment-specific toggles, and anything else that doesn't change mid-conversation.

### Outputs

A function returns a single JSON object with up to three keys:

**`response`** is what the agent sees as the result of the call. This is the natural place for human-readable data the agent will use in its next reply.

**`contextAdditions`** is a set of key/value pairs added to the conversation's context. Later functions can read these as internal parameters. Use this for data you want available later but don't want the agent reasoning over directly.

<Tip>Declare every key you might add under **Emitted Context Additions** on the function editor. The flow editor uses these declarations to offer suggestions, and a warning fires when a function emits an undeclared key.</Tip>

**`event`** is the name of an event this call emits. A function may emit at most one event per call. Events are what drive state transitions — see the Events section below.

<Tip>Declare every event a function may emit under **Emitted Events**. Like context additions, declared events power suggestions and undeclared-event warnings.</Tip>

### Source code

The function body is plain JavaScript with a small set of helpers available (HTTP fetch, logging, JSON parsing, etc.). The full helper reference is available via the info icon in the function editor.

## Events

An **Event** is a named signal that drives a state transition. The flow says "from state A, on event `AccountFound`, go to state B". The function says "I emit `AccountFound` when…".

Events are how flows branch. A `Lookup Account` function might emit:

* `AccountFound` — proceed to confirm details.
* `MultipleAccounts` — present a disambiguation step.
* `NoAccountMatch` — collect more info or escalate.

Each of these can drive a different next state. The same function, different branches.

<Note>Events are not visible to the AI agent. They drive routing only — the agent reads the `response`, the runtime reads the `event`.</Note>

## Designing functions

Functions don't always need to "do something." Sometimes the most useful function is one that simply emits an event to move the conversation into a new state with new instructions.

Example: a flow handles billing inquiries with complex eligibility rules. Rather than cramming every rule into the initial state's thought, define a `Start Billing Process` function that emits a `BillingStarted` event. The flow transitions to a dedicated billing state with a focused thought and a tighter set of functions. The agent stays in scope; the thoughts stay readable.

## When to use each input type

| Use… | When the value… |
| - | - |
| Normal parameter | Comes from the customer in this turn (account number, address, requested date). |
| Internal parameter | Was set by an earlier function or the platform (contact ID, caller ID lookup result). |
| Static parameter | Is the same for every conversation in this flow (API key, base URL, integration ID). |

## Testing a function

The function editor has a built-in test panel:

1. Fill the **Test parameters** form. To pre-populate values from a flow, click **Populate from flow** and pick a target flow.
2. Click **Run test**.
3. The panel shows the function's response, any context additions, and the emitted event.

For functions used by saved flows, you can also use **Test saved function** which reuses the function's snapshot version exactly as the published flow uses it.

## Function snapshots

When you publish a flow, the platform freezes the exact function source used by that flow as a **snapshot**. This means changes to a function don't accidentally break a published flow — the published version keeps running the source it was published with. To pick up new function code in production, re-publish the flow.

Snapshots are listed under **Build > Functions > \[Function]**.

***

## Related

<CardGroup>
  <Card title="Designing thoughts" icon="lightbulb" href="/thoughts">Write the instructions that decide when to call your functions.</Card>
  <Card title="Flow configuration" icon="sliders" href="/flow-configuration">Configure start-up and wrap-up functions and static parameters.</Card>
  <Card title="Building blocks" icon="cubes" href="/building-blocks">Manage parameters and tags shared across flows.</Card>
</CardGroup>


# iframe Integration (Legacy)
Source: https://docs.dialai.ca/iframe-integration

Embed a Dial AI chat session inside your existing web application using an HTML iframe

<Warning>
  This page describes the legacy web chat: a chat link from the **Web (Legacy)** tab of **Points of Contact**, in an iframe. For a new site, use [Web Widgets](/web-widgets). Chat links still work for now, but they are deprecated. This page stays for sites that use a chat link today.
</Warning>

<Frame>
  <img alt="Web POC Edit tab in light mode" />

  <img alt="Web POC Edit tab in dark mode" />
</Frame>

Dial AI chat links can be embedded in any web application via a standard HTML `<iframe>`. Use this when you want the AI agent to live inside an existing site — customer portal, support page, in-app help — without leaving the surrounding context.

If you want a floating chat button that pops a modal instead of embedding inline, see [Script Tag Integration](/script-tag-integration). For backend-driven flows that bypass the embedded widget entirely, see [API Integration](/api-integration).

## Creating a chat link

A **chat link** is a UUID-keyed Web [Point of Contact](/points-of-contact#web-legacy). Create one and you can embed it anywhere.

<Steps>
  <Step title="Open Points of Contact">
    Navigate to **Agent > Points of Contact > Web (Legacy)**.
  </Step>

  <Step title="Click Create Point of Contact">
    Pick **Web** as the channel type. Fill in a friendly name and select the flow you want this chat link to run.
  </Step>

  <Step title="Save and open the link">
    The new link appears in the Web POC table. Click the edit (pencil) icon to open the configuration panel.
  </Step>
</Steps>

### Configuring the link

The Edit tab controls what the chat link does:

* **The Code** — the UUID that uniquely identifies the link. Use this in your embed URL.
* **Link Name** — a human-readable label that shows up in transcripts and the conversations list.
* **Draft Flow** — the flow this chat link runs.
* **Version** — pin to a specific published flow version. Leave empty to track the draft live.
* **Voice** — synthetic voice for any audio-mode conversations on this link.
* **Settable Internal Parameters** — keys the client is allowed to set when starting a chat (e.g. UI preferences).
* **Extra Internal Parameters** — keys baked into every chat created via this link. The client cannot override these.

<Note>For passing trusted user identity (e.g. a verified `userId`) into the chat, see [Passing Context Securely](/integration-context). Never put trusted values in Settable Internal Parameters — those are client-controlled.</Note>

## Generating the embed link

<Frame>
  <img alt="Web POC Generate tab in light mode" />

  <img alt="Web POC Generate tab in dark mode" />
</Frame>

The **Generate** tab produces the live URL you embed. Configure:

* **Override Theme** — `Dynamic` (follows the visitor's browser theme) or fixed Light/Dark.
* **Disable Logos** — hide tenant branding for white-label embeds.
* **Fast Launch Chat** — open the chat immediately on page load instead of waiting for the visitor to click.
* **Extra Context Params** — query-string parameters appended to the URL. Used by start-up functions to look up information before the first turn. Only useful when paired with **Settable Internal Parameters** on the Edit tab.

The **Link** field at the bottom is the final embed URL. Copy it.

## Embedding the chat link

The simplest embed is a fixed-size iframe:

```html theme={null}
<iframe
  src="https://your-instance.dialai.ca/your-tenant/chat/00000000-0000-0000-0000-000000000000"
  width="1000"
  height="1000"
></iframe>
```

Replace the URL with the one from the Generate tab, and adjust width/height to fit your page.

### Toggling on a button click

For a "click to open chat" pattern, mount/unmount the iframe on demand. Chat context is preserved between iframe reloads as long as the visitor's session cookie is intact.

```js theme={null}
document.getElementById("toggle-chat").addEventListener("click", () => {
  const id = "dial-ai-chat";
  const existing = document.getElementById(id);
  if (existing) {
    existing.remove();
    return;
  }
  const iframe = document.createElement("iframe");
  iframe.id = id;
  iframe.src = "https://your-instance.dialai.ca/your-tenant/chat/00000000-0000-0000-0000-000000000000";
  iframe.width = "500";
  iframe.height = "500";
  document.getElementById("root").append(iframe);
});
```

## iframe vs script tag

| Use iframe when… | Use [script tag](/script-tag-integration) when… |
| - | - |
| You want chat embedded inline in your layout. | You want a floating button + modal. |
| You're OK with iframe-sandbox limitations. | You want native styling and a smaller bundle footprint. |
| You're embedding inside another iframe-friendly host. | You're embedding inside a SPA where DOM control is straightforward. |

## CSP and X-Frame-Options

The chat URL ships with a `Content-Security-Policy-Report-Only` header that allows `frame-ancestors 'self' https://*.hansencx.com`. The report-only policy means the platform logs violations but doesn't block — if your embed origin is outside the allow-list you'll see violation reports in browser dev tools, not a blocked iframe. If you need your embed origin allowed in an enforced policy, contact your account representative to extend the platform's CSP.

Your embedding page does not need any special headers unless your own CSP restricts iframe sources — in that case, allow `https://your-instance.dialai.ca` in your page's `frame-src` directive.

## Tips

* **Use a stable Version** when embedding into production. Tracking the draft means the chat behavior can change at any time without you knowing.
* **Set Link Name** before you copy the URL. It shows up in [Conversations](/conversations) and makes it much easier to attribute traffic.
* **Test the embed on a staging URL** before production — some browsers and corporate firewalls block third-party iframes even when CSP allows them.

***

## Related

<CardGroup>
  <Card title="Web Widgets" icon="comment" href="/web-widgets">The new way to put chat on a website.</Card>
  <Card title="Script tag integration" icon="window" href="/script-tag-integration">Floating button + modal instead of inline iframe.</Card>
  <Card title="API integration" icon="code" href="/api-integration">Skip the widget entirely and use the REST API.</Card>
  <Card title="Passing context securely" icon="shield" href="/integration-context">How to pass verified user identity into the chat.</Card>
  <Card title="Points of Contact: Web (Legacy)" icon="phone" href="/points-of-contact#web-legacy">Manage legacy web chats.</Card>
</CardGroup>


# Inbox
Source: https://docs.dialai.ca/inbox

Monitor and take over conversations that need human handling

<Frame>
  <img alt="Inbox in light mode" />

  <img alt="Inbox in dark mode" />
</Frame>

The **Inbox** is built for human agents who handle conversations the AI can't (or shouldn't) resolve on its own. When a conversation is queued for human help — by the AI itself, by a supervisor, or by a routing rule — it shows up here, waiting for a human to pick it up.

Pair the Inbox with [Live View](/live-view) for real-time monitoring of AI-handled conversations, and with [Conversations](/conversations) for the searchable archive after a conversation closes.

## Accessing the Inbox

Navigate to **Monitor > Inbox** in the left sidebar.

There are two views:

* **Inbox** (default) — every conversation in your queue, routed by skill match.
* **Inbox / Personal** — a configurable per-agent view. Set this up under **Configure Inbox** in the top bar.

## Audio configuration (Agent Leg status)

The top-left of the Inbox shows your **Agent Leg** indicator — your audio connection's readiness for voice calls.

* **Connected** — you're ready to receive voice calls.
* **Disconnected** — click to reconnect. The system uses your configured phone number from **Settings > Personal Configuration**, or opens a modal to set up web audio with your headset.
* **Ringing** — a queued voice call is being routed to you.

For chat and email conversations, no audio leg is needed.

## Status management

Use the **Status** dropdown in the top bar to control your availability:

* **Available** — eligible for new conversations.
* **Busy** or **Offline** — conversations won't route to you. Skill-based conversations that are already assigned to you are returned to the queue for reassignment; conversations that were routed directly to you (agent-specific) remain assigned and are not re-routed.

## How a conversation reaches you

<Steps>
  <Step title="The AI queues it">
    The AI agent decides it needs human help — based on the flow logic, the customer's request, or a function call — and queues the conversation with one or more **Skills** describing what's needed (e.g., Billing, Spanish, Fraud Assistance). Skills are managed under **Settings > Operations > Skills**.
  </Step>

  <Step title="The ACD routes it">
    The Automatic Call Distributor picks an **Available** agent whose configured skills match. Chat and email caps can be adjusted from the Inbox top bar or under **Settings > Personal Configuration**. Voice calls are capped at one per agent at a time and cannot be changed.
  </Step>

  <Step title="You accept or reject">
    When a conversation is routed to you, you can **Accept** it to take it on, or **Reject** it back into the ACD for reassignment.
  </Step>
</Steps>

## Taking over

* **Voice calls** — your phone or headset rings (per your selected audio method). Answer to take control.
* **Chats / emails** — open directly inside the Inbox for real-time messaging.

The conversation panel shows the full context: the transcript so far, sentiment, the flow the AI was running, and any parameters the AI captured before handing off.

## Ending a conversation

After you resolve the issue:

1. **Hang up** (voice) or click **End** (chat/email).
2. The conversation enters a **Wrap-up** state for any final notes.
3. Once wrap-up closes, you're eligible for new conversations again.

***

## Related

<CardGroup>
  <Card title="Live View" icon="eye" href="/live-view">Watch AI-handled conversations in real time.</Card>
  <Card title="Conversations" icon="messages" href="/conversations">Search past conversations.</Card>
  <Card title="Skills" icon="user-tag" href="/operations#skills">Define and manage routing skills.</Card>
  <Card title="Personal configuration" icon="user-gear" href="/personal-configuration">Set your phone, status, and skill assignments.</Card>
</CardGroup>


# Passing Context Securely
Source: https://docs.dialai.ca/integration-context

How to pass user identity and other context into chat sessions without allowing impersonation.

<Warning>
  This page describes how to pass context into the legacy web chat: chat links from the **Web (Legacy)** tab of **Points of Contact**, with the [iframe](/iframe-integration) or the [script tag](/script-tag-integration). Chat links still work for now, but they are deprecated. For a new site, use [Web Widgets](/web-widgets) with [signed-in visitors](/web-widget-sign-in).
</Warning>

## Signed-in visitors replace these approaches

A web widget with sign-in replaces all three approaches on this page:

| Approach on this page | With a web widget |
| - | - |
| [External JWT with public key verification](#approach-1-external-jwt-with-public-key-verification) | Add your identity provider as a sign-in provider of the widget, with its **JWKS URL** or its public key. |
| [Server-side token verification](#approach-2-server-side-token-verification) | Your backend checks the session of the customer and signs a short token for the widget, with a shared secret or its own key. |
| [Backend-created chat links](#approach-3-backend-created-chat-links-with-baked-in-context) | No link for each customer. The token carries the values, and the widget maps its claims to context parameters. |

In each case, your page gives the token to the widget through the `identity` function. The platform checks the token each time the session starts or refreshes. See [Signed-in visitors](/web-widget-sign-in).

The rest of this page applies to chat links only.

***

When embedding Dial AI into your application, you often need to pass context — such as the logged-in user's ID, account number, or role — into the chat session so that functions can act on behalf of that user. Because the widget runs client-side, any context sent directly from the browser can be forged. A malicious user could change their `userId` to someone else's and impersonate them.

This page covers three approaches to passing context securely, each suited to different integration architectures.

## The Problem

Consider a script-tag integration where you pass a user ID as an extra parameter:

```js theme={null}
// DON'T DO THIS — the user can change "user-123" to any value
window.renderModal("dial-ai-button", {
    chatId: "00000000-0000-0000-0000-000000000000",
    backendUrl: "https://your-instance.dialai.ca",
    iconUrl: "/icon.svg",
    extraInternalParameters: {
        userId: "user-123"
    }
});
```

Because this code runs in the user's browser, nothing prevents them from opening DevTools and changing `"user-123"` to `"user-456"`. Any downstream function that trusts this value is now operating on the wrong user's data.

All three approaches below solve this by ensuring user identity is verified server-side before it reaches your flow.

***

## Approach 1: External JWT with Public Key Verification

If your application already issues JWTs to authenticated users (e.g. via an identity provider like Auth0, Cognito, or Keycloak), Dial AI can validate those tokens directly and extract claims from them.

### How It Works

1. Your identity provider issues a signed JWT to the user when they log in
2. The user's browser passes this JWT to Dial AI when creating a chat session
3. Dial AI verifies the JWT signature against your provider's public keys (via a JWKS endpoint)
4. Dial AI checks the issuer claim matches your configured issuer
5. Verified claims (e.g. `sub`, `accountId`) are extracted and made available as internal parameters

Because the JWT is cryptographically signed, the user cannot modify the claims without invalidating the signature.

### Setup

To configure external JWT verification, provide Dial AI with:

* **JWKS URL**: The endpoint where your identity provider publishes its public keys (e.g. `https://your-idp.com/.well-known/jwks.json`)
* **Issuer**: The expected `iss` claim in the JWT (e.g. `https://your-idp.com/`)
* **Tenant**: Which Dial AI tenant this JWT configuration applies to

Once configured, users authenticate to Dial AI by passing their JWT as a Bearer token. Dial AI verifies the signature and issuer, then makes the JWT's claims available to your flow.

### When to Use This

* You already have an identity provider that issues JWTs with a JWKS endpoint
* You want a zero-backend-work integration — the browser can pass the token directly
* You need access to multiple claims from the token (e.g. user ID, roles, email)

***

## Approach 2: Server-Side Token Verification

If your users authenticate with tokens that aren't JWTs, or you need to verify additional state beyond what's in a token (e.g. checking that an account is still active), you can verify the user's identity via a server-side request before passing context to Dial AI.

### How It Works

1. The user logs in to your application and receives a session token
2. When starting a chat, your frontend sends the session token to **your backend**
3. Your backend validates the token against your system of record (database, auth service, etc.)
4. Your backend creates a chat session via the Dial AI API, passing verified context as `extraInternalParams`
5. The chat link or session ID is returned to the frontend

The user never passes their own identity to Dial AI — your backend does, after confirming who they are.

### Example Flow

```
Browser                    Your Backend                 Dial AI
  │                            │                           │
  │─── start chat ────────────►│                           │
  │    (session token)         │                           │
  │                            │── verify token ──►        │
  │                            │◄── user: alice ───        │
  │                            │                           │
  │                            │── POST /api/chat/link ───►│
  │                            │   { extraInternalParams:  │
  │                            │     { userId: "alice" } } │
  │                            │◄── chat link UUID ────────│
  │                            │                           │
  │◄── chat link UUID ────────│                           │
  │                            │                           │
  │── open chat (X-DialAi-Chat-Link: Bearer <uuid>) ─────►│
```

### When to Use This

* Your auth system doesn't use JWTs, or uses opaque tokens
* You need to check live state (account status, permissions) at chat-creation time
* You want full control over what context is passed to Dial AI

***

## Approach 3: Backend-Created Chat Links with Baked-In Context

Dial AI supports creating chat links via API with context permanently embedded in them. This is especially useful for short-lived, user-specific sessions.

### How It Works

1. Your backend authenticates the user through your own auth system
2. Your backend calls the Dial AI API to create a chat link, including verified user context in `extraInternalParams`
3. The chat link UUID is returned to the frontend
4. The frontend uses this link to open the chat — the baked-in context is automatically attached to every conversation created with this link

The context is stored server-side in Dial AI and cannot be modified by the client.

### Permanent Chat Links

Create a chat link with context that persists until explicitly deleted:

```
POST /api/chat/link
Authorization: Bearer <your-dial-ai-jwt>

{
    "flowId": "your-flow-id",
    "name": "Support chat for alice",
    "extraInternalParams": {
        "userId": "alice",
        "accountTier": "premium"
    },
    "settableInternalParams": ["preferredLanguage"]
}
```

* **`extraInternalParams`**: Context baked into the link. Every chat created with this link will have these values as internal parameters. The client cannot override them.
* **`settableInternalParams`**: Parameters the client is allowed to set when creating a chat. Use this for non-sensitive context like UI preferences. If a client attempts to set a parameter not in this list, the request is rejected.

> If a key appears in both `extraInternalParams` and `settableInternalParams`, the client-provided value will take precedence over the baked-in value. This is useful for providing overridable defaults, but be careful not to put trusted identity values (like `userId`) in `settableInternalParams` — the client would be able to override them.

### Temporary Chat Links with JWT Claim Extraction

For short-lived sessions, create a temporary chat link that automatically extracts claims from the caller's JWT:

```
POST /api/v2/chat/link/temporary
Authorization: Bearer <user-jwt>

{
    "flowId": "your-flow-id",
    "name": "Session link",
    "duration": 3600,
    "verifiedExtraInternalParams": {
        "userId": { "type": "jwt-claim", "key": "sub" },
        "accountId": { "type": "jwt-claim", "key": "accountId" }
    }
}
```

* **`duration`**: Link lifetime in seconds (must be positive, maximum 6 hours)
* **`verifiedExtraInternalParams`**: Maps parameter names to JWT claim extraction rules. Dial AI reads the specified claim from the caller's verified JWT and bakes it into the link. If the claim is missing or not a string, the request fails.

This combines the security of JWT verification with the simplicity of a pre-built chat link — the frontend just receives a UUID and doesn't need to handle tokens at all.

### When to Use This

* You want the simplest possible frontend — just a chat link UUID, no token handling
* You need per-user or per-session chat links with guaranteed context
* You want to limit which parameters the client can influence via `settableInternalParams`

***

## Comparison

| | External JWT | Server-Side Verification | Backend-Created Links |
| - | - | - | - |
| **Frontend complexity** | Low — pass existing JWT | Low — call your backend first | Lowest — just a UUID |
| **Backend work** | None (configuration only) | Moderate — verification endpoint | Moderate — link creation endpoint |
| **Identity source** | JWT claims | Your system of record | Your system of record or JWT claims |
| **Context flexibility** | All JWT claims available | Full control | Baked at link creation |
| **Session lifetime** | Per-token expiry | Per-link (optional expiry) | Per-link (optional expiry) |

## Using Context in Flows

Regardless of which approach you use, the verified context arrives in your flow as **internal parameters**. Functions can access these values as inputs by declaring them as [internal parameters (context parameters)](/functions-and-events#inputs). For example, a "Look Up Account" function could take `userId` as an internal parameter and use it to query your database — knowing that the value was verified and cannot have been tampered with by the end user.


# Internal Contacts
Source: https://docs.dialai.ca/internal-contact

Pre-configured destinations the AI agent can transfer customers to

**Internal Contacts** are the phonebook of people and teams the AI agent can transfer a customer to during a conversation — supervisors, specific departments, escalation paths, on-call rotations. Configure them once; the agent (or a supervisor in [Live View](/live-view)) can pick from the list mid-call.

## Where Internal Contacts live

Internal Contacts are managed under **Settings > Operations > Internal Contacts**. The Operations page documents the management interface in detail — see [Operations > Internal Contacts](/operations#internal-contacts).

Each entry has:

| Field | Description |
| - | - |
| **Name** | The display name shown when initiating a transfer. |
| **Phone Number** | The number to dial when this contact is picked. |

## Using Internal Contacts during a live call

From the [Live View](/live-view) page or a transcript detail view:

<Steps>
  <Step title="Open the conversation">
    Click a conversation in Live View or open a conversation from the Inbox.
  </Step>

  <Step title="Choose Transfer">
    Use the call-monitoring actions to initiate a transfer.
  </Step>

  <Step title="Pick a contact">
    The transfer dialog lists every Internal Contact. Pick the right one and confirm.
  </Step>
</Steps>

The agent (or supervisor) doesn't have to remember or look up phone numbers — every approved destination is one click away.

## Internal Contacts vs Points of Contact

A common point of confusion:

* **Points of Contact** are *incoming* channels — phone numbers customers call to reach you.
* **Internal Contacts** are *outgoing* transfer destinations — phone numbers your AI agent dials when handing off a customer to a human team.

The two never overlap.

## Internal Contacts vs Internal Agents

A separate concept that sometimes confuses operators:

* **Internal Contacts** (this page) are human destinations for transfers.
* **Internal Agents** are back-office AI agents your team uses internally — for reporting, analysis, and back-office automation. They never face customers. See [Agents](/agents).

## Tips

* **Use clear names.** "Billing Supervisor" beats "Joe's Desk" — the agent reads these aloud and operators pick from them under time pressure.
* **Keep the list short.** Every transfer destination adds cognitive load when picking. Aim for under a dozen well-defined options rather than a phone-tree dump.
* **Review quarterly.** People move teams, departments reorganize, escalation paths change. Internal Contacts decay quickly if not curated.

***

## Related

<CardGroup>
  <Card title="Operations" icon="gear" href="/operations">Manage Internal Contacts alongside Skills and Do-Not-Call.</Card>
  <Card title="Live View" icon="eye" href="/live-view">Initiate transfers from a live call.</Card>
  <Card title="Agents" icon="robot" href="/agents">Internal back-office AI agents (different concept).</Card>
</CardGroup>


# Introduction
Source: https://docs.dialai.ca/introduction

What Dial AI does and how the pieces fit together

<Frame>
  <img alt="Dialai dashboard in light mode" />

  <img alt="Dialai dashboard in dark mode" />
</Frame>

Dial AI runs AI agents that talk to your customers over voice, SMS, email, web chat, and other social-media platforms. You design what each agent says and does as a **flow** — a graph of conversation states with instructions, function calls, and rules for when to hand off to a human. You wire the flow to a **point of contact** (a phone number, email address, web widget, etc.), publish it, and watch it work.

When the AI can't handle something, it transfers the conversation to a human agent — with the full transcript, the customer's history, and any data the AI collected. Human agents pick up the conversation in their **inbox**; supervisors watch live traffic in **live view** and review completed conversations in the archive.

These docs cover the operator surface: building flows, connecting channels, monitoring conversations, and tuning what's in production.

## Quick start

<CardGroup>
  <Card title="Key concepts" icon="compass" href="/keyconcepts">
    Glossary of flows, states, transitions, agents, points of contact, and more.
  </Card>

  <Card title="Build your first flow" icon="pen-to-square" href="/first-flow">
    A guided walkthrough of the flow editor, end to end.
  </Card>

  <Card title="Watch conversations live" icon="eye" href="/live-view">
    Monitor in-progress calls, listen in, and step in when needed.
  </Card>

  <Card title="Triage the inbox" icon="inbox" href="/inbox">
    Handle transcripts that need human review or follow-up.
  </Card>
</CardGroup>

## How operators use Dial AI

<Steps>
  <Step title="Define what the agent should do">
    Use **Flows** to lay out conversation paths — greetings, intents, branches, and handoffs. Use **Thoughts** to express *how* the agent should think at each state in plain language. Ground the agent in your own knowledge by uploading **Documents** or connecting an S3 / Confluence source.
  </Step>

  <Step title="Connect a channel">
    Wire a **Point of Contact** — a phone number, SMS line, email address, web widget, or Slack workspace — to the flow. Each channel can run its own flow, or share one across many.
  </Step>

  <Step title="Test before you ship">
    Run **Test Scenarios** to assert behavior end-to-end. Use the in-product chat sandbox for quick iteration. Publish a flow only when its tests pass.
  </Step>

  <Step title="Watch it work">
    The **Dashboard** shows day-to-date and live operational metrics. **Live View** gives you a real-time pulse on every in-flight conversation. **Conversations** is the searchable archive of everything that already happened.
  </Step>

  <Step title="Tune as you learn">
    Use call review criteria, flagged conversations, and analytics to identify gaps. Refine flows, add documents, retrain — and ship the new version when you're confident.
  </Step>
</Steps>

## What you can build

<CardGroup>
  <Card title="Flexible flows" icon="diagram-project" href="/flows">
    Branching conversation flows with state-level instructions, function calls, and human-handoff rules.
  </Card>

  <Card title="Multiple channels" icon="phone" href="/points-of-contact">
    Voice, SMS, email, web chat, and Slack — each with its own routing and schedule.
  </Card>

  <Card title="Custom agent voice" icon="volume-high" href="/agent-voice">
    Choose or tune the synthetic voice that represents your brand on every call.
  </Card>

  <Card title="Outbound campaigns" icon="phone-arrow-up-right" href="/outbound">
    Run AI-driven outbound voice or email campaigns against a manifest of contacts.
  </Card>

  <Card title="Grounded knowledge" icon="book" href="/manage-documents">
    Upload documents or sync from Confluence and S3 so agents answer from your sources of truth.
  </Card>

  <Card title="Integrations" icon="plug" href="/api-integration">
    Put a web widget on your site, or call the REST API to plug Dial AI into your systems.
  </Card>
</CardGroup>

## Looking for something else?

* The **Building & Managing Flows** group covers everything about designing agents — start with [Key concepts](/keyconcepts) if you're new.
* The **Monitoring** group covers the day-to-day operator views — Dashboard, Conversations, Live View, Inbox.
* The **Settings** group covers tenant-wide configuration — users, permissions, theming, environment variables.

Need help that isn't in the docs? Email [support@dialai.ca](mailto:support@dialai.ca).


# Issues
Source: https://docs.dialai.ca/issues

Track bugs, requested flow changes, and observations, and turn review findings into applied fixes

<Frame>
  <img alt="Issues list (light mode)" />

  <img alt="Issues list (dark mode)" />
</Frame>

**Issues** are your tenant's tracked work items: an incorrect response caught during call review, a requested flow change, an investigation to run, or an observation worth recording. Each issue carries a status, a priority, a comment thread, and attachments, so findings survive across runs and hand off cleanly between people and agents.

The page has a second tab, **Agent Notes**: a shared scratchpad of durable context (patterns noticed, decisions made, fixes applied, things deliberately ignored). A note is reference memory with no action attached; an issue is a work item someone should act on.

## Accessing Issues

Navigate to **Issues** in the left sidebar.

## What's on the page

The issues table shows every issue in the tenant.

| Column | What it shows |
| - | - |
| **Status** | Where the issue is in its lifecycle (see below). |
| **Title** | Summary line, plus the issue number and age. |
| **Type** | Flow change / Incorrect response / Observation / Investigation. |
| **Priority** | Low / Normal / High / Urgent. |
| **Opened by** | The person, or agent, that filed it. |
| **Updated** | Last activity. |

Filter by status, priority, or type using the controls above the table, and click **Create Issue** to file one manually.

## Inside an issue

Click any row to open the issue. The left column holds the **description** and a running **activity** feed: every status change and comment, oldest first. The right rail is where you work the issue:

<Frame>
  <img alt="Issue detail view (light mode)" />

  <img alt="Issue detail view (dark mode)" />
</Frame>

* **Status / Priority / Type**: change any of them inline from the dropdowns.
* **Attachments**: link the issue to the things it's about: paste a **transcript** ID, or search for a **flow**, **test scenario**, or **related issue**. A reviewer can then jump straight from the issue to the exact call, flow, or test it concerns.
* **Comment**: add context to the thread; each comment is stamped with who wrote it and when.

## Issue lifecycle

| Status | Meaning |
| - | - |
| **Open** | Filed, not yet picked up. |
| **In progress** | Someone is actively working it. |
| **Verifying** | A fix has been applied and is being checked, and issues move here automatically when a proposed change is applied. |
| **Resolved** | Fix confirmed. |
| **Closed** | Done, no further action. |
| **Won't fix** | Deliberately not acting; the reasoning lives in the comments. |

## Comments and attachments

Every issue has a flat comment thread for discussion. Issues can also attach to the things they're about: transcripts, flows, test scenarios, and other issues. A reviewer can jump straight from "the agent said the wrong thing" to the exact call where it happened.

## Who files issues

* **Your team**, via **Create Issue**.
* **The review agent**, when call review flags a conversation that needs a fix rather than just a flag.
* **Internal agents**, which can open and update issues as they work so their findings are handed off with root-cause summaries and reproducible steps.

## Proposed changes: closing the loop

The most important thing attached to an issue is a **proposed change**: a structured fix proposal, distinct from the free-text comments. It carries the root cause, the precise change, an acceptance test, and risk/rollback notes.

The most common author is the review agent: when a flow accrues review corrections, they're distilled into a suggested call-review-guidance update and filed as a proposed change on a flow-targeted issue.

A proposal moves through its own statuses: **proposed**, then **approved / needs changes / rejected**, and finally **applied** or **superseded**.

### Approve & apply

Reviewing a proposal is one click: **Approve & apply** writes the suggested guidance to the flow and marks the proposal applied, which moves the parent issue to **Verifying**. Review findings become applied flow improvements in minutes, with the issue trail as the audit record.

<Note>Applying a proposed change is always a human action. Agents can prepare and file proposals, but never apply them.</Note>

## Agent Notes

The second tab holds the shared scratchpad. Notes work like issues without a lifecycle: create them, attach them to transcripts or flows, and search them later. Use notes for context you'd want the next person (or agent) to know; use issues for work that must get done.

***

## Related

<CardGroup>
  <Card title="Conversations" icon="comments" href="/conversations">Where review flags surface on individual calls.</Card>
  <Card title="Testing flows" icon="circle-check" href="/testing-flows">Verify a fix with test scenarios before resolving.</Card>
  <Card title="Flows" icon="diagram-project" href="/flows">Where applied guidance changes land.</Card>
</CardGroup>


# Key Concepts
Source: https://docs.dialai.ca/keyconcepts

The vocabulary you need before building flows and agents

This page is the glossary. Everything else in the **Building & Managing Flows** group assumes you know these terms.

## Flow

A **Flow** is a structured sequence of states and transitions that guides a conversation between your AI agent and the customer. A flow has an **initial state**, branches based on what the agent learns during the conversation, and ends when the agent (or a function) decides the interaction is done.

Flows are customer-facing. They run on every channel — voice, SMS, web chat, email, Slack.

See: [Flows](/flows), [Building Your First Flow](/first-flow).

## State

A **State** is one step inside a flow. Each state has:

* A **Thought** — the instructions that tell the AI agent what to say or do here.
* A set of **Functions** the agent is allowed to call from this state.
* Outgoing **Transitions** to other states, each triggered by an **Event**.

The agent stays in a state until a transition fires.

## Transition

A **Transition** is a directed edge from one state to another, triggered by a named **Event**. Transitions are how flows branch — different events from the same state can lead to different next states.

## Event

An **Event** is a named outcome a function can emit. Functions declare the events they may emit; transitions listen for them. Example: a `Lookup Account` function might emit `AccountFound` or `NoAccountMatch`, each driving the flow to a different state.

## Thought

A **Thought** is the natural-language instruction attached to a state. It tells the AI agent how to behave at this point in the conversation — what to say, what data to collect, when to call functions, how to handle edge cases.

Well-written thoughts use strong directives ("must", "will") and reference function names explicitly. See [Designing Thoughts](/thoughts) for the full guide.

## Function

A **Function** is a piece of JavaScript the agent can call. Functions can:

* Take in **parameters** from the agent, from conversation context, or from flow-level static configuration.
* Return a **response** the agent will see.
* Set **context additions** for use by later functions.
* Emit an **event** that drives a state transition.

See [Functions and Events](/functions-and-events).

## Parameter

**Parameters** are data values used inside a flow. Four kinds:

* **Normal parameters** — passed to a function by the agent at call time.
* **Internal (context) parameters** — values set by a previous function or by the runtime, available to later functions.
* **Static parameters** — flow-level configuration (API keys, base URLs, feature toggles). Configured under **Configure Flow > Variables**.
* **Emitted context additions** — context keys a function may write. Declaring these enables UI suggestions and a warning when a function writes an undeclared key.

## Agent

An **Agent** is an internal AI assistant your team uses inside the platform — for analysis, reporting, or back-office tasks. Agents are not customer-facing. They live alongside flows on the Build page for convenience.

See [Agents](/agents).

## Point of contact (POC)

A **Point of Contact** is the channel that connects a flow to the outside world — a phone number, SMS line, email address, [web widget](/web-widgets), or Slack workspace. One flow can serve many POCs; one POC runs exactly one flow at a time.

See [Points of Contact](/points-of-contact).

## Skill

A **Skill** is a named capability that human agents have (e.g., Billing, Spanish, Fraud Assistance). When a flow hands off to a human, the routing engine matches the conversation's required skills against the available human agents.

See [Operations > Skills](/operations#skills).

## Draft vs Published

Every flow has a **draft** (the version you're editing) and zero or more **published** versions. Points of Contact reference a specific published version, so editing a draft never disrupts traffic. Hit **Publish** to cut a new immutable version and update the POCs that should pick it up.

## Test Scenario

A **Test Scenario** is a recorded simulated conversation used to assert flow behavior. Scenarios can be replayed across flow versions to catch regressions before publishing.

See [Testing Flows](/testing-flows).

## Document

A **Document** is reference material the AI agent can search during a conversation. Documents can be uploaded directly, or sourced from a connected S3 bucket or Confluence space.

See [Manage Documents](/manage-documents).

## FAQ

An **FAQ** is a Q\&A pair attached to a flow. FAQs are surfaced to the agent when the customer's message matches the question.

See [FAQ](/faq).

***

## Related

<CardGroup>
  <Card title="Build your first flow" icon="pen-to-square" href="/first-flow">Apply the concepts.</Card>
  <Card title="Flows overview" icon="diagram-project" href="/flows">Manage flows.</Card>
  <Card title="Flow configuration" icon="sliders" href="/flow-configuration">Every flow setting, explained.</Card>
</CardGroup>


# Live View
Source: https://docs.dialai.ca/live-view

Monitor and manage active customer conversations in real time

<Frame>
  <img alt="Live View in light mode" />

  <img alt="Live View in dark mode" />
</Frame>

The **Live View** page gives supervisors and operators a real-time pulse on every conversation in flight. Watch what the AI agent is doing right now, listen in on voice calls, step in if a conversation goes sideways, and transfer to a human when needed.

For the searchable archive of past conversations, see [Conversations](/conversations). For conversations waiting to be assigned to a human, see the [Inbox](/inbox).

## Accessing Live View

Navigate to **Monitor > Live View** in the left sidebar.

## The conversation list

The conversation table shows every in-progress interaction across every channel. Columns include:

| Column | What it shows |
| - | - |
| **ID** | Unique conversation identifier. |
| **Platform** | Voice / SMS / Web Chat / Email / Slack icon. |
| **Status** | Where the conversation is in its lifecycle. |
| **Duration** | How long it's been going. |
| **Sessions** | How many sessions this contact has had in the past 24 hours. |
| **Risk** | Color-coded estimation of how the call is progressing. |
| **Sentiment** | Detected customer emotion. |
| **Functions** | Functions the AI has called during the interaction. |

Click any row to expand the detail panel beneath it.

### Filters

The filter toolbar at the top lets you narrow the view by **Direction**, **Risk**, **Duration**, **Status**, **Sentiment**, and **Platform**. Useful when a high volume of calls makes it hard to spot the ones that need attention.

## Conversation details panel

Selecting a conversation opens its detail panel below the table. The panel shows:

* **Platform** and **Contact ID** — the channel and customer identifier.
* **Status** — current lifecycle state.
* **Top sentiments** — up to the top three emotions detected so far, filtering out any with a score at or below 0.1.
* **Duration** and **Start** — timing.
* **Live transcript** — messages as they happen, alongside the flow graph showing the current state and the path the conversation has taken so far.
* **Function calls** — every tool the AI has invoked, with inputs and outputs.

You can expand multiple call detail panels at once to keep an eye on several conversations in parallel.

## Monitor mode

Toggle **Monitor** in the top bar to listen in on a voice call without the customer or the AI knowing. This is supervisor-mode listening — useful for quality assurance and training. Turn it off when you're not actively monitoring; it consumes a softphone leg while engaged.

### Call monitoring actions

> These controls are available **only while an AI Agent call is in progress**. If a call is **queued** or **assigned** to a human, these actions are not shown.

### Listen In

Silent monitoring of the live call. The caller and the agent do not hear you.

**How to use**

1. Open the **⋯ Actions** menu on the active call.
2. Select **Listen In**.

**What happens**

* You can hear the conversation in real time.
* Your microphone is not connected to the call.

***

### Take Over

Assume live control of the call. You can hand control back later.

**How to use**

1. Open **⋯ Actions**.
2. Select **Take Over**.

**What happens**

* You are connected as the speaking participant.
* When finished, hand control back to the previous participant (AI Agent or original agent).

***

### Transfer

Send the live call to an **external phone number**.

**How to use**

1. Open **⋯ Actions**.
2. Select **Transfer**.
3. Enter the destination phone number.
4. Confirm to transfer.

**What happens**

* The system dials the destination number and bridges the caller.
* After transfer, control moves to the external destination.

***

### Enqueue

Move the live call into the **human agent queue**.

**How to use**

1. Open **⋯ Actions**.
2. Select **Enqueue**.

**What happens**

* The call is placed back into the queue to be assigned to a human agent.
* The AI Agent stops handling the call.

***

### End

Immediately hang up the call for all parties.

**How to use**

1. Open **⋯ Actions**.
2. Select **End** and confirm.

**What happens**

* The call ends immediately.
* Post-call processes (wrap-up, logging, transcript, etc.) continue as configured.

***

### Add Coaching

Send **coaching notes** to the agent only (not visible to the caller) while the call is active.

**How to use**

1. Open **⋯ Actions**.
2. Select **Add Coaching**.
3. Enter your coaching note and send.

**What happens**

* The note appears to the agent as an internal coaching message during the call.
* The caller never sees coaching notes.

***

### Summary (for quick scan)

| Action | Purpose | Notes |
| - | - | - |
| Listen In | Silent monitoring | No whisper audio |
| Take Over | You become the speaking participant | You can hand control back later |
| Transfer | Send caller to an **external** phone number | Replaces any prior inline refs |
| Enqueue | Return caller to the **human agent queue** | For assignment by a human agent |
| End | Hang up for all parties immediately | Triggers post-call handling |
| Add Coaching | Side-channel guidance to the agent (text only) | Not visible to the caller |

These controls let you intervene on a live call — barge in to talk to the customer, transfer to a human agent, or end the call.

## Settings

The **Settings** button in the top bar opens preferences that tailor your Live View experience:

* **Auto open** — automatically opens new conversations as they appear in the list.
* **Audio alert** — plays a notification sound when a new conversation starts.
* **Auto clear** — removes completed conversations from the list automatically.
* **Max conversations** — caps how many conversations auto-open at once.

These settings are per-user; they don't affect other operators.

## Empty state

When there are no active conversations, the table shows "No Conversations" along with a hint about whether your filters might be hiding live activity. Clear the filters to see everything that's actually in flight.

***

## Related

<CardGroup>
  <Card title="Conversations" icon="messages" href="/conversations">Past transcripts, searchable and filterable.</Card>
  <Card title="Inbox" icon="inbox" href="/inbox">Take over a conversation that needs a human.</Card>
  <Card title="Dashboard" icon="chart-line" href="/dashboard">Aggregate live metrics.</Card>
</CardGroup>


# Manage Documents
Source: https://docs.dialai.ca/manage-documents

Upload files, sync from S3, Confluence, or SharePoint, and curate the knowledge your AI agents can search

<Frame>
  <img alt="Documents page in light mode" />

  <img alt="Documents page in dark mode" />
</Frame>

The **Documents** page is your tenant's knowledge library — every reference document the AI agent can search during a conversation lives here, whether it came from a direct file upload, an S3 bucket, a Confluence space, or a SharePoint site.

## Accessing Manage Documents

Navigate to **Docs > Manage** in the left sidebar.

## What's on the page

Every document indexed in the tenant appears as a card showing:

* The document name (filename for uploads, page or object name for connectors).
* An **Uploaded** or **Synced** timestamp showing when the index was last updated.
* A **More actions** menu (three-dot) with Download, Sync, and Delete.

The **Upload** button in the top-right opens the upload dialog, where you choose the source type.

## Adding documents

The Upload dialog has four tabs, one per source type. Click any tab to switch.

### File upload

<Frame>
  <img alt="File upload tab in light mode" />

  <img alt="File upload tab in dark mode" />
</Frame>

Use the **File** tab for one-off documents you want to manage manually.

<Steps>
  <Step title="Drag a file or click Choose a file">
    Supported formats: **PDF, TXT, HTM, HTML**.
  </Step>

  <Step title="Click Upload">
    The dialog closes immediately. The document appears in the list and indexes in the background; the card shows a processing indicator until indexing completes.
  </Step>
</Steps>

Updating a file means re-uploading it — there's no in-place file replace. The recommended workflow is: delete the old version, upload the new one, re-attach to any flow that needs it.

### S3 Bucket

<Frame>
  <img alt="S3 bucket connector in light mode" />

  <img alt="S3 bucket connector in dark mode" />
</Frame>

Use the **S3 Bucket** tab when your documents already live in S3 and you want the AI agent to read from the source of truth.

<Steps>
  <Step title="Enter the Bucket Name">
    The exact name of the bucket — no `s3://` prefix, no region suffix.
  </Step>

  <Step title="Enter the Region">
    The AWS region the bucket lives in (e.g., `us-east-1`, `us-west-2`).
  </Step>

  <Step title="Click Upload">
    The platform queues an indexing job. Objects in the bucket are pulled, indexed, and turned into searchable documents in the background. Each indexed object appears as its own card in the list.
  </Step>
</Steps>

<Note>The tenant must already have IAM access to the bucket configured at the platform level. If indexing fails with a permission error, contact your administrator to grant the platform's service role read access. Buckets not pre-authorized for the tenant cannot be added.</Note>

To pick up new objects added to the bucket later, open the bucket's card in the documents list and use **More actions > Sync** to trigger a re-index.

### Confluence

<Frame>
  <img alt="Confluence connector in light mode" />

  <img alt="Confluence connector in dark mode" />
</Frame>

Use the **Confluence** tab to sync documents from a Confluence space. The first time you connect, you'll see an **Install Dial AI App** button — that launches the OAuth flow on Atlassian's side.

<Steps>
  <Step title="Install the Dial AI App in Confluence">
    Click **Install Dial AI App**. You'll be redirected to Atlassian to authorize. Once approved, the OAuth token is stored against your tenant and you can return to the dialog.
  </Step>

  <Step title="Pick a space">
    After install, the Confluence tab populates with the spaces the app has access to. Pick the one you want to index.
  </Step>

  <Step title="Optionally filter by label">
    Add one or more labels to the **Allowed labels** list. When set, only pages with at least one matching label are indexed. Leave empty to index every page in the space.
  </Step>

  <Step title="Click Upload">
    The platform queues an indexing job. Pages are fetched, indexed, and surfaced as searchable documents. Each page becomes its own document card.
  </Step>
</Steps>

To pick up changes (new pages, edits to existing pages, removed pages), use **More actions > Sync** on a Confluence-sourced document to re-index. Sync is on-demand — the platform does not currently poll Confluence on a schedule.

### SharePoint

Use the **SharePoint** tab to ground your agents in content straight from your organization's SharePoint, with no copy-pasting files out of it and no duplicate libraries to maintain.

<Steps>
  <Step title="Sign in with Microsoft">
    The first time you connect, you'll be prompted to sign in with your Microsoft account and grant the Dial AI app access. Access is scoped per site: an admin approves which SharePoint sites the app can read.
  </Step>

  <Step title="Pick a site">
    After sign-in, choose the SharePoint site you want to index from the list the app has access to.
  </Step>

  <Step title="Click Upload">
    The platform queues an indexing job. Documents in the site are fetched, indexed, and surfaced as searchable document cards, like any other source.
  </Step>
</Steps>

To pick up changes in SharePoint later, use **More actions > Sync** on a SharePoint-sourced document to re-index. Sync is on-demand.

## Managing existing documents

Click **More actions** on any document card for:

* **Download** — save the indexed source to disk. For Confluence, SharePoint, and S3 sources, this is the fetched copy at index time.
* **Sync** — re-fetch and re-index. Useful after changes in the source bucket or space.
* **Delete** — remove the document from the tenant.

<Warning>If a document is currently attached to a flow's Documentation tab, deletion is blocked. Detach it from every flow first.</Warning>

## How documents reach the AI agent

A document in this list isn't automatically used by every flow. To make the agent search a document during a conversation, attach it to a flow under **Configure Flow > Documentation**. See [Flow Documentation](/flow-documentation) for the full configuration reference, including how to tune document amount and query rewriting.

The same documents are also available from [Document Search](/document-search) — a standalone interface for ad-hoc querying.

## Source comparison

| | File upload | S3 Bucket | Confluence |
| - | - | - | - |
| **Best for** | One-off documents you own | Documents already in S3 | Living documentation in Confluence |
| **Auth** | None | Platform-level IAM (admin) | OAuth (per tenant) |
| **Filtering** | n/a (one file at a time) | Whole bucket | Labels (optional) |
| **Sync model** | One-time at upload | On-demand re-index | On-demand re-index |
| **Best when** | Static reference material rarely changes | You already manage versioning in S3 | Your team edits docs in Confluence and wants the agent to pick up updates |

## Supported file formats

For direct file upload: **PDF, TXT, HTM, HTML**. S3 and Confluence connectors handle the file/page types those sources naturally expose.

***

## Related

<CardGroup>
  <Card title="Document search" icon="magnifying-glass" href="/document-search">Search across every indexed document.</Card>
  <Card title="Flow documentation" icon="book-open" href="/flow-documentation">Attach documents to a specific flow.</Card>
  <Card title="FAQ" icon="circle-question" href="/faq">Configure short Q\&A pairs that complement documents.</Card>
</CardGroup>


# Operations
Source: https://docs.dialai.ca/operations

Tenant-wide operational configuration — journey, internal phonebook, do-not-call, and skills

<Frame>
  <img alt="Operations Journey tab in light mode" />

  <img alt="Operations Journey tab in dark mode" />
</Frame>

The **Operations** page is the catch-all for tenant-wide operational config that doesn't belong to any single flow. Four tabs: **Journey** (what links a customer's conversations together), **Internal Contacts** (the internal phonebook), **Do Not Call** (outbound suppression), and **Skills** (routing tags for human handoff).

## Accessing Operations

Navigate to **Settings > Operations** in the left sidebar.

## Journey

The Journey tab controls which parameter names are used to **stitch separate conversations into a single customer timeline**. When an agent collects a value like `CISAccountNumber` in one conversation and the same value shows up again next week, the platform threads those conversations together in [Contact History](/points-of-contact#contact-history) — but only for parameters listed here.

<Steps>
  <Step title="Choose identifying parameters">
    Under **Contact History Params**, use the **Configs** dropdown to pick the parameter names that uniquely identify a customer (e.g., `CISAccountNumber`, `ContactId`, `phoneNumber`).
  </Step>

  <Step title="Save">
    Click **Save** to apply.
  </Step>

  <Step title="Backfill (optional)">
    Click **Backfill** to re-thread historical conversations using the updated identifier set. Useful right after adding a new parameter.
  </Step>
</Steps>

<Note>Parameters chosen here must actually be set by your flow's [Functions](/functions-and-events) during the conversation — otherwise the platform has nothing to stitch on.</Note>

## Internal Contacts

<Frame>
  <img alt="Internal Contacts tab in light mode" />

  <img alt="Internal Contacts tab in dark mode" />
</Frame>

The phonebook used by call-center workflows for warm-transfer destinations: escalation lines, supervisor desk phones, and external partner numbers the agent can transfer customers to.

| Column | What it shows |
| - | - |
| **Name** | Display name shown when a transfer is offered (e.g., "Billing Escalation"). |
| **Phone Number** | The number the transfer dials. |

Top-right actions:

* **Create** — add a new internal contact.
* **Delete** (row-level icon) — remove an outdated entry.

For end-to-end coverage of building a dedicated Internal Contact transfer destination — including PSTN vs SIP routing and per-skill steering — see [Internal Contact](/internal-contact).

## Do Not Call

<Frame>
  <img alt="Do Not Call tab with Add Numbers dialog open in light mode" />

  <img alt="Do Not Call tab with Add Numbers dialog open in dark mode" />
</Frame>

The Do Not Call (DNC) suppression list blocks specific phone numbers from being dialed by outbound campaigns. Numbers on this list are filtered out before the dispatcher places the call.

<Steps>
  <Step title="Click Add Numbers">
    Opens the bulk-add dialog. Paste one number per line, or upload a CSV/TXT file.
  </Step>

  <Step title="Submit">
    The numbers appear in the list and are immediately respected by [outbound campaigns](/outbound).
  </Step>

  <Step title="Remove an entry">
    Click the delete icon on a row to lift the suppression for that number.
  </Step>
</Steps>

<Warning>The DNC list is tenant-wide. Removing a number affects every campaign in the tenant — verify the lift is intentional before clicking delete.</Warning>

## Skills

<Frame>
  <img alt="Skills tab in light mode" />

  <img alt="Skills tab in dark mode" />
</Frame>

Skills are short labels (e.g., **Billing**, **Spanish**, **Fraud**) that the routing engine uses to match a handoff to a qualified human agent. Each human agent picks the skills they can handle from their [Personal Configuration](/personal-configuration); when a flow requests a handoff with a specific skill, the router narrows assignment to users whose skill set covers the request.

<Note>Only users with the **DialAiAdmin** role can manage skills.</Note>

### Creating a skill

<Steps>
  <Step title="Click Create">
    Opens the create dialog.
  </Step>

  <Step title="Enter a name">
    Use a short, recognizable label — it appears verbatim in users' Personal Configuration dropdowns.
  </Step>

  <Step title="Click Create">
    The new skill is immediately selectable by users.
  </Step>
</Steps>

### Deleting a skill

Click the delete icon on the skill row, then confirm. Deletion is irreversible.

<Warning>Deleting a skill doesn't auto-remove it from human agents who already selected it. Those agents keep the tag (struck-through) until they next save their Personal Configuration.</Warning>

### Best practices

| Practice | Reason |
| - | - |
| Use names ≤ 25 characters. | Fits the multi-select pill UI without truncation. |
| Avoid overlapping meanings ("Customer Support" vs "Customer Assistance"). | Keeps routing logic unambiguous. |
| Review the list quarterly. | Retire unused skills to keep agents' selectors tidy. |

***

## Related

<CardGroup>
  <Card title="Users" icon="users" href="/users">Assign skills and routing settings to operators.</Card>
  <Card title="Personal Configuration" icon="user-gear" href="/personal-configuration">Where each user selects their own skills.</Card>
  <Card title="Outbound Campaigns" icon="phone-arrow-up-right" href="/outbound">Where the DNC list is enforced.</Card>
  <Card title="Points of Contact" icon="phone" href="/points-of-contact">Where Contact History (driven by Journey params) lives.</Card>
</CardGroup>


# Outbound Campaigns
Source: https://docs.dialai.ca/outbound

Run AI-driven outbound voice campaigns against a list of contacts, or dispatch one-off calls

<Frame>
  <img alt="Outbound Campaigns list in light mode" />

  <img alt="Outbound Campaigns list in dark mode" />
</Frame>

**Outbound Campaigns** let the AI agent place calls *to* customers — for billing reminders, appointment confirmations, NPS follow-ups, renewals, or anything else where you reach out instead of waiting for inbound. Each campaign attaches a flow to a list of contacts and dispatches calls at a controlled rate.

For one-off calls outside a campaign, see [Dispatch Single](#dispatch-single).

## Accessing Outbound

Navigate to **Outbound > Campaigns** in the left sidebar.

## What's on the page

The campaigns table shows every outbound voice campaign in the tenant.

| Column | What it shows |
| - | - |
| **Name** | The campaign name (e.g., "Late Payment Reminder"). |
| **Type** | Icon for the campaign type. |
| **Active** | Status indicator — paused or running. |
| **Batch Size** | Maximum concurrent calls the dispatcher will schedule at once. |
| **Created** | When the campaign was created. |
| **Flow** | The flow this campaign runs. Click to open it in the flow editor. |
| **Scheduler** | Link into the campaign's scheduler tab. |

Top-right actions:

* **Filter** — narrow the campaigns by name, date, or active status.
* **Dispatch Single** — open the [one-off call](#dispatch-single) form.
* **Create Campaign** — start the campaign-creation flow.

## Creating a campaign

Click **Create Campaign** to start the create flow. You'll attach a flow, configure the dispatcher, and upload a contacts manifest. The contacts table inside the campaign is where the actual call queue lives.

## Inside a campaign

Open a campaign by clicking its row. Each campaign has three tabs: **Contacts**, **Manual**, and **Schedule**.

### Scheduler

<Frame>
  <img alt="Campaign Scheduler tab in light mode" />

  <img alt="Campaign Scheduler tab in dark mode" />
</Frame>

Controls when and how aggressively the dispatcher places calls.

* **Batch Size** — maximum concurrent calls the dispatcher will schedule at once. Higher numbers process the contact list faster but consume more telephony capacity.
* **Dispatcher On/Off** — master switch. Flip on when you want the campaign to start placing calls.
* **Calendar** — schedule windows for when the dispatcher is allowed to run. Same calendar widget as the platform-wide [Schedule](/schedule) page, but scoped to this campaign. Use windows like "Tue–Thu 10am–4pm" to respect customer timezones and call-time rules.

The **Edit Queue** button in the top-right opens the queue settings (max concurrent calls, retry policy) in a side panel.

### Contacts Table

<Frame>
  <img alt="Contacts Table in light mode" />

  <img alt="Contacts Table in dark mode" />
</Frame>

The full queue of contacts. Each row is one outbound call.

| Column | What it shows |
| - | - |
| **Phone Number** | The customer's number. |
| **Status** | Queued / Launched / Completed / Failed. |
| **Voice** | The synthetic voice used for this call. |
| **AI Phone Number** | The caller-ID number the call dials *from*. |
| **Parameters** | Per-contact parameters merged into the flow (e.g., FirstName). |
| **Transcript** | Link to the transcript after the call completes. |
| **Launched At** | When the call was dispatched. |

Top-right toolbar:

* **Add** — append contacts to the campaign. The add dialog supports CSV upload and inline entry.
* **Launch** — manually launch the selected contacts (overrides batch-size pacing for emergencies).
* **Relaunch** — re-dispatch contacts that already ran. Useful for retry-after-fix scenarios.
* **Delete** — remove contacts from the campaign.
* **Edit** — modify exactly one contact's parameters before it dispatches.

### Manual launch console

<Frame>
  <img alt="Manual launch console (light mode)" />

  <img alt="Manual launch console (dark mode)" />
</Frame>

The **Manual** tab is the campaign's on-demand launch console. Instead of waiting for the dispatcher's schedule, launch calls yourself and watch them as they run:

* **Unlaunched**: contacts still queued. Click the launch button on a row to dispatch that call immediately.
* **Currently launched**: calls in flight or just completed, each with a live status and a link to its transcript.
* **Live conversation panel**: select any launched call to watch the conversation in real time, including the agent's messages and (expandable) its thoughts.

Use it for controlled sends ("launch five, listen, adjust, launch the rest"), urgent one-offs inside a campaign, and demos.

## Dispatch Single

<Frame>
  <img alt="Manual Launch Call in light mode" />

  <img alt="Manual Launch Call in dark mode" />
</Frame>

The **Dispatch Single** action (top-right of the Campaigns page) opens a one-off launch form for placing a single outbound call without setting up a campaign. Use for ad-hoc test calls, executive follow-ups, or any single dispatch that doesn't justify a campaign.

Required fields:

* **Flow** — the conversation flow to run.
* **Agent Phone Number** — the caller-ID number to dial from.
* **Voice** — the synthetic voice.
* **Customer Number** — the number to dial.
* **Speech to Text Runner** and **Model** — transcription configuration (default: deepgram / flux).

Click **Launch** to place the call.

## Per-contact parameters

Each contact in a campaign can carry parameters that get merged into the flow at call time. The Contacts Table shows these in the **Parameters** column — for example, a `FirstName` parameter so the agent says "Hi Demo A, this is..." instead of a generic greeting.

Set per-contact parameters when uploading the contact manifest, or use **Edit** on a single row to tweak before dispatch.

## Compliance: Do-Not-Call

Manage your tenant's Do-Not-Call suppression list under **Settings > Operations > Do Not Call** — see [Operations](/operations#do-not-call). Before launching a campaign, review the DNC list against your contact manifest to keep prohibited numbers out of the queue.

## Tips

* **Start with a small batch size.** A batch size of 1–3 lets you watch the first few calls before opening the floodgates.
* **Use call-time windows.** Even if your contacts span timezones, the campaign Scheduler's calendar makes it easy to respect "no calls before 9am or after 8pm local time" rules.
* **Set caller-ID to a number the customer recognizes.** Calls from unrecognized numbers get answered far less often.
* **Watch the first conversations.** Use [Live View](/live-view) to monitor the first few real outbound calls — that's where flow bugs surface fastest.

***

## Related

<CardGroup>
  <Card title="Email campaigns" icon="envelope" href="/email-campaigns">Outbound via email instead of voice.</Card>
  <Card title="Points of Contact" icon="phone" href="/points-of-contact">Configure the caller-ID numbers campaigns dial from.</Card>
  <Card title="Live View" icon="eye" href="/live-view">Watch calls go out in real time.</Card>
  <Card title="Operations" icon="gear" href="/operations">Manage the Do-Not-Call list.</Card>
</CardGroup>


# Permissions
Source: https://docs.dialai.ca/permissions

Roles and scope-based access control for your tenant

<Frame>
  <img alt="Permissions Roles list in light mode" />

  <img alt="Permissions Roles list in dark mode" />
</Frame>

The **Permissions** page is where administrators define and review the roles that govern who can do what in your tenant. Access is **scope-based**: each role bundles a set of fine-grained scopes (e.g., `transcripts:read`, `flows:publish`, `users:update`), and a user's effective access is the union of every scope on every role they hold.

## Accessing Permissions

Navigate to **Settings > Permissions** in the left sidebar.

## What's on the page

The Roles list shows every role configured for your tenant.

| Column | What it shows |
| - | - |
| **Role Name** | The role's display name. Click to open the role editor. |
| **Permission Count** | How many scopes the role bundles. |
| **Actions** | Delete the role (row-level icon). |

Top-right: **Add Role** opens the new-role dialog.

### Unassigned permissions banner

At the top of the page, the platform surfaces any scopes that **exist in the system but aren't covered by any role in this tenant**. This banner is your hint that a recent platform update added new permissions — review and assign them to the right roles so the features become reachable.

## Built-in roles

The platform ships with a starter set of roles. Common ones:

| Role | Typical use |
| - | - |
| **Admin** / **DialAiAdmin** | Full tenant access — manage users, flows, environment, billing. |
| **Maintainer** | Build and publish flows, manage agents and POCs, run campaigns. Cannot manage users or permissions. |
| **Read-Only** | View dashboards, conversations, transcripts. No edits. |
| **Chatlink** / **Webchat** | Service-account roles used by embedded chat widgets — minimum scopes to start a conversation and send messages. |
| **Customer-Journey** | Service-account role for journey backfill and customer-history sync. |
| **Infrastructure-Manager** | Platform-team role that spans environment and integration management. |

The exact set varies by deployment — your tenant may have additional roles tailored to your organization's structure.

## Creating a role

<Steps>
  <Step title="Click Add Role">
    Opens the role editor.
  </Step>

  <Step title="Name it">
    Pick a name that describes the role's purpose (e.g., "QA Reviewer", "Campaign Operator").
  </Step>

  <Step title="Assign scopes">
    Tick each scope the role should grant. Scopes are grouped by domain (transcripts, flows, channels, etc.) — start narrow and expand as needed.
  </Step>

  <Step title="Save">
    The role is immediately available in the [Users](/users) page for assignment.
  </Step>
</Steps>

## Editing a role

Click a role's name to open the editor. Toggle scopes and click **Save**. Changes take effect on the next request for any user holding the role.

<Warning>Removing scopes from a role can lock currently-signed-in users out of pages they have open. Communicate before tightening a role that's in active use.</Warning>

## Deleting a role

Click the delete icon on the role row, then confirm.

<Note>Deleting a role detaches it from every user who holds it. Those users keep their other roles' permissions, but lose anything that was granted only by the deleted role. Check the [Users](/users) page for affected accounts before deleting.</Note>

## Assigning roles to users

Roles are assigned from the [Users](/users) page — edit a user, add or remove **Groups**, save. A user can hold any number of roles; their effective permissions are the union.

## Scopes naming convention

Scopes follow a `domain:resource:action` shape. Examples seen across the platform:

* `transcripts:list`, `transcripts:read`, `transcripts:update`
* `flows:config:files:upload`, `flows:config:files:delete`
* `test-scenarios:create`, `test-scenarios:results:read`
* `verified-caller-ids:list`, `verified-caller-ids:update`

The granular shape is intentional: it lets a role like "Read-Only Auditor" grant `transcripts:read` without granting `transcripts:update` or `flows:publish`.

***

## Related

<CardGroup>
  <Card title="Users" icon="users" href="/users">Assign these roles to operator accounts.</Card>
  <Card title="Personal Configuration" icon="user-gear" href="/personal-configuration">Per-user settings users can adjust themselves.</Card>
  <Card title="Environment" icon="sliders" href="/environment">Tenant config gated by these roles.</Card>
</CardGroup>


# Personal Configuration
Source: https://docs.dialai.ca/personal-configuration

Self-service settings each user controls for their own routing, concurrency, and transfer destinations

<Frame>
  <img alt="Personal Configuration page in light mode" />

  <img alt="Personal Configuration page in dark mode" />
</Frame>

**Personal Configuration** is the self-service page where every operator tunes how the platform routes conversations to them — their skills, their concurrency limits, and where transferred calls should land when they happen. Settings saved here take effect immediately for all new conversations.

## Accessing Personal Configuration

Navigate to **Monitor > Inbox > Personal** in the left sidebar.

## Skills

The **Skills** multi-select is how you declare what kinds of conversations you can handle. The routing engine matches every skill required by a handoff against the skills you've selected — only users whose skill set covers the request are eligible.

<Tip>Start broad. Selecting **Customer Assistance** alone makes you eligible for general handoffs. Add specialized skills like **Billing** or **Spanish** only when you're confident you can handle them — narrower selections make you eligible for fewer conversations.</Tip>

Skill definitions are tenant-wide and managed by admins under [Operations > Skills](/operations#skills). If a skill you need isn't in the dropdown, ask an admin to create it.

## Voice Calls

The **Voice Calls** toggle controls whether the router will send you voice conversations. Off means chat-only routing — useful when you're in a noisy environment or on a call already.

## Max Concurrent Chats

The maximum number of chat conversations the router will assign to you at once. Range 0–10.

| Scenario | Recommendation |
| - | - |
| Quiet hours, full attention available | Higher (3–5). |
| Live-calling and chatting simultaneously | Lower (1–2) so chat doesn't displace voice. |
| Trainee / first week | 1 — focus on quality before scaling. |

## Max Concurrent Emails

Same idea as Max Concurrent Chats, but for email conversations. Range 0–10. Email is typically slower than chat, so concurrency tends to be higher.

## Mobile Phone Number

Where a transferred call should reach you when you're away from your desk — PSTN destination for **Internal Contact** transfers steered at your skills. Use E.164 format (`+1 555 555 0123`); the country selector to the left of the textbox sets the dial code.

<Note>Calls only route here when a flow's Internal Contact transfer step matches a skill you've selected. The mobile number isn't used for routing customer calls directly — only for delivering transfers.</Note>

## SIP Trunk

The SIP destination for transferring calls to your desk phone or softphone. Numeric IDs and SIP URIs are both accepted.

If both Mobile Phone Number and SIP Trunk are set, the platform attempts the SIP trunk first and falls back to PSTN on failure.

## Saving

Click **Submit** at the bottom of the form. A "User Configuration Updated" toast confirms success. Changes apply to **new** sessions only — anything already routed to you keeps running with its original settings.

## Troubleshooting

| Symptom | Resolution |
| - | - |
| **Skill isn't in the dropdown.** | Ask an admin to create it under [Operations > Skills](/operations#skills). |
| **Transferred calls aren't reaching my mobile.** | Confirm the number is E.164, and that your carrier accepts inbound from your tenant's outbound carrier (some carriers block unfamiliar caller-IDs). |
| **The router keeps skipping me.** | Make sure your status is **Available** (top bar), Voice Calls is on if voice is being routed, and your skills cover the handoff requirements. |
| **Concurrency feels off.** | Remember Max Chats and Max Emails are separate counters — they don't share the cap. |

***

## Related

<CardGroup>
  <Card title="Operations: Skills" icon="screwdriver-wrench" href="/operations#skills">Where the skills you can select are defined.</Card>
  <Card title="Internal Contact" icon="phone" href="/internal-contact">How a flow transfers calls to a human via skill-matching.</Card>
  <Card title="Inbox" icon="inbox" href="/inbox">Where the conversations the router sends you appear.</Card>
</CardGroup>


# Points of Contact
Source: https://docs.dialai.ca/points-of-contact

Connect AI agents to phone numbers, SMS lines, email addresses, web widgets, legacy web chats, and Slack channels

<Frame>
  <img alt="Points of Contact Phone tab in light mode" />

  <img alt="Points of Contact Phone tab in dark mode" />
</Frame>

A **Point of Contact** (POC) is the bridge between a customer and a flow. It's the channel — phone number, SMS line, email address, web widget, legacy web chat, or Slack workspace — that customers reach the AI agent through. Each POC ties a channel to exactly one flow and the routing rules that control how interactions are distributed.

## Accessing Points of Contact

Navigate to **Agent > Points of Contact** in the left sidebar.

The page has a tab for each channel type: **Phone**, **SMS**, **Email**, **Web Widgets**, **Web (Legacy)** and **Slack**. It also has a **Verified Outbound Numbers** tab. The **Web Widgets** tab shows only when your role has the `web-widgets:list` permission. The **Verified Outbound Numbers** tab needs `verified-caller-ids:list`.

<Note>To get new phone numbers or email addresses provisioned, consult your account representative. Only authorized contact points can be added.</Note>

## Channel tabs

Each tab shows a table of configured POCs with the columns relevant to that channel.

### Phone

Voice POCs route incoming phone calls to a flow.

| Column | What it shows |
| - | - |
| **Friendly Name** | An internal label (e.g., "Main Support Line"). |
| **AI Phone Number** | The number assigned to the AI agent. |
| **Flow** | The flow this number runs. |
| **AI Handle / Mode** | Routing mode and AI-handled percentage (e.g., "On (100%)"). |
| **Fallback Phone Number** | Where calls go when the AI does not handle them. |

### SMS

<Frame>
  <img alt="SMS tab in light mode" />

  <img alt="SMS tab in dark mode" />
</Frame>

SMS POCs route text messages to a flow. Each row shows Friendly Name, AI Phone Number, and Flow.

### Email

<Frame>
  <img alt="Email tab in light mode" />

  <img alt="Email tab in dark mode" />
</Frame>

Email POCs handle inbound mail. Additional columns:

* **Email** — the address customers email.
* **Status** — health indicator for the email connection (e.g., **Healthy**).
* **Health Check** — runs a connectivity check against Microsoft Graph or SendGrid.
* **Display Name** — the name shown in the agent's outgoing replies.
* **Handling Mode** — how inbound mail is processed (e.g., **Always Agent**).

### Web Widgets

<Frame>
  <img alt="Web Widgets tab in light mode" />

  <img alt="Web Widgets tab in dark mode" />
</Frame>

A web widget puts a chat with a flow on your own website, with a launcher in the corner of each page. This is the way to put chat on a new site. Each row shows the **Status**, the **Widget** name and its flow, the **Visitors** mode, the **Allowed sites** and when it was **Updated**. Click **Create Widget** to add one.

See [Web Widgets](/web-widgets), [Widget appearance](/web-widget-appearance) and [Signed-in visitors](/web-widget-sign-in).

### Web (Legacy)

<Warning>The legacy web chat (chat links) is deprecated. Chat links still work for now. For a new site, use [Web Widgets](#web-widgets).</Warning>

<Frame>
  <img alt="Web tab in light mode" />

  <img alt="Web tab in dark mode" />
</Frame>

Legacy web POCs are chat links you embed on a site. Each row shows the **Chat Code** (a UUID used in the embed snippet), the **Flow** it runs, and the **Voice** assignment (used when the chat supports voice input).

See [iframe integration](/iframe-integration) and [script tag integration](/script-tag-integration) for how to embed a legacy web POC.

### Slack

Slack POCs connect a flow to a Slack workspace. Click **Create Point of Contact** to add one; the create flow walks you through Slack OAuth.

## Creating a POC

Click **Create Point of Contact** in the top-right and pick the channel type. Required fields vary by channel:

* **Friendly Name** — internal label.
* **Channel Type** — Phone, SMS, Email, Web, or Slack. **Web** makes a legacy web chat link.
* **Flow** — the flow this POC routes to.
* **Phone Number** / **Email** / **Chat Code** — the channel-specific identifier.
* **Environment** — Production or Internal Testing.
* For voice channels: **Speech to Text Runner**, **Speech to Text Model**, **Speech to Text Endpointing**, **Voice**, **Background Noise**.

<Note>To create a web widget, open the **Web Widgets** tab and click **Create Widget**. See [Create a widget](/web-widgets#create-a-widget).</Note>

## Editing a POC

Click the edit (pencil) icon on a row. The Edit Configuration page has three tabs.

### Details

<Frame>
  <img alt="Edit POC Details tab in light mode" />

  <img alt="Edit POC Details tab in dark mode" />
</Frame>

The AI Phone Number is read-only; everything else is editable:

* **Friendly Name** — internal label.
* **Used For** — Production or Internal Testing.

### Routing

<Frame>
  <img alt="Edit POC Routing tab in light mode" />

  <img alt="Edit POC Routing tab in dark mode" />
</Frame>

Controls how incoming interactions are distributed.

* **Routing Mode** — `On` or `Schedule`.
  * **On**: AI is always active. Configure **AI Handle Percentage** (0-100%) to split traffic between AI and fallback. The remaining percentage transfers to the **Fallback Phone Number**.
  * **Schedule**: AI is active only during configured time windows. Click **Edit Schedule** to open the schedule editor — see [Schedule](/schedule).
* **Fallback Phone Number** — where unhandled calls go.

### Variants

<Frame>
  <img alt="Edit POC Variants tab in light mode" />

  <img alt="Edit POC Variants tab in dark mode" />
</Frame>

Variants let you A/B test multiple flow configurations on the same POC. Each variant has:

* **Handle Percentage** — share of calls routed to this variant. Variants must sum to 100%.
* **Draft Flow** — the flow this variant runs.
* **Version** — a specific published version. Leave empty to track the draft (any edit takes effect immediately).
* **Voice** — synthetic voice for this variant.
* **Speech to Text Runner** / **Model** / **Endpointing** — voice transcription settings.
* **Background Noise** — ambient call center sounds during voice calls.

Use **Add variant** to create a new variant; the `×` button removes one.

### Rollouts

Rollouts automate the variant split over time, so changing a live flow doesn't have to be all-or-nothing, and doesn't require you to nudge percentages by hand every morning.

A rollout shifts traffic from your current variant to a new one on a schedule you choose: start the new flow version at a small share of calls (say 10%) and let the platform ramp it automatically to 100% over the period you set. Every change proves itself on a small slice of real traffic before it goes wide.

* **Start small.** The starting percentage is your safety margin: the first calls on the new variant are the ones to review.
* **Watch as it ramps.** Use [Conversations](/conversations) filters to compare the variants while the rollout is running.
* **Interrupt anytime.** Editing the variant percentages directly stops the automatic ramp, which is handy as an instant rollback if something looks wrong.

## Tips

* **Friendly names matter.** "Main Support Line" beats "+1 (555) 555-0101" when you have 30 POCs.
* **Roll out gradually.** Use a [Rollout](#rollouts) to ramp a new flow version from 10% to 100% automatically, or nudge the **AI Handle Percentage** slider by hand.
* **Test before going live.** Set **Used For** to **Internal Testing** while iterating; flip to **Production** when ready.
* **Plan fallback explicitly.** Every Phone POC needs a fallback number — don't leave it empty.

***

## Related

<CardGroup>
  <Card title="Schedule" icon="calendar" href="/schedule">Set time-of-day routing windows.</Card>
  <Card title="Agent voices" icon="volume-high" href="/agent-voice">Pick the AI's synthetic voice.</Card>
  <Card title="Web Widgets" icon="comment" href="/web-widgets">Put chat on your website.</Card>
  <Card title="Outbound" icon="phone-arrow-up-right" href="/outbound">Run outbound campaigns from a verified caller ID.</Card>
</CardGroup>


# Schedule
Source: https://docs.dialai.ca/schedule

Configure when each phone POC is active and how much AI handles

<Frame>
  <img alt="Schedule page in light mode" />

  <img alt="Schedule page in dark mode" />
</Frame>

The **Schedule** page gives you a unified view of when every phone POC in your tenant is active. Configure business hours, after-hours coverage, weekend handling, and AI-vs-human ramp percentages — all from a single calendar.

## Accessing Schedule

Navigate to **Agent > Schedule** in the left sidebar.

## What's on the page

* **Filters panel (left)** — checkboxes for each phone POC, each showing its current routing mode and AI handle percentage (e.g., `ON • 100% AI handle`). Toggle individual numbers to focus the calendar, or use **All phone numbers** to show everything.
* **Calendar (center)** — colored bars showing each POC's active windows. Switch views with the **Month**, **Week**, **Day**, **Agenda** tabs. Use **Today**, **Back**, **Next** to navigate between time periods.
* **Schedules panel (right)** — a summary of total and active schedule windows for the currently selected POCs.

## Routing modes

Every phone POC has a **Routing Mode** set on its [Points of Contact > Edit > Routing](/points-of-contact) tab:

* **On** — AI is always active. The handle percentage applies at every hour of every day.
* **Schedule** — AI is active only during the configured time windows. Outside those windows, AI handle drops to 0% and calls transfer to the fallback number.

Only POCs in **Schedule** mode show colored windows on the Schedule page. POCs in **On** mode appear as a full bar at their constant handle percentage.

## Editing a schedule

Two entry points:

<Steps>
  <Step title="From this page">
    Click a phone POC's bar in the calendar — it opens the schedule editor pre-filtered to that POC.
  </Step>

  <Step title="From a Point of Contact">
    Edit the POC, switch to the **Routing** tab, set **Routing Mode** to **Schedule**, then click **Edit Schedule**. See [Points of Contact](/points-of-contact#routing) for the full editor walkthrough.
  </Step>
</Steps>

## Creating a schedule window

In the schedule editor:

1. Click **+ New Event** (or drag-select on the calendar to pre-fill the time range).
2. Fill in:
   * **Name** — what this window is for (e.g., "Business Hours", "Weekend Coverage").
   * **AI Handle Percentage** — share of calls AI handles during this window (0–100%).
   * **From** / **To** — the day and time range. Schedule windows repeat weekly.
   * **Enabled** — uncheck to disable a window without deleting it.
3. Click **Add**.

### Rules and gotchas

* Each window repeats every week.
* Same-day windows require end-time after start-time.
* Overlapping windows on the same POC aren't allowed.
* Outside any active window, AI handle is **0%** and calls transfer to the fallback number.

### Common patterns

| Pattern | From | To |
| - | - | - |
| Weekday business hours | Monday 9:00 AM | Friday 5:00 PM |
| After-hours coverage | Saturday 5:00 PM | Monday 8:00 AM |
| Night shift | Monday 8:00 PM | Tuesday 5:00 AM |

## Calendar views

* **Month** — the whole month at a glance; good for spotting coverage gaps.
* **Week** — hour-resolution view of a single week; the default for active configuration.
* **Day** — focus on one day; useful for densely-scheduled POCs.
* **Agenda** — list view of upcoming windows.

## Tips

* **Default to Schedule mode for production POCs.** It makes business hours explicit and gives you a calendar you can audit.
* **One window per shift, not one per day.** Use a single Monday-9am→Friday-5pm window instead of five identical daily windows.
* **Disable, don't delete.** Toggle **Enabled** off when an emergency change is needed; that way you can re-enable later without re-typing the times.

***

## Related

<CardGroup>
  <Card title="Points of Contact" icon="phone" href="/points-of-contact">Set Routing Mode and Fallback per POC.</Card>
  <Card title="Operations" icon="gear" href="/operations">Tenant-wide ops: skills, internal contacts, do-not-call.</Card>
</CardGroup>


# Script Tag Integration (Legacy)
Source: https://docs.dialai.ca/script-tag-integration

Instructions on how to integrate Dial AI into your application using a simple script tag.

<Warning>
  The customer chat on this page (`renderModal` and a chat ID) is the legacy web chat. It uses a chat link from the **Web (Legacy)** tab of **Points of Contact**. For a new site, use [Web Widgets](/web-widgets). Chat links still work for now, but they are deprecated. This page stays for sites that use a chat link today.

  Web Widgets do not replace the [internal-agent embed](#internal-agent-embed-page-aware-integrations) (`renderInternalAgentApp`) on this page.
</Warning>

Dial AI can be embedded in your application via a single script tag. This method gives you a floating chat button (bottom-right) that opens the AI agent in a modal when clicked — your visitors talk to the agent without leaving your application.

## Prerequisites

Before you begin, you'll need:

* A Dial AI chat ID (see [Creating a Chat ID](#creating-a-chat-id) below)
* The backend URL for your Dial AI instance
* A unique anchor ID for mounting the chat button

## Creating a Chat ID

A **chat ID** is the UUID of a Web Point of Contact. Create one under **Agent > Points of Contact > Web (Legacy)** — see [iframe integration](/iframe-integration#creating-a-chat-link) for the step-by-step.

<Frame>
  <img alt="Web POC Generate tab in light mode" />

  <img alt="Web POC Generate tab in dark mode" />
</Frame>

## Basic Integration

Add the following to your HTML file, replacing the placeholder values as needed:

1. Load the widget script in your `<head>` tag:

```html theme={null}
<script defer type="module" src="https://cdn.dialai.ca/v1/esm/{version}/dial-ai.js"></script>
```

Replace `{version}` with a specific release version (e.g. `0.0.1329`) from the [versions manifest](https://cdn.dialai.ca/v1/versions.json).

2. Add the mount point and initialization script:

```html theme={null}
<!-- Mount point for the chat widget (renders in the bottom right) -->
<span id="your-anchor-id"></span>

<script>
document.addEventListener("DOMContentLoaded", function() {
    window.renderModal("your-anchor-id", {
        iconUrl: "https://www.yourdomain.com/path/to/icon.svg",
        chatId: "YOUR_CHAT_ID",
        backendUrl: "https://your-dialai-instance.com"
    });
});
</script>
```

## Configuration Options

The `renderModal` function accepts the following configuration options:

* `iconUrl` (string, required): URL to the icon that will be displayed in the chat button
* `chatId` (string, required): Your unique Dial AI chat identifier
* `backendUrl` (string, required): The base URL of your Dial AI instance
* `brandVariants` (object, optional): Custom color scheme for the chat interface (see [Brand Variants](#brand-variants) below)

## Brand Variants

By default, the widget uses the theme configured for the chat link's tenant. If you need to override this to match your site's branding, pass a `brandVariants` object with color values on a scale from 10 (darkest) to 160 (lightest):

```js theme={null}
brandVariants: {
    10: "#001018",
    20: "#002030",
    30: "#003049",
    40: "#004062",
    50: "#00507a",
    60: "#006093",
    70: "#0070ab",
    80: "#0080c4",
    90: "#0090dc",
    100: "#00a1f5",
    110: "#10adfe",
    120: "#2bb6ff",
    130: "#45bfff",
    140: "#60c8ff",
    150: "#7ad1ff",
    160: "#95dafe"
}
```

Omit `brandVariants` to use the tenant's default theme.

## CORS Configuration

The widget script is served from our CDN with permissive CORS headers (`Access-Control-Allow-Origin: *`), so it can be loaded from any domain without additional configuration.

## Troubleshooting

* If the chat button doesn't appear, check your browser's console for any error messages
* Ensure the anchor element with the specified ID exists in the DOM when the script runs
* Make sure the chat ID and backend URL are correct

## Example Implementation

Here's a complete example of how to integrate the chat button into a simple HTML page:

```html theme={null}
<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>My App with Dial AI</title>
    <script defer type="module" src="https://cdn.dialai.ca/v1/esm/0.0.1329/dial-ai.js"></script>
</head>
<body>
    <h1>Welcome to My App</h1>
    <p>Click the chat button in the bottom right to get help.</p>

    <!-- Mount point for the chat widget -->
    <span id="dial-ai-button"></span>

    <script>
    document.addEventListener("DOMContentLoaded", function() {
        window.renderModal("dial-ai-button", {
            iconUrl: "https://cdn.dialai.ca/v1/esm/0.0.1329/favicon.ico",
            chatId: "00000000-0000-0000-0000-000000000000",
            backendUrl: "https://demo.dialai.ca"
        });
    });
    </script>
</body>
</html>
```

## Versions

The widget is hosted on our CDN at `https://cdn.dialai.ca/v1/esm/{version}/dial-ai.js`. You can find available versions in the [versions manifest](https://cdn.dialai.ca/v1/versions.json). Pin to a specific release version to avoid unexpected changes.

## Internal-Agent embed: page-aware integrations

In addition to the customer-facing chat (`renderModal`), the same bundle exposes `renderInternalAgentApp` — used to embed an **internal agent** (back-office assistant) into your own internal tooling. This embed exposes two host-page hooks that let the agent become aware of, and act on, the page it's running inside.

### `onNavigate` — let the agent drive page navigation

When an agent tool result includes the field `X-DialAI-Navigation-Path`, the widget invokes your `onNavigate(path)` callback. Use this to wire the agent into your app's router so the agent can say "I've opened the customer record for you" and actually open it.

```html theme={null}
<div id="agent-app"></div>
<script defer type="module" src="https://cdn.dialai.ca/v1/esm/{version}/dial-ai.js"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    window.renderInternalAgentApp("agent-app", {
      tenantId: "your-tenant",
      backendUrl: "https://your-instance.dialai.ca",
      onNavigate: (path) => {
        // Route using your framework, e.g.:
        // window.history.pushState({}, "", path); router.refresh();
        window.location.href = path;
      }
    });
  });
</script>
```

The callback fires exactly once per tool completion that contains a navigation path. The path is a string — the host decides how to interpret it (absolute URL, relative route, anchor). If `onNavigate` is omitted, navigation results are silently ignored.

### `onMessageSend` — inject page context with every user message

Before each user message is sent to the agent, the widget calls your `onMessageSend()` callback. Return `{ contextAdditions: string }` and the string is appended to the outgoing user message after a delimiter, so the agent can see what's currently on the page without the user having to type it.

```html theme={null}
<div id="agent-app"></div>
<script defer type="module" src="https://cdn.dialai.ca/v1/esm/{version}/dial-ai.js"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    window.renderInternalAgentApp("agent-app", {
      tenantId: "your-tenant",
      backendUrl: "https://your-instance.dialai.ca",
      onMessageSend: () => ({
        contextAdditions: [
          `Current page URL: ${window.location.href}`,
          `Selected record ID: ${document.querySelector("[data-selected-id]")?.dataset.selectedId ?? "none"}`,
          `Filters: ${JSON.stringify(window.__appState?.filters ?? {})}`
        ].join("\n")
      })
    });
  });
</script>
```

The widget appends the returned string to the user's message using a `<!-- dialai-context -->` marker; the agent sees both the original user input and the appended context.

<Warning>The callback must be **synchronous** — return a value immediately, don't await anything. Use cached/derived values that are already in memory.</Warning>

Common things to pass via `contextAdditions`:

* The current route, page title, or page-level entity ID.
* The currently-selected item (row in a table, item in a list).
* Active filters or search terms the user has applied.
* The viewport-visible portion of a long document, if the agent should "see what the user sees".

### When to use this vs the chat-link iframe

| | `renderInternalAgentApp` | Customer chat (`renderModal` / iframe) |
| - | - | - |
| Audience | Your internal staff. | Your end customers. |
| Auth | Operator-authenticated session (the host page is already signed in). | Anonymous; uses a Web POC chat link UUID. |
| Page hooks | `onNavigate`, `onMessageSend`. | None — chat is sandboxed in an iframe. |
| Conversation persistence | Backed by the internal-agent SSE stream. | One-shot chat session per visitor. |

Pick `renderInternalAgentApp` when you're building an in-house tool where the agent should *do things* in your app on the user's behalf. Pick `renderModal` (or the [iframe](/iframe-integration)) when you're putting a customer-facing AI agent on a public page.

## ESM vs UMD

The widget is available in two module formats:

* **ESM** (recommended) — loaded with `<script type="module">`. This is the current format used for all new releases (`/v1/esm/{version}/dial-ai.js`).
* **UMD** (legacy) — loaded with a plain `<script>` tag. Older releases (pre-0.0.1323) were published in UMD format and remain available at `/v1/umd/dial-ai-{version}.umd.js` for backward compatibility.

New integrations should use the ESM format. Existing UMD integrations will continue to work but will not receive new releases.


# Testing Flows
Source: https://docs.dialai.ca/testing-flows

Validate AI agent flows before publishing — quick chat sandbox, simulated platforms, and reusable test scenarios

<Frame>
  <img alt="Flow editor canvas with Live Test panel in light mode" />

  <img alt="Flow editor canvas with Live Test panel in dark mode" />
</Frame>

Testing a flow before you ship it is the difference between an agent that works and an agent that drifts. The platform has three tools for this, in roughly increasing order of effort:

1. **Live Test** — a one-off interactive conversation, useful for quick "does this work?" checks while editing.
2. **Test Platform** — emulate a specific channel (Voice, SMS, Web, Email) to verify channel-specific behavior.
3. **Test Scenarios** — recorded conversations with assertions, replayable across flow versions to catch regressions.

This page covers all three.

## Live Test (chat sandbox)

The fastest way to talk to the flow you're editing — built into the right side of the flow editor. When the panel first opens, you pick **Chat Using Text** or **Voice Using Voice** to start a conversation against the current draft.

<Steps>
  <Step title="Open the flow editor">
    From the **Flows** page, click any flow's **Edit** button.
  </Step>

  <Step title="Pick a modality in the Live Test panel">
    On the right side, the **Live Test** panel asks "Chat Using Text" or "Voice Using Voice". Chat is text-only and faster to iterate. Voice exercises the speech pipeline end-to-end.
  </Step>

  <Step title="Send a message">
    Type as if you were the customer. The agent responds using the current draft of the flow.
  </Step>

  <Step title="Inspect what happened">
    The transcript shows function calls, state transitions, and the agent's thought process alongside each turn. Use this to confirm the right functions are firing on the right inputs.
  </Step>
</Steps>

<Frame>
  <img alt="Chat sandbox conversation in light mode" />

  <img alt="Chat sandbox conversation in dark mode" />
</Frame>

Live Test always runs against the current draft, so any edit you save is immediately reflected on the next message. No need to publish.

## Test Platform

The chat sandbox runs in a neutral text mode. Real conversations happen on specific channels — voice has different latencies and phonetic considerations than SMS; email is async and quote-aware. **Test Platform** runs the same draft flow but emulates a specific channel.

<Steps>
  <Step title="Open Test Platform">
    From the **Flows** page, click the three-dot menu on the flow card and select **Test Platform**.
  </Step>

  <Step title="Pick a channel">
    Voice, SMS, Web, or Email. Each applies the platform-specific behavior the runtime would apply on a live conversation.
  </Step>

  <Step title="Run through scenarios">
    Type messages as the customer. The agent responds in the chosen channel's style — voice-style speech for Voice, short messages for SMS, formatted body text for Email.
  </Step>
</Steps>

### Channel-specific things to watch

| Channel | Watch for |
| - | - |
| Voice | The agent spells back names digit-by-digit / letter-by-letter when needed; numbers are read naturally (twenty-two, not 2-2). |
| SMS | Messages are short. Long structured responses get awkward on a phone screen. |
| Web | Formatting renders (Markdown, lists, links). |
| Email | Quotes and threading work; the agent's tone reads as written, not spoken. |

To input spaced/spelled-out characters in voice tests, type each letter separated by spaces — `B r i a n` — and the runtime will treat it as a spelled name.

## Test Scenarios

The chat sandbox and Test Platform are interactive — good for exploring, bad for catching regressions. **Test Scenarios** are recorded conversations with assertions: you walk through a flow once, save the scenario, and the platform can replay it against any future flow version to confirm behavior is stable.

### Creating a scenario

<Steps>
  <Step title="Open Test Scenarios">
    On the flow editor, open the **Test Scenarios** panel.
  </Step>

  <Step title="Record a conversation">
    Click **New scenario**, walk through a representative conversation in the sandbox. Each turn is captured along with the agent's response, function calls, and state transitions.
  </Step>

  <Step title="Add assertions">
    On each turn, mark which assertions matter: a specific state was reached, a specific function was called, a specific event was emitted, a specific tag was set, the agent's reply contained certain phrasing.
  </Step>

  <Step title="Categorize and save">
    Assign the scenario to a category (e.g., "Happy path", "Edge cases", "Compliance"). Save.
  </Step>
</Steps>

### Running scenarios

The Test Scenarios panel lists every saved scenario. Click **Run** on one to replay it; click **Run all** to replay the entire category. Each run shows pass/fail per assertion alongside the full replay transcript.

### Versioned results

Test results are tracked per **flow version**. When you publish a new version of a flow, run all scenarios — the platform records the result against that version. The history view shows which scenarios pass against which versions, making it easy to see when a regression was introduced and against which change.

This is the safety net for editing a flow that's already live. As long as your scenarios cover the conversations you care about, you can edit confidently — failing assertions will catch breakage before it reaches customers.

## What to test before publishing

A minimal test plan for any flow heading to production:

* **Happy path** for every primary intent your flow handles.
* **Disambiguation** — what happens when a function returns multiple matches or no matches.
* **Out-of-scope requests** — the customer asks for something this flow can't do; does the agent transfer or escalate gracefully?
* **Emergencies** if your domain has them — fire, gas leak, medical, threats of harm. The agent must route correctly.
* **Channel-specific quirks** — at minimum a smoke test on each channel the flow will run on.
* **Language fallback** if the flow is single-language but customers may try another.

Convert each into a Test Scenario so future edits can't regress them silently.

***

## Related

<CardGroup>
  <Card title="Building your first flow" icon="pen-to-square" href="/first-flow">Where testing fits in the build process.</Card>
  <Card title="Designing thoughts" icon="lightbulb" href="/thoughts">Most flow bugs are thought bugs — fix them here.</Card>
  <Card title="Flow configuration" icon="sliders" href="/flow-configuration">Configure call review criteria that complement scenario testing.</Card>
</CardGroup>


# Theme
Source: https://docs.dialai.ca/theme-editing

Customize your tenant's branding — display name, logos, and color palette

<Frame>
  <img alt="Theme settings page in light mode" />

  <img alt="Theme settings page in dark mode" />
</Frame>

The **Theme** page controls the tenant's visible branding — the display name, the logos that appear in the app and on the legacy customer chat pages, the brand colours, the per-handoff destination icons, and the color palette that drives buttons, badges, and links.

## Accessing Theme

Navigate to **Settings > Theme** in the left sidebar.

## Tenant display name

The **Tenant display name** field at the top of the page sets the name shown in the browser title bar, the tenant switcher, and any place the product references the tenant by name.

<Steps>
  <Step title="Edit the field">
    Type the new display name.
  </Step>

  <Step title="Save">
    The **Save** button enables once the value changes.
  </Step>
</Steps>

## Logos

Every logo slot accepts a separate **Light mode** and **Dark mode** image, so your branding matches whichever theme the viewer has selected. Click the **Upload** button under each slot to pick a file (PNG or JPEG, up to 2 MB).

### Application header

The logo shown in the top-left of the platform's main navigation bar — visible on every page after sign-in.

### Brand colours

The **Brand colours** section has two colours: **Primary colour** and **Accent colour**. Documents that the platform exports for your organization use them, such as the deployment status report. The light **App header logo** is the logo on those documents.

The **Primary colour** is also the default accent colour of each [web widget](/web-widgets). A widget that overrides its accent does not use it. See [Widget appearance](/web-widget-appearance#where-the-default-colours-come-from).

### Customer chat page

Two surfaces, both shown on the legacy chat page that **end customers** interact with (not the operator UI):

* **Chat header icon** — small icon shown in the chat page's header bar.
* **Sidebar header logo** — full logo shown at the top of the chat page sidebar.

<Tip>The sidebar header logo is the most visible branding to your customers — invest the most polish here.</Tip>

<Note>These logos show only on the legacy web chat (chat links on the **Web (Legacy)** tab). A [web widget](/web-widgets) shows no tenant logo. Its look comes from its own [appearance](/web-widget-appearance).</Note>

## Handoff icons

When a flow hands a conversation off to another destination (a queue, an external integration, a human agent group), the destination appears in the [Conversations](/conversations) table under the **Status** column. The Handoff icons section lets you customize the icon shown for each destination.

<Note>Only handoff destinations that have already appeared in real transcripts can be customized — the platform discovers destinations from transcript history. If you don't see a destination listed, drive a conversation that hands off to it first, then return here.</Note>

## Color palette (Brand)

The brand palette drives primary buttons, chat bubbles, link colors, and selected branded UI elements. It is a 16-step ramp from `10` (darkest) to `160` (lightest), with `80` representing the primary brand color.

### Example palette

```json theme={null}
{
  "10": "#011821", "20": "#045066", "30": "#04566c", "40": "#056078",
  "50": "#00647d", "60": "#00647d", "70": "#017490", "80": "#0088AA",
  "90": "#0194b7", "100": "#08b1da", "110": "#0fc1ec", "120": "#43d8fd",
  "130": "#47d6fa", "140": "#84e9ff", "150": "#a3f8ff", "160": "#eefcff"
}
```

### Generating a palette

A practical way to build a coordinated palette from a new primary color is to provide an example like the one above to an LLM along with your new `80` value and ask for a matching ramp.

### Applying a palette

Themes are applied per tenant via the API:

```http theme={null}
PUT /api/v1/frontend/config/theme/update
X-Organization-Id: {your-tenant}
Authorization: Bearer {token}
Content-Type: application/json

{"10": "#...", "20": "#...", ..., "160": "#..."}
```

For the underlying theme variables and what each one drives, see [Fluent UI 9's theme documentation](https://react.fluentui.dev/?path=/docs/theme-colors--docs) — the platform's UI is built on Fluent UI 9, so every variable from that catalog is accepted in the body.

### Advanced — per-mode overrides

To override individual variables for light and dark mode separately, prefix the key with `light-` or `dark-`:

```json theme={null}
{
  "80": "#E10D11",
  "light-colorNeutralStroke2": "#708090",
  "dark-colorNeutralStroke2": "#434D54"
}
```

<Warning>Custom theme overrides can break contrast and readability. Test against WCAG contrast guidelines before rolling a change tenant-wide.</Warning>

### Commonly tuned variables

| Variable | What it drives |
| - | - |
| `colorNeutralBackground1` | Main background. |
| `colorNeutralBackground1Selected` | Customer chat bubbles, user tags, card grid items. |
| `colorNeutralBackground3` | Secondary background panels. |
| `colorNeutralForeground1` | Primary text. |
| `colorNeutralForeground3` | Secondary text. |
| `colorNeutralStroke2` | Main border color. |
| `colorBrandForegroundLink` | Link color. |

***

## Related

<CardGroup>
  <Card title="Environment" icon="sliders" href="/environment">Manage tenant-wide environment variables and secrets.</Card>
  <Card title="Users" icon="users" href="/users">Onboard operators who will see this branding.</Card>
  <Card title="Widget appearance" icon="palette" href="/web-widget-appearance">The look of a web widget, with the brand colour as its accent.</Card>
  <Card title="Points of Contact: Web (Legacy)" icon="globe" href="/points-of-contact#web-legacy">The legacy chat surface the logos appear on.</Card>
</CardGroup>


# Designing Thoughts
Source: https://docs.dialai.ca/thoughts

Write the instructions that drive how your AI agent behaves at every state

<Frame>
  <img alt="State editor with Thought tab in light mode" />

  <img alt="State editor with Thought tab in dark mode" />
</Frame>

A **Thought** is the natural-language instruction attached to a state in a flow. It tells the AI agent what to do here: what to say, what data to collect, which functions to call, how to handle edge cases. Thoughts are the single biggest lever you have on agent behavior — well-written thoughts produce predictable, useful conversations; vague ones produce drift.

This page is the field guide for writing thoughts that work.

## Anatomy of a thought

Every thought benefits from the same backbone:

1. **Context.** One sentence on the agent's role at this point in the conversation. *"You are helping the customer book a meter exchange appointment."*
2. **Objective.** What the agent must accomplish before this state can transition. *"Confirm the customer's service address."*
3. **Trigger.** When this thought applies, if it's not just "always". *"If the customer provides an address that matches multiple accounts…"*
4. **Conversation moves.** Specific things to say. Quoted phrases when wording matters. *"Say: 'I've found your account. Would you like to schedule the earliest available appointment?'"*
5. **Function calls.** Which functions to call and what parameters they need. Reference functions by their exact name.
6. **Error handling.** What to do when a function fails, the customer goes off-script, or there are multiple matches.
7. **Special cases.** Anything unusual — emergency routing, accessibility accommodations, regulatory requirements.

## Voice and phrasing

**Use strong directives.** "Must" and "will" produce more reliable behavior than "should" and "can".

**Avoid telling the agent what *not* to do.** Negative instructions can backfire. Instead, describe the action you want.

> ❌ "Do not ask for the customer's name again."
>
> ✅ "After you've received the customer's name, move to confirming their account."

**Quote exact phrasing in single quotes** when the wording matters — for greetings, legally required disclosures, brand-specific language. The agent will say what's inside the quotes verbatim.

**Use placeholder variables in brackets** for values that should be filled in: `[Customer Name]`, `[Service Provider]`.

## Multi-channel branching

Voice and text conversations need different instructions. Be explicit:

```
If the customer is speaking over the phone:
  Confirm the spelling of their name by asking, "How do you spell that?"

If the customer is speaking over text:
  Skip the spelling confirmation and proceed to the next step.
```

For voice: spell numbers digit-by-digit, spell street names letter-by-letter, ask for confirmation. For text: trust what the customer typed and move on.

## Function references

Reference functions by their exact registered name and call out what they need:

> "Call the `Get Account By Address` function. Before calling, confirm the street number, street name, and ZIP code with the customer."

If a function emits events that drive transitions, you generally do *not* need to mention the events in the thought — the flow editor handles routing.

## Don't do math in thoughts

LLMs are unreliable at arithmetic. Put any calculation in a function, call the function, then relay the result.

> ❌ "Add the installment amount to the current balance and tell the customer the total."
>
> ✅ "Call `Calculate Total Amount` with `InstallmentAmount` and `CurrentBalance`, then relay the result to the customer."

## Avoid embedded examples

Don't put example values inside thoughts — the agent may treat them as real data.

> ❌ "Confirm the customer's address (e.g., 123 Main Street, 90210)."
>
> ✅ "Confirm the customer's street number, street name, and ZIP code."

## Reference information block

When you need the agent to know facts that don't justify a function call, list them as a reference block:

```
Use the following information to answer customer questions:
- Appointments are scheduled with a 4-hour arrival window.
- Technicians require access to the meter and may shut off power briefly.
- For other assistance, customers can call +1-800-123-4567 (weekdays 7am–7pm).
```

Keep these blocks short — the agent has a limited attention budget for general context.

## Error handling

Every state that calls a function should declare what happens when the function fails or the customer goes off-script. Be specific:

* The **statement** or **trigger** that activates the fallback.
* The exact **response** to give the customer.
* The **function** to call (or "end the conversation politely").
* The **escalation** if the function itself fails.

Worked example:

> **Customer issue:** Water leak.
>
> **Response:** "I understand there's a water leak. I'll connect you with our emergency support."
>
> **Function call:** `Transfer to Emergency`.
>
> **Escalation:** If the transfer fails, say "It seems I couldn't connect you. Please call our emergency line at \[Emergency Number] directly."

## Common pitfalls

| Symptom | Most likely cause | Fix |
| - | - | - |
| Agent uses phrasing you don't like | The thought describes the goal but not the exact words | Surround the wording you want with single quotes. |
| Agent keeps asking for spelling on SMS | The thought doesn't branch on channel | Add explicit "If voice / If text" instructions. |
| Agent forgets to call a function | Function isn't referenced by exact name, or isn't attached to the state | Verify the function is on this state's Functions list and reference it by name. |
| Agent gets math wrong | Calculation lives in the thought | Move the math into a function. |
| Agent leaks placeholder text | Examples in the thought | Replace examples with parameter names. |

## Thought template

A copy-paste skeleton for a typical initial state:

```text theme={null}
You are [Agent Name], an AI customer service representative for [Company Name]. You assist
customers with [purpose].

Start the conversation by introducing yourself and indicating that you are an AI assistant. Use
this greeting: 'Hi, this is [Agent Name], an AI assistant from [Company Name]. This call is
recorded for quality. How can I help today?'

You can assist with:
- [Task 1]
- [Task 2]
- [Task 3]

For anything else, transfer the customer using the `Transfer to Agent` function. If the transfer
fails, fall back to `Schedule Callback`.

Languages: You can assist customers in [supported languages]. If a customer requests another
language, inform them you can only assist in [supported languages].

If the customer mentions a safety emergency:
- Tell them their safety comes first and direct them to call 9-1-1.
- For non-immediate safety concerns (outages, gas leaks), use the `Transfer to Emergency Line`
  function.

Caller ID:
- If the system returns an address, confirm it with the customer before using it.
- If not, ask the customer for their address.

Address collection rules:
- For voice calls, ask the customer to spell street names letter-by-letter.
- For text chats, accept the address as typed.
- For numerical street names (e.g., "22nd Street"), read it back without spelling each digit.
- Convert spelled-out numbers ("twenty-second street") to digits.

If at any point the customer is ready to end the conversation, confirm there is nothing else and
end politely.
```

***

## Related

<CardGroup>
  <Card title="Functions and events" icon="code" href="/functions-and-events">What functions can do and how to declare events.</Card>
  <Card title="Flow configuration" icon="sliders" href="/flow-configuration">Settings that affect every state.</Card>
  <Card title="Testing flows" icon="flask" href="/testing-flows">Validate your thoughts before publishing.</Card>
</CardGroup>


# Users
Source: https://docs.dialai.ca/users

Create, edit, and de-provision tenant operator accounts

<Frame>
  <img alt="Users page in light mode" />

  <img alt="Users page in dark mode" />
</Frame>

The **Users** page is where you onboard, edit, and de-provision the operators who use the platform — the people who monitor conversations, build flows, take handoffs, and run campaigns. Every user belongs to one or more roles, and roles determine what they can do.

## Accessing Users

Navigate to **Settings > Users** in the left sidebar.

## What's on the page

The users table lists every operator account in your tenant.

| Column | What it shows |
| - | - |
| **Name** | Display name. Searchable from the filter. |
| **Email** | Login email. Searchable from the filter. |
| **Status** | Current availability — `Available`, `Busy`, `Offline`, or `Disconnected` (websocket dropped unexpectedly). |
| **Groups** | Role badges (e.g., **DialAiAdmin**, **Maintainer**, **Read-Only**). |
| **Edit** | Open the edit drawer for this user. |
| **Delete** | Soft-delete the account after confirmation. |

Top-right actions:

* **Filter** — narrow the list by name, email, status, or role.
* **Bulk Add Users** — onboard many users at once via CSV.
* **Create User** — open the single-user create form.

## Creating a user

<Steps>
  <Step title="Click Create User">
    Opens the create form.
  </Step>

  <Step title="Fill in name and email">
    The email must be unique within the tenant. An invite email with a password-set link is sent automatically.
  </Step>

  <Step title="Assign at least one group">
    Roles drive access. See [Permissions](/permissions) for what each role allows.
  </Step>

  <Step title="Save">
    The user appears in the table immediately.
  </Step>
</Steps>

## Bulk onboarding

Click **Bulk Add Users** to provision many accounts at once. Useful when standing up a new team or seeding a fresh tenant.

## Editing a user

Click the edit (pencil) icon on a row. The drawer exposes:

* **Groups** — add or remove role memberships.
* **Status** — manually set availability.
* **CSR User** — flag this account as a human agent eligible for routing.
* **Skills** — assign [Skills](/operations#skills) used to match handoffs to this user.
* **Voice Calls** — toggle whether voice calls can be routed to this user.
* **Max Chats / Max Emails** — concurrency caps (0–10 each).
* **Mobile Phone Number** — PSTN destination for transferred calls.

<Tip>To promote a temporary admin, just add the **DialAiAdmin** group. No re-invite required.</Tip>

## De-provisioning

<Steps>
  <Step title="Click the delete icon">
    The confirmation dialog asks you to type the user's email to confirm.
  </Step>

  <Step title="Confirm">
    The account is soft-deleted — historical reports keep referencing it, but the user can no longer sign in.
  </Step>
</Steps>

## Read-only fields

Username, first name, last name, and email are immutable after creation. To change any of these, create a new account and de-provision the old one.

## What "Disconnected" means

The user's browser websocket closed without a clean sign-out (tab closed, network drop, sleep). They appear offline to the router until they re-open the app.

***

## Related

<CardGroup>
  <Card title="Permissions" icon="lock" href="/permissions">Roles, scopes, and what each role lets a user do.</Card>
  <Card title="Personal Configuration" icon="user-gear" href="/personal-configuration">What an individual user can tune for themselves.</Card>
  <Card title="Operations: Skills" icon="screwdriver-wrench" href="/operations#skills">Define the skills users select for routing.</Card>
</CardGroup>


# Widget Appearance
Source: https://docs.dialai.ca/web-widget-appearance

Give a web widget the look of your site with a preset, colour and shape overrides, a font, and a launcher style.

The appearance of a [web widget](/web-widgets) is a **preset** plus your **overrides**. A preset sets the full look. An override changes one value, such as the accent colour or the panel corners. Each value that you do not override comes from the preset.

You set the appearance on the dashboard, and each site that shows the widget gets it. The page that shows the widget cannot change the theme.

## Open the appearance editor

<Steps>
  <Step title="Open the widget">
    Go to **Agent > Points of Contact > Web Widgets** and click the widget.
  </Step>

  <Step title="Open the editor">
    On the **Appearance** card, click **Customize**. You need the `web-widgets:update` permission.
  </Step>

  <Step title="Change the look">
    Select a preset, then change the values on the tabs. The live preview shows each change.
  </Step>

  <Step title="Save">
    Click **Save**. To discard your changes, click **Cancel**.
  </Step>
</Steps>

When the editor is closed, the **Appearance** card shows a picture of the widget and a summary: **Preset**, **Light or dark**, **Accent**, **Font** and **Launcher**.

## Presets

The editor shows the presets in a gallery. Click a preset to select it.

<Frame>
  <img alt="The seven presets in a gallery. Classic is selected (light)" />

  <img alt="The seven presets in a gallery. Classic is selected (dark)" />
</Frame>

| Preset | The look |
| - | - |
| **Classic** | The widget's first look: an accent header, rounded bubbles and a soft shadow. This is the default. |
| **Glass** | Translucent panel that blurs the page behind it, with a glossy accent header. |
| **Plain** | The browser's own look: serif text, plain lines, no shadow and no bubbles. |
| **Swiss** | International style: black rules, square corners and one strong red. |
| **Bauhaus** | Primary colours, a black outline and a hard offset shadow. |
| **Paper** | Serif text on warm paper, ink-blue accents and letter-like outlined bubbles. |
| **Terminal** | A dark console in both schemes: monospace text, phosphor green and hard edges. |

Each preset meets the WCAG 2.1 AA contrast ratio (4.5:1) for its text, in light and in dark.

<Frame>
  <img alt="The chat panel of the widget with the Glass, Bauhaus and Terminal presets, side by side (light)" />

  <img alt="The chat panel of the widget with the Glass, Bauhaus and Terminal presets, side by side (dark)" />
</Frame>

Above the gallery, the editor shows the number of overrides, for example "3 overrides on the preset". Click **Clear overrides** to remove all overrides and use the preset as it is. When you select a different preset, your overrides stay.

## Light or dark

**Light or dark** sets which colour scheme the widget shows:

* **As the visitor's system** — the widget follows the light or dark choice of the visitor's device.
* **Light** — always light.
* **Dark** — always dark.

## Overrides

The overrides are on five tabs: **Colours**, **Shape**, **Type**, **Surface** and **Launcher**.

Each field shows its default value in grey when you do not override it. The hint below the field tells you where the default comes from, such as **From the preset**. To remove an override, click the reset icon beside the field label (tooltip **Use the default**).

### Colours

<Frame>
  <img alt="The Colours tab of the appearance editor. The live preview shows the chat panel with the same colours (light)" />

  <img alt="The Colours tab of the appearance editor. The live preview shows the chat panel with the same colours (dark)" />
</Frame>

The **Colours** tab has a **Light** tab and a **Dark** tab, because each scheme has its own colours. A scheme that the widget does not show has "(not shown)" after its name.

| Group | Colours |
| - | - |
| **Accent** | **Accent**, **Accent text** |
| **Panel** | **Background**, **Surface**, **Text**, **Muted text**, **Border** |
| **Header** | **Header background**, **Header text** |
| **Messages** | **Visitor bubble**, **Visitor bubble text**, **Agent bubble**, **Agent bubble text** |

Type a colour as `#rrggbb`, or as `#rrggbbaa` for a colour with transparency. You can also click the colour well and pick a colour.

### Where the default colours come from

* **Accent** — the **Primary colour** of your tenant, if your tenant has one. Otherwise, the accent of the preset. You set the **Primary colour** in **Settings > Theme > Brand colours**. See [Theme](/theme-editing#brand-colours).
* **Accent text** — near-black or white, whichever has more contrast on the accent.
* **Header text**, **Visitor bubble text** and **Agent bubble text** — the text colour of the preset. If you override the background of the header or a bubble, its text becomes near-black or white, whichever has more contrast.
* In some presets, such as **Classic**, the header and the visitor bubbles follow the accent. When you change the accent, they change too.
* All other colours come from the preset.

### Contrast warnings

The editor checks the contrast of each text colour on its background, in light and in dark:

* **Text** on **Background**
* **Muted text** on **Background**
* **Header text** on **Header background**
* **Visitor bubble text** on **Visitor bubble**
* **Agent bubble text** on **Agent bubble**
* **Accent text** on **Accent**

When a pair has a contrast of less than 4.5:1, the **Colours** tab shows a red count. The tab also shows the message "Some text may be hard to read" with a list of the pairs. You can still save, but visitors with low vision can find the text hard to read.

### Shape

| Field | Values |
| - | - |
| **Panel corners** | 0 to 32 px |
| **Message corners** | 0 to 32 px |
| **Button and field corners** | 0 to 32 px |
| **Border width** | 0 to 4 px |
| **Border style** | **Solid**, **Dashed**, **Double** |

### Type

| Field | Values |
| - | - |
| **Font** | See [Fonts](#fonts). |
| **Text size** | 13 to 18 px |
| **Spacing** | **Compact**, **Comfortable** |

### Surface

| Field | Values |
| - | - |
| **Shadow** | **None**, **Soft**, **Strong**, **Hard offset** |
| **Background blur** | 0 to 40 px |
| **Panel opacity** | 0.5 to 1 |
| **Header** | **Filled**, **Plain**, **Underline** |
| **Messages** | **Filled**, **Outlined**, **Plain** |

A **Panel opacity** of less than 1 makes the panel translucent. The panel then blurs the page behind it.

### Launcher

<Frame>
  <img alt="The Launcher tab with the label Chat with us. The live preview shows the launcher with this label (light)" />

  <img alt="The Launcher tab with the label Chat with us. The live preview shows the launcher with this label (dark)" />
</Frame>

| Field | Values |
| - | - |
| **Corner** | **Bottom right**, **Bottom left** |
| **Distance from the side** | 0 to 64 px |
| **Distance from the bottom** | 0 to 64 px |
| **Shape** | **Circle**, **Pill**, **Square**, **Rounded** |
| **Size** | **Small** (48 px), **Medium** (56 px), **Large** (64 px) |
| **Style** | **Solid**; **Glass**, which blurs the page behind it; **Orb**, a sphere in the accent colour that turns |
| **Icon** | **Chat bubble**, **Spark**, **No icon** |
| **Animation** | **None**, **Pulse**, **Orbit** |
| **Label** | A short text beside the icon. Leave it empty to show the icon only. |

A **Circle** launcher shows no label. If you set **No icon** and no label, the launcher shows the chat bubble icon. The **Orb** style and the animations stop when the visitor's device asks for reduced motion.

## Fonts

On the **Type** tab, select the kind of font in **Font**:

| Kind | What it does |
| - | - |
| **The preset's font** | The system font of the preset. Nothing loads. This is the default. |
| **A system font stack** | A font that each device has. Select the **Stack**: **Sans serif**, **Serif**, **Monospace** or **Rounded**. Nothing loads. |
| **Fonts on the visitor's device** | Type **Font names**, separated by commas, such as `"Segoe UI", Arial`. The widget uses a font only when the visitor's device has it. |
| **A web font stylesheet** | A CSS file that loads a web font, such as a Google Fonts stylesheet. Type the **Family name** and the **Stylesheet URL**. |
| **Font files** | Your own font files. Type the **Family name**, then add a **Font file URL**, a **Weight** and a **Style** for each file. |

### Web font stylesheet

Example of a **Stylesheet URL**:

```text theme={null}
https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap
```

The **Family name** for this example is `Inter`.

<Frame>
  <img alt="The Type tab. Font is A web font stylesheet, the family name is Fraunces, and the live preview shows the Fraunces font (light)" />

  <img alt="The Type tab. Font is A web font stylesheet, the family name is Fraunces, and the live preview shows the Fraunces font (dark)" />
</Frame>

When you save, the platform checks the stylesheet. The stylesheet must obey these rules:

* The URL starts with `https://` and names a public host.
* The URL answers with the content type `text/css`.
* The stylesheet names at least one font file on a public `https` host.
* The font files are on a maximum of 8 hosts.

If the stylesheet does not obey a rule, the field shows "The server cannot use this stylesheet." and the reason. The **Type** tab then shows a warning icon.

### Font files

Each font file must be `woff2`, `woff`, `ttf` or `otf`, with an `https` URL on a public host. Add one file for each weight and style that you need, to a maximum of 8 files. Example: `https://cdn.example.com/brand-400.woff2`.

<Note>The launcher is on your own page, and it uses the family name of the theme font. If your page does not load that font, the launcher shows the system font.</Note>

## Live preview

While the editor is open, the **Live preview** shows the sample site beside the controls, with your unsaved changes. The preview changes a short time after each change.

The **Open the sample site in a new tab** icon button opens the preview in a new browser tab. There, the widget has the full window. The tab shows your unsaved changes, but it does not show your later changes until you click **Reload**.

The tab can show these messages:

| Message | What it means |
| - | - |
| The theme has changed. | Click **Reload** to see the latest version. |
| The editor is closed, so there is no draft. Reload shows the saved theme. | You saved or cancelled the edit. |
| The preview expires soon. / The preview has expired. | A preview lasts 10 minutes. Click **Reload** to make a new one. |
| No draft is open, so this tab shows the saved theme. | The tab shows the saved appearance. |

## Save

Click **Save** to store the appearance. Each site gets the new appearance:

* A page that a visitor opens after the save shows the new look.
* A page that stays open shows the new launcher after a maximum of 30 minutes.

If another person saves the appearance while you edit it, a bar asks which version to keep. Click **Use theirs** or **Keep mine**.

## Style the launcher from your page

The usual CSS of your page does not reach the launcher or the panel frame. Your page can style these parts only with the `::part()` selector on the element `[data-dialai-widget]`:

| Part | What it is |
| - | - |
| `launcher` | The launcher button. |
| `launcher-icon` | The icon in the launcher. |
| `launcher-label` | The label in the launcher. |
| `badge` | The count of unread messages. |
| `panel` | The panel that holds the chat. |
| `panel-close` | The close button of the panel, before the chat loads. |

These part names do not change. Example:

```css theme={null}
[data-dialai-widget]::part(launcher) {
  box-shadow: 0 0 0 3px #ffd400;
}
[data-dialai-widget]::part(launcher-label) {
  letter-spacing: 0.04em;
}
```

No CSS of your page reaches the chat itself. Only the appearance that you save on the dashboard changes the chat.

## Best practices

| Practice | Reason |
| - | - |
| Start from the preset that is nearest to your site. | You need fewer overrides. |
| Set the **Primary colour** of your tenant before you override the accent. | All widgets then use your brand colour. |
| Correct each contrast warning before you save. | Some visitors cannot read text with low contrast. |
| Use **As the visitor's system** when your site has a dark mode. | The widget then follows the visitor's choice. |

## Related

<CardGroup>
  <Card title="Web Widgets" icon="comment" href="/web-widgets">Create a widget and put it on your site.</Card>
  <Card title="Signed-in visitors" icon="user-check" href="/web-widget-sign-in">Tell the widget who your customer is.</Card>
  <Card title="Theme" icon="paintbrush" href="/theme-editing">Tenant logos and brand colours.</Card>
</CardGroup>


# Signed-in Visitors
Source: https://docs.dialai.ca/web-widget-sign-in

Let a web widget know which customer is signed in to your portal, and give the flow verified values from the customer's token.

A [web widget](/web-widgets) can sit behind the login of your portal. Your portal gives the widget a signed token (a JWT) for the customer who is signed in. The platform checks the token, and then it knows the customer. Values from the claims of the token become **verified context parameters** of the conversation. Your flow can trust these values, because the visitor cannot change them.

Use this when a flow must act for one customer, for example to look up the balance of the customer's account.

## How it works

1. A customer signs in to your portal.
2. The widget asks your page for a token. Your page gets a token for the customer from your identity provider or from your backend.
3. The platform checks the signature, the issuer, the audience and the age of the token.
4. The platform reads the user id and the context parameters from the claims of the token, with the paths that you set.
5. The conversation starts. Functions in the flow read the context parameters as [internal parameters](/functions-and-events#inputs).

The same user of one sign-in provider is the same visitor each time.

## Who can chat

On the page of the widget, click **Edit** on the **Sign-in** card. In **Who can chat**, select a mode:

| Mode | Label in the list | What the widget does |
| - | - | - |
| Anyone can chat. The widget accepts no sign-in. | **Anonymous** | It does not ask your page for a token. Each visitor is anonymous. This is the default. |
| Anyone can chat. A signed-in visitor is known to the agent by the claims of the portal's token. | **Sign-in optional** | Without a signed-in customer, it starts an anonymous session. When a customer signs in, it ends the anonymous session and starts a verified one. The anonymous conversation does not move to the customer. |
| Only signed-in visitors can chat. | **Sign-in required** | It starts only verified sessions. Without a signed-in customer, it shows "Sign in to chat." and starts nothing. |

The two sign-in modes need at least one sign-in provider.

When the customer on the page changes, or signs out, the widget clears the conversation at once. It then starts again as the new customer, as an anonymous visitor (**Sign-in optional**), or with "Sign in to chat." (**Sign-in required**).

## Add a sign-in provider

A sign-in provider is an issuer of tokens that the widget trusts, such as your identity provider. A widget can have a maximum of 20 providers. The `iss` claim of a token selects the provider.

<Steps>
  <Step title="Open the sign-in settings">
    On the page of the widget, click **Edit** on the **Sign-in** card.
  </Step>

  <Step title="Add a provider">
    Click **Add a sign-in provider**.
  </Step>

  <Step title="Fill in the fields">
    Fill in the fields in the table below.
  </Step>

  <Step title="Add the context parameters">
    Click **Add a parameter** for each value that the flow needs. See [Map claims to context parameters](#map-claims-to-context-parameters).
  </Step>

  <Step title="Save">
    Select the mode in **Who can chat**, then click **Save**.
  </Step>
</Steps>

<Frame>
  <img alt="The Sign-in card. Sign-in is optional, and one provider has an issuer, an audience, a JWKS URL, a user id path and one context parameter (light)" />

  <img alt="The Sign-in card. Sign-in is optional, and one provider has an issuer, an audience, a JWKS URL, a user id path and one context parameter (dark)" />
</Frame>

| Field | What to type |
| - | - |
| **Issuer (iss)** | The exact `iss` value of the tokens of your portal, such as `https://login.example.com/`. |
| **Audience (aud)** | The `aud` value that each token must have, such as `dialai-widget`. The `aud` claim of a token can be this value or an array that holds it. |
| **How the portal signs its tokens** | **JWKS URL**, **Public key (JWK)** or **Shared secret (HS256)**. See [Keys](#keys). |
| **User id path** | An RFC 9535 JSONPath query to the user's id in the claims. The default is `$.sub`. See [Map claims with JSONPath queries](#map-claims-with-jsonpath-queries). |
| **Oldest token, in minutes** | 1 to 1440 (24 hours). The platform refuses a token whose `iat` is older than this. The default is 60. |
| **Context parameters** | The parameters that the widget fills from the claims. |

### Keys

Select how your portal signs its tokens:

| Kind | What to give | Algorithms |
| - | - | - |
| **JWKS URL** | The `https` URL of the JSON Web Key Set of your portal, such as `https://login.example.com/.well-known/jwks.json`. It must be on a public host. | ES256, ES384, RS256, PS256 |
| **Public key (JWK)** | One EC (P-256 or P-384) or RSA public key, as JSON. Paste the public key only. The platform refuses a key that has a private part. | ES256, ES384, RS256, PS256 |
| **Shared secret (HS256)** | A secret of 32 to 512 bytes that your backend also knows. | HS256 |

Use a **JWKS URL** when your identity provider publishes one. Then a key rotation needs no change here.

Use a **Shared secret** when your own backend signs a token for the widget. After you save, the secret does not show again. To keep the secret, leave the field empty when you edit the provider. To replace it, type a new secret. If the page shows "This deployment cannot store a shared secret. Use a JWKS URL or a public key.", use one of the other kinds.

<Warning>Keep a shared secret on your server. Never put it in the code of your page.</Warning>

### What the token must have

* `iss`, equal to **Issuer (iss)**.
* `aud`, equal to **Audience (aud)**, or an array that holds it.
* `exp` and `iat`.
* The claim that **User id path** finds. It must be text that is not empty, or a number.

The platform permits 60 seconds of clock difference.

## Map claims with JSONPath queries

The **User id path** and each context parameter use a **JSONPath query**, as [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) defines it. The platform runs each path on the claims of the token. A path finds no value, one value, or more values.

Example claims of a token. The `aud`, `iat` and `exp` claims are not shown.

```json theme={null}
{
  "sub": "user-123",
  "iss": "https://portal.example.com",
  "https://portal.example.com/claims": { "account": "A-1" },
  "x-tenant": "east",
  "profile": { "email": "a@example.com", "name": { "given": "Ada" } },
  "accounts": [
    { "number": "1001", "primary": true },
    { "number": "1002", "primary": false }
  ],
  "roles": ["a", "b", "c"]
}
```

| Path | Result on these claims |
| - | - |
| `$.sub` | Finds `"user-123"`. |
| `$.profile.name.given` | Finds `"Ada"`. Each `.name` goes into a member of an object. |
| `$['https://portal.example.com/claims'].account` | Finds `"A-1"`. Put a member name in brackets and quotes when it has a character that is not a letter, a digit or `_`, such as `/`, `-` or `.`. |
| `$["x-tenant"]` | Finds `"east"`. You can use single quotes or double quotes. |
| `$.accounts[0].number` | Finds `"1001"`. The index of the first element is `0`. |
| `$.accounts[-1].number` | Finds `"1002"`. A negative index counts from the end, so `-1` is the last element. |
| `$.accounts[?@.primary == true].number` | Finds `"1001"`, the number of the primary account. A filter `[?…]` keeps each element for which its test is true. In the test, `@` is the element. |
| `$.roles` | Finds `["a", "b", "c"]`. An array is one value. |
| `$.missing` | Finds no value. |
| `$.accounts[*].number` | Finds two values, `"1001"` and `"1002"`. `[*]` selects each element of the array. This is **ambiguous**, so the platform does not use it. |

### Rules for a path

* A path starts with `$`, the root of the claims. Do not put a space before `$` or after the end of the path.
* Use `.name` for a member whose name has only letters, digits and `_`, and does not start with a digit. For other names, use `['name']` or `["name"]`.
* `[*]` selects each element of an array, and `.*` selects each member of an object. Thus they find one value for each element or member. To select one element, use an index or a filter.
* A filter can use the functions of RFC 9535. For example, `$.accounts[?search(@.number, '2$')].number` finds `"1002"`.
* A path has a maximum of 1000 characters.

For all of the syntax, see [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535).

### Outcomes

Each path has one of three outcomes:

| Outcome | Means | User id path | Context parameter |
| - | - | - | - |
| **found** | The path finds exactly one value. | If the value is text that is not empty, or a number, it is the visitor's user id. Else the sign-in fails. | The platform sets the parameter. |
| **absent** | The path finds no value. | The sign-in fails. | The platform leaves the parameter out. The conversation starts. |
| **ambiguous** | The path finds two or more values. | The sign-in fails. | The platform leaves the parameter out. The conversation starts. |

An **ambiguous** outcome is a mistake in the path, and only you can correct it.

Some details about the outcomes:

* A path cannot fail on the claims. A comparison of two values of different types is false. For example, `$.accounts[?@.number > 1000].number` finds no value, because each `number` is text and `1000` is a number.
* A filter without a comparison only tests that the member is there. For example, `$.accounts[?@.primary].number` finds two values, because both accounts have `primary`. To test the value, write `$.accounts[?@.primary == true].number`.
* A path into a value of a different type finds no value. For example, `$.sub.inner` finds no value, because `sub` is text.
* An array or an object is one value. For example, `$.roles` is **found**, and gives the array `["a", "b", "c"]`.
* A JSON `null` is a value, so a path to `null` is **found**. A context parameter then gets `null` if its schema permits it.

### The check when you save

When you click **Save**, the platform reads each path. If a path is not a correct RFC 9535 JSONPath query, the field shows "This is not an RFC 9535 JSONPath query, such as $.sub or $.accounts\[0].number", then the problem that the platform found and its position in the path. For example, the platform refuses these paths:

* `$.`, because the path ends with a dot.
* `$.accounts[?@.number = '1001']`, because a comparison uses `==`, not `=`.
* `$.accounts[?like(@.number, '1')]`, because RFC 9535 has no function `like`.

This check finds only syntax mistakes. It cannot find a path that finds no value, or two values, in the tokens of your portal. To find those mistakes, use [Act as a customer](#test-the-paths-with-act-as-a-customer).

## Map claims to context parameters

A context parameter is a [parameter](/building-blocks#parameters) of your tenant that the widget fills from the claims of the token.

1. In **Context parameters**, click **Add a parameter**.
2. Select the parameter. To make a new parameter, type its name and select **Add ‘name’**.
3. Type the JSONPath query to the value in the claims, such as `$.accounts[0].number`.

When a conversation starts, the platform checks each value against the JSON schema of its parameter. If a value does not fit the schema, the platform leaves the parameter out. The conversation starts without it.

A provider can map a maximum of 50 parameters. The values of all context parameters must be 4 KiB of JSON or less. If they are more, the sign-in fails.

Functions in the flow read these values as [internal parameters (context parameters)](/functions-and-events#inputs).

## Give the widget a token

Your page gives the widget a token through the `identity` option of `init`. `identity` is a function with no arguments. It returns a promise of a token for the customer who is signed in now, or `null` when nobody is signed in.

To use `identity`, call `init` yourself, and remove the `data-tenant`, `data-widget-id` and `data-host` attributes from the script tag. See [Call DialAI before the script loads](/web-widgets#call-dialai-before-the-script-loads).

```html theme={null}
<script>
  window.DialAI = window.DialAI || function () { (DialAI.q = DialAI.q || []).push(arguments) };
  DialAI("init", {
    tenant: "<tenant>",
    widgetId: "<widget id>",
    host: "https://<api host>",
    identity: async function () {
      // Your backend checks the portal session and returns a new token as text.
      const response = await fetch("/session/widget-token", { credentials: "same-origin" });
      if (!response.ok) return null;
      return (await response.text()) || null;
    },
  });
</script>
<script async src="https://<api host>/widget/loader.js"></script>
```

The widget calls the function before each session start, and again about each 8 minutes to refresh the session. Obey these rules:

* Return a new token on each call.
* Return `null` when nobody is signed in.
* Return in less than 10 seconds. The widget counts no answer as `null`.
* Keep the token under 32 KiB.

An error, a rejected promise, or a value that is not text counts as `null`.

When a customer signs out of your portal, also call `DialAI("logout")`. Then the next person on the same browser does not see the conversation.

### Your backend can sign the token

If your portal has no identity provider that issues JWTs, your backend can sign a short token for the widget:

1. Your backend checks the portal session of the customer.
2. It signs a JWT with HS256 and the shared secret of the provider. Or it signs with its own private key, and you give the public key or a JWKS URL to the provider.
3. It puts the verified values in the claims, for example the account number.
4. It returns the token to the `identity` function of your page.

Give the token a short life, for example 10 minutes, and set **Oldest token, in minutes** to match.

## Test the paths with Act as a customer

**Act as a customer** lets you chat on the **Try it** card as a signed-in customer, with claims that you type. You do not need a token from your portal.

You need the `web-widgets:simulate` permission, and the widget must have at least one sign-in provider.

<Steps>
  <Step title="Start">
    On the **Try it** card, click **Act as a customer**.
  </Step>

  <Step title="Select the provider">
    In **Sign-in provider**, select the provider to test.
  </Step>

  <Step title="Type the claims">
    In **Claims (JSON)**, type the claims of a customer's token. The field starts with a test user at the **User id path**. The maximum is 16 KiB.
  </Step>

  <Step title="Chat">
    Click **Start as this customer**. Then open the launcher on the sample site and chat.
  </Step>
</Steps>

The card then shows what the paths of the provider found in your claims:

* **Visitor id** — **Found**, or the reason the sign-in fails:
  * "The path finds nothing in the claims. The sign-in fails."
  * "Not an id. Use text that is not empty, or a number. The sign-in fails."
  * For an ambiguous path, the number of values and the first values. For example, the user id path `$.accounts[*].number` on the example claims above gives `The path finds 2 values: "1001", "1002". It must find one. The sign-in fails.`
* Each context parameter — one of these:
  * **Set**.
  * "The path finds nothing in the claims".
  * "Does not fit: …" with the schema problem.
  * For an ambiguous path, the number of values and the first values, then "It must find one, so the parameter is left out."

The card shows a maximum of five values. When a path finds 50 values or more, the card says "50 or more values".

<Frame>
  <img alt="The Try it card in a simulated session. Visitor id shows Found, ServiceAddress shows Set, and the chat panel shows an answer of the flow (light)" />

  <img alt="The Try it card in a simulated session. Visitor id shows Found, ServiceAddress shows Set, and the chat panel shows an answer of the flow (dark)" />
</Frame>

If a path finds two or more values, the card shows a warning: "A path of this sign-in provider has a mistake. Correct it in the sign-in settings: a real visitor gets the same result, and the widget logs the mistake as an error."

Click **Stop** to chat as an anonymous visitor again. The session of **Act as a customer** is a simulated session. It never shows the real conversations of that customer.

## When a sign-in fails

When the platform refuses a token, the widget gets one of these codes. Your developers can see the code in the network tab of the browser.

| Code | Means |
| - | - |
| `invalid_token` | Not a JWT, a bad signature, an algorithm that the key does not permit, no `exp` or `iat`, or an `iat` or `nbf` in the future. |
| `unknown_issuer` | No provider of the widget has the `iss` of the token. |
| `expired` | The `exp` of the token is more than 60 seconds ago. |
| `too_old` | The `iat` of the token is older than **Oldest token, in minutes**. |
| `bad_audience` | The `aud` of the token does not hold the audience of the provider. |
| `no_user_id` | The **User id path** found no value, two or more values, or a value that is not text or a number. Empty text is not a user id. |
| `context_too_large` | The context parameters are more than 4 KiB of JSON. |
| `identity_required` | A refresh had no token, but the session needs a signed-in customer. The session ends. |
| `user_changed` | A refresh had a token of a different user. The session ends. |

## Best practices

| Practice | Reason |
| - | - |
| Put only the values that the flow needs in the claims. | The values must be 4 KiB of JSON or less. |
| Use a filter to select one value from a list. | A path that finds two values is ambiguous, and the platform does not use it. |
| Test each provider with **Act as a customer** before you go live. | The save check finds only syntax mistakes. |
| Give tokens a short life. | A stolen token is then useful for a short time only. |

## Related

<CardGroup>
  <Card title="Web Widgets" icon="comment" href="/web-widgets">Create a widget and put it on your site.</Card>
  <Card title="Widget appearance" icon="palette" href="/web-widget-appearance">Presets, colours, fonts and the launcher.</Card>
  <Card title="Functions and events" icon="code" href="/functions-and-events">Read context parameters in a function.</Card>
  <Card title="Building blocks" icon="cubes" href="/building-blocks">Make the parameters that the widget fills.</Card>
</CardGroup>


# Web Widgets
Source: https://docs.dialai.ca/web-widgets

Put a chat with one of your flows on your website, with a launcher in the corner of each page.

<Frame>
  <img alt="The Web Widgets tab shows a list of widgets with their status, flow, visitors, allowed sites and update time (light)" />

  <img alt="The Web Widgets tab shows a list of widgets with their status, flow, visitors, allowed sites and update time (dark)" />
</Frame>

A **web widget** puts a chat with one of your flows on your own website. The widget adds a launcher in a bottom corner of each page. A visitor clicks the launcher, and a chat panel opens on the same page.

Web Widgets are the new way to put chat on a website. They replace the legacy web chat (chat links on the **Web (Legacy)** tab, with the [iframe](/iframe-integration) or the [script tag](/script-tag-integration)). Use a web widget for each new site.

A widget has these parts:

* **A flow** — the flow that answers the visitors.
* **Allowed sites** — the sites that can show the widget. No other site can show it.
* **An appearance** — a preset and your changes to it. See [Widget appearance](/web-widget-appearance).
* **Sign-in** — optional. A portal that signs its customers in can tell the widget who the customer is. See [Signed-in visitors](/web-widget-sign-in).

## Find Web Widgets

Go to **Agent > Points of Contact** and select the **Web Widgets** tab.

The tab shows only when your role has the `web-widgets:list` permission. Other actions need other permissions:

| Permission | What it lets you do |
| - | - |
| `web-widgets:list` | See the **Web Widgets** tab and the list of widgets. |
| `web-widgets:read` | Open the page of a widget. |
| `web-widgets:create` | Create a widget with **Create Widget**. |
| `web-widgets:update` | Change a widget: its status, allowed sites, appearance and sign-in. |
| `web-widgets:simulate` | Use **Act as a customer** on the **Try it** card. |

The list has these columns: **Status**, **Widget**, **Visitors**, **Allowed sites** and **Updated**. Active widgets are at the top. Use the **Status** filter to show only **Active** or **Off** widgets. Click a row to open the page of that widget.

## Create a widget

<Steps>
  <Step title="Open the dialog">
    On the **Web Widgets** tab, click **Create Widget**.
  </Step>

  <Step title="Type a name">
    In **Name**, type a name for the site or the page that shows the widget. An example is "Billing help on the account page". Each widget in your tenant must have a different name.
  </Step>

  <Step title="Select the flow">
    In **Flow**, select the flow that answers the visitors.
  </Step>

  <Step title="Add the allowed sites">
    In **Allowed sites**, type the address of a site, such as `https://www.example.com`. Click **Add**. Do this again for each site that shows the widget.
  </Step>

  <Step title="Create the widget">
    Click **Create Widget**. The page of the new widget opens.
  </Step>
</Steps>

<Frame>
  <img alt="The Create Widget dialog. The Name, Flow and Allowed sites fields are filled in (light)" />

  <img alt="The Create Widget dialog. The Name, Flow and Allowed sites fields are filled in (dark)" />
</Frame>

A new widget is active. Each visitor is anonymous until you set up [sign-in](/web-widget-sign-in). The appearance is the **Classic** preset until you change it.

## Allowed sites

The allowed sites are a security control. On a site that is not in the list, the launcher and the chat panel do not show. If the list is empty, no site can show the widget.

Each entry is an origin: a scheme, a host and an optional port. The widget ignores the path of an address. These forms are permitted:

| Form | Example | Notes |
| - | - | - |
| One site | `https://www.example.com` | The usual form. |
| All subdomains of a domain | `https://*.example.com` | Not permitted on a public suffix, such as `*.co.uk` or `*.github.io`. |
| A site with a port | `https://portal.example.com:8443` | For a site on a port that is not the default. |
| A local test site | `http://localhost:3000` | Only `localhost` and `127.0.0.1` can use `http`. |

A widget has a maximum of 50 allowed sites.

The list in the **Create Widget** dialog starts with the site of the Dial AI dashboard. This lets you try the widget on the **Try it** card at once. Keep this entry while you use **Try it**.

To change the list later, click the edit (pencil) icon beside **Allowed sites** on the page of the widget. Add or remove sites, then click **Save**.

## The page of a widget

The page has these cards: **Try it**, **Appearance**, **Embed code** and **Sign-in**. The side panel shows the **Status**, **Flow**, **Visitors**, **Allowed sites**, **Look**, **Limits** and **Created** date.

### Status

The **Status** switch turns the widget on or off for all sites at the same time.

* **Active: sites show the widget** — each allowed site shows the launcher.
* **Off: no site shows it** — the launcher goes away, and the widget starts no new session.

Use **Off** to stop a widget. The page has no delete action.

### Limits

**Limits** shows the maximum number of conversations that the widget starts in one day (UTC), or **No daily limit**. You cannot change the limit on this page.

## Try it

The **Try it** card shows a sample website with the widget on it. Click the launcher in its bottom corner and chat as a visitor does. A chat on the sample site is a real conversation with the flow of the widget.

<Frame>
  <img alt="The page of a widget. The chat panel is open on the sample site, with a question and the answer of the flow (light)" />

  <img alt="The page of a widget. The chat panel is open on the sample site, with a question and the answer of the flow (dark)" />
</Frame>

* **Start again** loads the sample site again.
* The **Open the sample site in a new tab** icon button opens the sample site in a new browser tab. In the tab, the widget has the full window, so it shows its desktop layout.

<Frame>
  <img alt="The sample site in a full browser tab, with the chat panel open in the bottom right corner (light)" />

  <img alt="The sample site in a full browser tab, with the chat panel open in the bottom right corner (dark)" />
</Frame>

When somebody saves a change, the tab shows a bar: **The theme has changed.** or **The widget has changed.** Click **Reload** to show the change.

The sample site cannot show the widget in these conditions. The card then shows the reason.

| Message | What to do |
| - | - |
| This page (…) is not one of the widget's allowed sites, so the widget cannot show here. | Add the site of the dashboard to **Allowed sites**. |
| The widget is off, so no site shows it. | Set **Status** to **Active**. |
| The chat widget is not available on this deployment… | Contact your account representative. |

When the widget has a sign-in provider, you can also chat as a signed-in customer. See [Act as a customer](/web-widget-sign-in#test-the-paths-with-act-as-a-customer).

## Put the widget on your site

<Steps>
  <Step title="Copy the embed code">
    On the **Embed code** card, click **Copy**.
  </Step>

  <Step title="Paste it into each page">
    Paste the code immediately before the `</body>` tag of each page that shows the widget.
  </Step>

  <Step title="Check the allowed sites">
    Make sure that the site of each page is in **Allowed sites**.
  </Step>
</Steps>

<Frame>
  <img alt="The Embed code card with the script tag and the Copy button (light)" />

  <img alt="The Embed code card with the script tag and the Copy button (dark)" />
</Frame>

The embed code has this shape:

```html theme={null}
<script async src="https://<api host>/widget/loader.js"
  data-tenant="<tenant>"
  data-widget-id="<widget id>"
  data-host="https://<api host>"></script>
```

Always copy the embed code from the page of the widget, because it has the correct values for your deployment.

### What visitors see

* The launcher shows in the corner that you set in the appearance.
* On a screen of 480 px or less, the open chat panel covers the full page.
* The **Escape** key closes the panel.
* If the chat cannot load in 15 seconds, the panel shows "The chat could not load." and a **Try again** button.

A page that a visitor opens after a change shows the change. A page that stays open shows the new launcher after a maximum of 30 minutes.

## Control the widget from your page

The embed code also makes a JavaScript function, `DialAI`, on your page. Your page can use it to open the chat, to listen to events, and to give the widget a sign-in token.

### Call `DialAI` before the script loads

To call `DialAI` before the script loads, add a small queue function first. Then call `init` yourself, and remove the `data-tenant`, `data-widget-id` and `data-host` attributes from the script tag:

```html theme={null}
<script>
  window.DialAI = window.DialAI || function () { (DialAI.q = DialAI.q || []).push(arguments) };
  DialAI("init", { tenant: "<tenant>", widgetId: "<widget id>", host: "https://<api host>" });
</script>
<script async src="https://<api host>/widget/loader.js"></script>
```

Copy the values of `tenant`, `widgetId` and `host` from the embed code of the widget.

<Warning>Only the first `init` has an effect. The `data-tenant` attribute on the script tag is also an `init`, and it runs first. If you keep the attributes and also call `init`, the widget ignores your `init` and its options, such as `identity`.</Warning>

### Commands

| Command | What it does |
| - | - |
| `DialAI("init", { tenant, widgetId, host, identity })` | Adds the launcher. `host` and `identity` are optional. |
| `DialAI("open")` | Opens the chat panel. |
| `DialAI("close")` | Closes the chat panel. |
| `DialAI("toggle")` | Opens the panel when it is closed, and closes it when it is open. |
| `DialAI("logout")` | Ends the session of the visitor in the widget. |
| `DialAI("on", event, handler)` | Calls `handler(payload)` for each event of that type. |

Call `DialAI("logout")` when a person signs out of your site. Then the next person on the same browser does not see the conversation of the previous person. The logout works also when the chat panel did not open yet.

To tell the widget who a signed-in customer is, give `init` an `identity` function. See [Signed-in visitors](/web-widget-sign-in#give-the-widget-a-token).

### Events

| Event | Payload | When |
| - | - | - |
| `state` | `{ open }` | Each time the panel opens or closes. |
| `conversation` | `{ event }`, with `event` one of `"started"`, `"ended"` or `"handoff-started"` | When a conversation starts, ends, or goes to a human agent. |
| `message` | `{ direction, text, at }`, with `direction` one of `"received"` or `"sent"` | For each new message. |

In the `text` of a `sent` message, the platform masks sensitive data, such as a card number. Your page never gets the text that the visitor typed.

This example opens the chat from a "Chat with us" link, and records each handoff:

```html theme={null}
<a href="#" id="chat-link">Chat with us</a>
<script>
  document.getElementById("chat-link").addEventListener("click", function (event) {
    event.preventDefault();
    DialAI("open");
  });
  DialAI("on", "conversation", function (payload) {
    if (payload.event === "handoff-started") {
      console.log("The conversation went to a human agent.");
    }
  });
</script>
```

Put this code after the queue function, so that `DialAI` exists when it runs.

### Style the launcher

Your page can change the launcher with CSS `::part()` rules. Your page cannot change the chat panel or the theme. See [Widget appearance](/web-widget-appearance#style-the-launcher-from-your-page).

## Web Widgets and the legacy web chat

| | Web Widgets | Web (Legacy) |
| - | - | - |
| Where | **Points of Contact > Web Widgets** | **Points of Contact > Web (Legacy)** |
| On your site | One script tag. It adds a launcher and a chat panel. | An iframe or the `dial-ai.js` script with `renderModal`. |
| Which sites | Only the allowed sites. | Any site that has the chat link. |
| Look | Presets and overrides, set on the dashboard. | The tenant theme, or `brandVariants` on the page. |
| Customer identity | Tokens from your portal, checked by the platform. See [Signed-in visitors](/web-widget-sign-in). | Chat links with baked-in context. See [Passing context securely](/integration-context). |
| Status | Current. | Deprecated. Chat links still work for now. |

## Best practices

| Practice | Reason |
| - | - |
| Make one widget for each site or each part of a site. | Each widget has its own allowed sites, look and flow. The name shows in the list. |
| Add only the sites that you own to **Allowed sites**. | Any allowed site can show your flow to its visitors. |
| Test on the **Try it** card before you paste the embed code. | You see the same widget that your visitors see. |
| Set **Status** to **Off** to stop a widget at once. | All sites stop it. You do not have to change each page. |

## Related

<CardGroup>
  <Card title="Widget appearance" icon="palette" href="/web-widget-appearance">Presets, colours, fonts and the launcher.</Card>
  <Card title="Signed-in visitors" icon="user-check" href="/web-widget-sign-in">Tell the widget who your customer is.</Card>
  <Card title="Points of Contact" icon="address-book" href="/points-of-contact">All the channels that connect a flow to customers.</Card>
  <Card title="Flows" icon="diagram-project" href="/flows">Build the flow that answers your visitors.</Card>
</CardGroup>


# Writing Good Documentation
Source: https://docs.dialai.ca/writing-good-docs

How to author reference material the AI agent can actually use

The AI agent doesn't read your documents end-to-end the way a person does. When a customer asks a question, the platform searches your library for the passages most likely to contain the answer and hands those passages — not the whole document — to the model. The way you write and structure documentation has a direct impact on whether the right passage gets retrieved and whether the model can answer from it.

This page lays out the properties that make documentation work well with our retrieval system. Treat it as a working baseline — we will keep iterating as we learn what helps most.

## How retrieval works (in one paragraph)

Each document is split into **large chunks** and embedded into a vector index. At conversation time, the customer's message (rewritten as a search query — see [Flow Documentation](/flow-documentation)) is embedded against that index, and the closest chunks are returned. Before indexing, each chunk is **contextualized**: the platform prepends a short, AI-generated summary that situates the chunk inside the larger document, so that a chunk about "rebate eligibility" still retrieves well for a query about "the Energy Rebate Program" even when the program name isn't repeated locally. This technique is described in Anthropic's [Contextual Retrieval](https://www.anthropic.com/engineering/contextual-retrieval) write-up.

The practical implication: **the model only sees the chunks that come back**. If a chunk is ambiguous on its own, retrieved out of context, or contradicts another chunk, the answer suffers.

## Properties of good documentation

### Self-contained sections

A reader who lands on a single section — with no surrounding pages — should still understand what it's about. Don't rely on "as described above" or "see the previous section". Restate the subject when a new section starts.

> **Less good**: "It must be submitted within 30 days."
> **Better**: "A rebate application must be submitted within 30 days of installation."

Contextualization helps, but the closer a chunk is to standing on its own, the more reliably retrieval and answering both work.

### Clear, descriptive headings

Headings are one of the strongest signals the contextualization step uses to summarize a chunk. Write them like search results, not table-of-contents entries.

> **Less good**: "Overview", "Details", "Other notes"
> **Better**: "Rebate eligibility for residential customers", "How to submit a rebate application", "What to do if your application is rejected"

### One topic per document, when practical

Smaller, focused documents retrieve more accurately than monolithic handbooks. A 200-page policy manual is a worst case — ten 20-page documents on specific topics is much better. If a single PDF mixes billing, outages, and rebate programs, retrieval will sometimes return the wrong section for a given question.

If you can't split a source document, at least give it a strong, descriptive internal structure.

### Consistent terminology

Use the same name for the same thing throughout your library. If one document calls it the "Energy Rebate Program" and another calls it "EnerSave", retrieval has to bridge that gap on every query. Pick one canonical term per concept and stick to it.

Where customers genuinely use a different vocabulary than your documents do, use the **Query Rewriter Context** field on [Flow Documentation](/flow-documentation) to list the synonyms — but reduce vocabulary drift inside the documents themselves first.

### Define acronyms and jargon inline

Spell out an acronym the first time it appears in a section — not just the first time it appears in the document. Remember that the agent may only see one chunk, not the introduction.

> "PV (photovoltaic) systems qualify for the federal credit when..."

### Concrete over abstract

Specific values, names, thresholds, dates, dollar amounts, and procedures retrieve much better than abstract descriptions. If the answer to a likely question is a number or a step list, write the number or the step list — don't paraphrase it.

### Avoid duplication and contradiction

When two chunks cover the same ground with different details, retrieval may return either one — and the agent's answer becomes inconsistent. Prefer a single authoritative source per topic. If you do need duplication (e.g., a quick summary plus a full policy), make sure the two versions agree, and consider whether the summary belongs in an [FAQ](/faq) instead.

### Keep documents current

Stale documentation is worse than missing documentation — the agent will confidently quote outdated policy. Set a review cadence for every document, and prefer connector sources ([S3](/manage-documents#s3-bucket), [Confluence](/manage-documents#confluence)) when the source of truth is already maintained somewhere your team updates regularly.

### Images and tables

Images aren't invisible to the agent — the platform converts each image into an AI-generated text description before indexing — but quality varies. A labeled diagram or a screenshot with obvious content describes well; a dense chart, a small-text infographic, or a low-resolution scan describes poorly. If a fact is critical, don't rely on it living only inside an image; include it in the surrounding text too.

Tables are handled whether they're expressed as text (Markdown, HTML, text-layer PDF) or rendered as images. Text-form tables retrieve more reliably; image tables go through the same image-to-text path and inherit its limitations.

Supported direct-upload formats are listed under [Manage Documents](/manage-documents#supported-file-formats).

## Document, FAQ, or thought?

Documentation is one of three knowledge mechanisms. Choosing the right one matters as much as writing it well.

| Use | When |
| - | - |
| **Document** | Reference material the customer might ask many different questions about. |
| **FAQ** | A common one-line question with a single definitive answer. See [FAQ](/faq). |
| **Thought** | Behavior or process that depends on where the customer is in the flow. See [Thoughts](/thoughts). |

If you find yourself adding the same answer to many FAQs, it probably belongs in a document. If you find yourself writing a document that's really one Q\&A, it probably belongs in an FAQ.

## A quick checklist

Before attaching a document to a flow, run through:

* Does each section stand on its own without the rest of the document?
* Are headings specific enough to describe what's in the section?
* Is terminology consistent with the rest of the library?
* Are acronyms defined where they appear?
* Are there concrete values, steps, and names — not just abstractions?
* Is anything duplicated or contradicted by another document?
* Is the source text-based (not scanned images)?
* Is it current, and is there an owner who will keep it current?

If most of these are "yes", the agent has a good chance of answering correctly from your material.

## Further reading

* [Anthropic — Contextual Retrieval](https://www.anthropic.com/engineering/contextual-retrieval) — the technique used to enrich chunks before embedding.

***

## Related

<CardGroup>
  <Card title="Manage documents" icon="folder-open" href="/manage-documents">Upload, sync, and organize source material.</Card>
  <Card title="Flow documentation" icon="book-open" href="/flow-documentation">Attach documents and tune retrieval per flow.</Card>
  <Card title="FAQ" icon="circle-question" href="/faq">Curate short Q\&A pairs.</Card>
  <Card title="Document search" icon="magnifying-glass" href="/document-search">Query the library directly.</Card>
</CardGroup>