> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Configure Every Playbook has a description, availability rules, one or more sections containing steps, and general guidelines. Playbooks can also be assigned to conversation start events so they run automatically when a conversation begins on a specific channel. The Playbook editor includes a side panel with four panes, accessible via the icon rail on the right side of the editor. ## Runtime harness While a Playbook runs, the AI Agent continuously monitors the conversation and can intervene automatically — without requiring explicit steps in the Playbook. This built-in behavior ensures Playbooks stay responsive to end user needs even when the conversation takes an unexpected turn. * **Escalation and exit**: When the end user asks for a human agent, the Agent clears the Playbook's progress and exits permanently. The conversation does not return to the Playbook. * **Intent change detection**: When the end user goes off-topic, the Agent suspends the Playbook and addresses the new topic. Depending on how the conversation unfolds, the Agent may then return to where it left off in the Playbook or exit it entirely. * **Pause and resume for Knowledge search**: When the end user asks a question that would benefit from a Knowledge search, the Agent temporarily pauses Playbook execution, performs a Q\&A search, answers the question, and then resumes where it left off. > **Note** > > The runtime harness operates independently of the steps you author. You do not need to anticipate every possible conversational detour — the Agent handles common interruptions on its own. ### Flow controls By default, the runtime harness exits the Playbook, suspends it, or searches Knowledge when the end user deviates from the current flow. Flow controls let you change these defaults to keep the Agent focused on the Playbook. #### Conversation deviation behaviour In the Playbook details pane, open **Advanced settings** to find the **Conversation deviation behaviour** section. Three controls determine what happens when the end user deviates: | When the end user… | Default behavior | "Stay in this Playbook" behavior | | :----------------------- | :------------------------------------ | :------------------------------------------------------ | | **Asks for human** | Exit Playbook | Agent continues the flow | | **Goes off-topic** | Suspend Playbook, then return or exit | Agent continues the flow | | **Asks a Q\&A question** | Search Knowledge | Agent skips the Knowledge search and continues the flow | When **Stay in this Playbook** is active, the Agent does not ignore the end user's request. It acknowledges the request, continues with the current flow, and follows up later to offer to act on it. #### Playbook-level vs. step-level controls Controls are available at two levels: * **Playbook level**: In the Playbook details pane under **Advanced settings**. For **Asks for human** and **Asks a Q\&A question**, these apply throughout the entire Playbook execution — including while the Agent is sending a message or speaking on a Voice call. The **Goes off-topic** control takes effect while an `ASK` step is collecting the end user's response. * **`ASK` step level**: In any `ASK` step's side pane under **Advanced settings**. These override the Playbook-level defaults for that specific step. Each step dropdown includes a **Match Playbook-level setting** option that defers to the Playbook-level setting. When a step has its own explicit setting, the step setting always takes precedence. #### When the Agent follows up When **Stay in this Playbook** is active, the Agent overrides the [default runtime harness behaviors](#runtime-harness) described above. Instead of exiting, suspending, or searching Knowledge, the Agent acknowledges the deviation, continues the current flow, and then follows up to ask whether the end user still wants help with their original request. The timing of that follow-up depends on where the control is set: * **Step-level setting**: The Agent follows up immediately after that `ASK` step completes. * **Playbook-level setting with no step override**: The Agent follows up at the end of the Playbook. This distinction matters even when the values match. If the Playbook is set to **Stay in this Playbook** and a step is also explicitly set to **Stay in this Playbook**, the follow-up still happens after the step — not at the end of the Playbook — because the step-level setting is an override regardless of the value. #### Interaction with exact wording When an `ASK` step uses the **exact wording** question mode and deviation controls are active, a hint appears in the editor: *"If the user deviates, the AI Agent may transform these words to acknowledge their request before re-asking."* This means the Agent may adjust the fixed message slightly to acknowledge the deviation before repeating the question. > **Tip** > > Use flow controls on steps that collect critical information — such as identity verification or payment details — where an interruption would disrupt the workflow. ## Side panes The Playbook editor's side panel contains four panes — Playbook Details, General Guidelines, Steps, and Variables — accessible via the icon rail on the right side of the editor. ### Playbook Details The Details pane controls the Playbook's description, usage scope, and access rules. ![Playbook Details pane](/_fern-img/2e4753a2d1a2d1be56bf02f6322ebfb00d4cc79e740d70298ae33fb27c7e162c.webp) * **When to use this Playbook**: Describes the situations where the Playbook is appropriate, much like how you would explain its use to a human agent. This is the primary signal the Agent uses when selecting which Playbook to run. * **Usage**: Check **Only available within other Playbooks** to prevent the Playbook from triggering on its own. When checked, the AI Agent only uses this Playbook inside another Playbook, not on its own. Use this for child Playbooks that exist solely to support a parent. * **Availability rules**: Restrict which end users can access this Playbook based on variable conditions. Set to **Everyone** or configure rules using the following operators: | Operator | Description | | :------------------- | :------------------------------------ | | **Is** | Exact match. | | **Is not** | Does not match. | | **Starts with** | Value begins with the specified text. | | **Ends with** | Value ends with the specified text. | | **Contains** | Value appears anywhere. | | **Does not contain** | Value does not appear. | | **Is set** | Variable has a value. | | **Is not set** | Variable has no value. | * **Acknowledgment**: Controls what the AI Agent says immediately before this Playbook starts. Leave the field blank to let the Agent word the acknowledgment itself. Enter an instruction of up to 500 characters to guide it. To fix the exact wording, make the whole instruction `say exactly "your text"`. Exact wording is spoken as written and never translated. Messaging conversations follow the **Send acknowledgement messages** setting in [personality settings](/docs/setup/persona/personality-setup). If that setting is off, select **Always acknowledge on Chat for this Playbook** to send acknowledgments for this Playbook only. > **Warning** > > The description is critical to how the Playbook is selected. Be very clear about the intent that this Playbook corresponds to — vague or generic descriptions reduce selection accuracy. #### Conversation start events A conversation start event triggers a Playbook automatically when a new conversation begins on a specific channel. Instead of relying on intent matching from the description, the Playbook runs immediately as the first response on that channel. The available events depend on which channels are configured. Messaging and Voice events are always available. Other events appear when the corresponding channel is configured. #### Supported channels | Event | Channel | | :------------------------------------------- | :---------------------------------- | | **Conversation start - Messaging** | Web chat and messaging integrations | | **Conversation start - Voice** | Voice calls | | **Conversation start - Email** | Inbound email | | **Conversation start - Facebook Messenger** | Sunshine: Facebook Messenger | | **Conversation start - Instagram** | Sunshine: Instagram | | **Conversation start - WhatsApp** | Sunshine: WhatsApp | | **Conversation start - SMS** | Sunshine: Twilio SMS | | **Conversation start - Twitter DM** | Sunshine: Twitter DM | | **Conversation start - Web Messenger** | Sunshine: Web Messenger | | **Conversation start - Android** | Sunshine: Android | | **Conversation start - iOS** | Sunshine: iOS | | **Conversation start - Apple Business Chat** | Sunshine: Apple Business Chat | | **Conversation start - LINE** | Sunshine: LINE | | **Conversation start - Telegram** | Sunshine: Telegram | | **Conversation start - Viber** | Sunshine: Viber | **To assign a conversation start event to a Playbook:** 1. Open the Playbook editor and select the **Details** pane. 2. In the **When to use this Playbook** field, type `@`. 3. Select a conversation start event from the dropdown. Events already assigned to another Playbook are greyed out. The selected event appears as a pill above the description field. 4. Save the Playbook. A Playbook can have multiple conversation start events assigned — for example, both Messaging and Voice — so it runs at the start of conversations on all assigned channels. Each event can only be assigned to one Playbook at a time. > **Note** > > A standalone Playbook requires a description, even with a conversation start event assigned to it. The Playbook can still be used as a standalone Playbook if the intent of an end user matches the description. **What happens to Greetings:** Messaging and Voice channels use a Greeting as their default conversation opener. When a conversation start event for one of these channels is assigned to a Playbook, the Playbook replaces the Greeting for that channel. The Greeting page shows which events currently trigger the Greeting and which have been reassigned to a Playbook. To revert a channel to using the Greeting, remove the event from the Playbook. > **Warning** > > Assigning a Messaging or Voice conversation start event to a Playbook overrides the Greeting for that channel. End users on that channel will see the Playbook's first step instead of the Greeting response. Social channels and Email do not have Greetings, so assigning a conversation start event to a Playbook on these channels sets the Playbook as the first response — there is no Greeting to fall back to. **Greeting-first vs. user-message-first channels:** On Messaging and Voice, the AI Agent speaks first — the Playbook fires before the end user sends a message. On social channels and Email, the end user sends a message before the conversation start event fires. In this case, the Playbook has access to the end user's first message and can reason about their intent when generating responses. If the Playbook is not designed to address the original intent, that intent is stashed and picked up after the Playbook completes, so the end user's request is not lost. > **Warning** > > Availability rules on the Playbook still apply. If an end user on a Messaging or Voice channel does not meet the availability conditions, the conversation start event falls back to the Greeting. Playbooks can also be linked to [Proactive Outreach](/docs/automation/proactive-outreach/messaging#link-a-playbook) so they run when an end user engages with a proactive message. [Simulations](/docs/optimization/testing/simulations) support conversation start events — when a Playbook has an event assigned, simulations trigger that Playbook at the start of the conversation, matching production behavior. ### General Guidelines The General Guidelines pane is a rich text editor for instructions that apply to all end user interactions in the Playbook. Type `@` to reference API tools, Handoffs, Variables, Playbooks, Knowledge articles, and Exit. A reference tells the Agent which item applies. A reference does not run the item. ![General Guidelines pane](/_fern-img/605d3edbde54413ec0ff7d7148245a25ed064da49c54759f57853ec70e1faa0e.webp) The editor supports headings (H1, H2), bold text, bulleted lists, and numbered lists. Use it for: * **Tone and formatting** specific to this Playbook. * **Guardrails and boundaries** — what the Agent should and should not do. * **Knowledge references** — reference articles using `@ArticleName` mentions or instruct the Agent to search the knowledge base. * **Handoff, API tool, linked Playbook, and Exit references**: a reference is a name, not an action. The Agent reads the reference as the item's name. For a Handoff, the Agent reads the Handoff's handle. For a linked Playbook, the Agent reads "the linked playbook". Nothing runs. Use a reference when a rule must name the item. To hand off, call an API tool, run a linked Playbook, or exit at a point in the flow, add a `RUN` step at that point. * **Edge case handling** — fallback behavior for unexpected situations. General Guidelines are stateless — they apply throughout the entire conversation regardless of which step the Agent is currently on. This makes them ideal for cross-cutting rules that should not be embedded in any single step or section. The Agent also reads General Guidelines when it suspends the Playbook because the end user went off-topic. On those turns the Agent can use any Handoff, API tool, or Playbook the AI Agent allows. Write guidelines that make sense outside the step sequence. **Good General Guidelines content:** * "Always verify the end user's identity before sharing account-specific information." * "Never offer a refund greater than the original order value." * "If the end user asks about a topic not covered by this Playbook, search the knowledge base before handing off." * "Use a friendly, professional tone. Avoid jargon." * "Only `@Support` can approve a refund above \$100. Do not promise a refund in the chat." **Poor General Guidelines content:** * Step-specific instructions that belong in a particular step (for example, "In Step 3, ask for the order number" — write this directly in Step 3 instead). * Long, detailed procedures — structure these as steps within a section instead. * Guidance that only applies in one branch of the flow — place this in the relevant `IF/ELSE` branch instead. * A rule that hands off or runs a tool, for example "Hand off to `@Support` when the end user is upset" or "Follow `@Returns Process` for a return". A guideline cannot run the item. Add a `RUN` step where the Playbook must run it. > **Warning** > > General Guidelines cannot set or write variable values. To write a variable, use a `SET` or `ASK` step in the Playbook body. > **Warning** > > General Guidelines cannot run a Handoff, an API tool, a linked Playbook, or Exit. A reference names the item the Agent must use. To run the item, add a `RUN` step in the Playbook body. > **Note** > > Knowledge articles are scoped via availability rules configured on the Knowledge page. Reference them using `@ArticleName` or natural-language search instructions. ### Steps The Steps pane provides a navigable outline of all sections and steps in the Playbook. Each row displays the step number, keyword (`SEND`, `SET`, `RUN`, etc.), and a preview of the step's target — such as the API tool name for a `RUN` step or the variable name for a `SET` step. ![Steps pane](/_fern-img/be0cc61c93a98d70c253e59db10f471ef2e1cc4588dda41bf518c766495e7720.webp) Click any row to scroll directly to that step in the editor. ### Variables The Variables pane displays all variables referenced in the Playbook. Each variable row shows a reference count. Click a variable to expand it and see every step that reads or writes it, listed by step number and keyword. ![Variables pane](/_fern-img/8c89834fefb84da8df530d26584dbfa54405348f092e1b0986d56b594b02acb2.webp) ## Build your Playbook with sections and steps The body of a Playbook is organized into **sections** and **steps**. ### Sections Sections represent stages of the end user journey — for example, "Verify identity", "Look up order", or "Process refund". Each section contains a sequence of steps that execute in order. * Add sections to group related steps and make the workflow easier to read. * Sections execute in order unless redirected by an `IF/ELSE` branch or `GO TO` jump. * `GO TO` can jump to steps in other sections, enabling cross-section flows. ### Steps Within each section, add steps to define what the AI Agent does. The six step types are: | Step | What it does | | :-------- | :-------------------------------------------------------------------- | | `SEND` | Send a message to the end user. | | `SET` | Assign a variable value silently (Exact value or Use reasoning mode). | | `ASK` | Ask the end user for a value. | | `RUN` | Execute an API tool, Handoff, linked Playbook, or Exit. | | `IF/ELSE` | Branch the flow based on conditions. | | `GO TO` | Jump to a specific step. | For complete field-level documentation, including modes, validation rules, and examples for each step type, see [Step reference](/docs/automation/playbooks/step-reference). **To add a step:** 1. In a section, click **Add Step**. 2. Select a step type. 3. Configure the step's fields (for example, the message content for a `SEND` step, or the variable and instruction for an `ASK` step). 4. Click the step icon to open that step's configuration in the side pane. Applies to `ASK`, `SEND`, and `SET`. ## Reference API tools, Handoffs, Exits, and Variables Playbooks connect to external systems and end user data through references to API tools, Handoffs, Exits, and Variables. ### API tools and Handoffs In any step that supports references, type `@` to search for existing [API tools](/docs/automation/tools/api-tools/api-tool-control) and [Handoffs](/docs/handoffs). Select one to insert a reference. If no results appear, click **+ Create API tool** or **+ Create Handoff** to define a new item without leaving the editor. ![Playbooks: Actions and Handoffs](/_fern-img/8f01a66113231ecfc510cae8435749a3147cc19dd352f57e775bf4a135c16dd0.webp) Use `RUN` steps to execute API tools (API calls) and trigger Handoffs (escalation to human agents) at specific points in the workflow. > **Note** > > A reference inside exact-words `SEND` or `ASK` text is removed from the message the end user receives. The words around it stay. Write the name in plain words in exact-words text. Put references in instructions or in General Guidelines. Use a `RUN` step to run the item. > **Warning** > > If your Playbooks trigger Handoffs and you have multiple Handoffs live in your instance, make sure each one has a **clearly distinct name and description** to improve routing accuracy. > **Note** > > API tool names longer than 64 characters can cause errors and fallbacks to the first available handoff. Rename duplicated API tools to keep names short. ### Exits Use a `RUN` step with the Exit option to deterministically end a Playbook. Type `@Exit` to find the **Exit Playbook** option in the reference menu — it appears in the same reference dropdown shown above. > **Warning** > > Always use explicit exits at the end of your flows. Every Playbook should have a clear termination point to ensure predictable behavior. ### Variables Playbooks support [Global Variables, Sensitive Variables, and Metavariables](/docs/automation/variables). Reference variables in any step to personalize the flow. * **Reading**: Reference a variable to shape logic (for example, check `@order_status` in an `IF/ELSE` branch). Metavariables are read-only. * **Writing**: `SET` and `ASK` steps write to Global Variables and Sensitive Variables. Variables cannot be written from General Guidelines. > **Error** > > Always select the `@variable` pill when referencing variables. Typing variable names manually is not recognized by the system. ### Knowledge Playbooks can reference [Knowledge](/docs/knowledge) sources — including third-party knowledge bases, Ada-created articles, and web-scraped content. * **Direct reference**: Use `@ArticleName` in General Guidelines to reference a specific article. * **`SEND` steps**: In a Contextual AI-generated `SEND` step, select **Search Knowledge** or an article from the `@` menu. The step grounds its reply in the search results or in the article. See [Search Knowledge in `SEND` steps](/docs/automation/playbooks/step-reference#search-knowledge-in-send-steps). * **Native search**: The [runtime harness](#runtime-harness) can pause Playbook execution to perform a Knowledge search when it detects the end user needs information, then resume where it left off. You can also add natural-language search instructions in General Guidelines to guide this behavior. > **Note** > > Articles cannot be referenced by URL. Knowledge references do not override availability rules. ## Link a Playbook Break large workflows into smaller, reusable components by linking Playbooks together. ![Linked Playbooks](/_fern-img/473df6f8200e88457d01b0ad3f3fb8812a05d930c386da5c57f57b3faac8b1a2.webp) ### Version compatibility Linked Playbooks must be of the same version. A Playbook cannot link to a Playbook (Classic), and a Playbook (Classic) cannot link to a Playbook. If you are migrating from Classic, update all Playbooks in a linked chain together so that parent and child Playbooks are on the same version. ### How linking works Linked Playbooks use call-and-return logic: the parent calls a child via a `RUN` step, the child runs to completion, then control automatically returns to the parent. The child does not branch — it always returns to the exact point in the parent where it was called. > **Warning** > > Always end child Playbooks with an explicit Exit (`RUN` > Exit). Without an explicit Exit, the child may not return control to the parent reliably. ### How to link Use a `RUN` step with the linked Playbook option. The parent pauses while the child runs, then continues once the child exits. * You can link multiple Playbooks within a single parent with no limit on how many a parent may call. * Treat the top-level Playbook as the **parent** and all linked Playbooks as **children**. * Keep child Playbooks focused on a **single, structured task** to ensure they remain reusable. ### Restrict child Playbooks When a Playbook exists only to support another — meaning it should never trigger on its own — enable **AI Agent can only use this Playbook within other Playbooks** in the [Playbook Details](#playbook-details) pane. This prevents accidental triggering and reduces misfires. ![Restrict child Playbook](/_fern-img/1ea70a41d7478dc0a85d5e8c416b73f4e8060ef094f6e1f75e9d1832749c3f10.webp) --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).