Full authoring guide

This page covers triggering playbooks from chat widgets. For building playbooks from scratch, step type reference, provision as code, and testing, see the Playbooks Authoring Guide.

Playbooks

Playbooks are automated multi-step workflows that can be triggered by the AI agent, by events (like a new conversation), or manually.

Creating a Playbook

1. Navigate to Playbooks
2. Click New Playbook
3. Add steps in order, each step performs one action

Step Types

Playbooks consist of sequential steps. Each step runs after the previous one completes:

Step Type	Description
AI Prompt	Sends a prompt to the AI and uses the response
HTTP Request	Makes an API call to an external service
Transform	Processes data from previous steps

Inputs

Playbooks accept key-value inputs that can be referenced in step templates:

Hello {{.name}}, your order {{.order_id}} has been processed.

When triggered by the agent, the AI provides the inputs based on the conversation context.

Triggering from Agent Tools

To allow the AI to trigger a playbook:

1. Open the widget settings
2. Enable the Playbook Trigger tool
3. Select which playbooks the widget is allowed to trigger

Only explicitly allowed playbooks can be triggered, the AI cannot run arbitrary playbooks.

Triggering from Events

Playbooks can also be triggered by widget events through the event router:

• New conversation started
• Conversation archived
• Custom events via API

Configure event triggers in the Routers section.

Execution

When a playbook runs:

1. Steps execute sequentially
2. Each step can access outputs from previous steps
3. If a step fails, the playbook stops and reports the error
4. Timeout: 30 seconds per execution (when triggered by agent)

Scheduled Playbooks

Playbooks can run on a recurring schedule, hourly syncs, daily reports, weekly digests, etc.

Setting up a schedule

1. Open a playbook and go to the Schedule tab
2. Set the Trigger type to schedule
3. Enter a Cron expression (standard 5-field format, minimum interval: 1 hour)
4. Pick a Timezone (IANA format, e.g. Europe/Amsterdam)
5. Enable the playbook

Common cron examples:

Expression	Meaning
0 9 * * *	Every day at 9:00 AM
0 */2 * * *	Every 2 hours
0 9 * * 1	Every Monday at 9:00 AM
0 0 1 * *	First day of the month at midnight

Pause and resume

You can pause a schedule without removing it. Paused playbooks keep their cron expression and resume from the next occurrence when unpaused.

Auto-pause on failures

If a scheduled playbook fails 3 times in a row, it is automatically paused to prevent runaway costs. The failure counter resets when a run succeeds or when you manually resume the schedule.

Monitoring

View playbook runs in the Playbook Runs section. Each run shows:

• Status (success, failed, timeout)
• Duration
• Step-by-step output
• Trigger source (agent, event, manual)