Playbooks

Create a playbook

Create a version 2 playbook. New playbooks default to draft (enabled: false); set enabled: true to validate the full step graph and activate on create.

post/v2/playbooks/

Request

Base URL: https://example.ada.support/api
URL: https://example.ada.support/api/v2/playbooks/
Auth: HTTP bearer

Request body

namestring required

Display name for the playbook

descriptionstring

Short description of the playbook (routing-facing). Required to be non-empty when enabled is true; an active playbook without one is rejected with 422.

sectionsPlaybookCreateSectionsItems[] required

The ordered sections of the playbook. Each section holds an ordered list of steps (send, set, ask, run, if_else, go_to). Every section and step needs a caller-generated unique ObjectId string.

enabledboolean

Whether the playbook is enabled. False (the default) creates a draft; true validates the full step graph and activates the playbook.

general_instructionsstring

Instructions that apply across the whole playbook

on_human_request'exit_playbook' | 'stay_in_playbook'

Deviation behavior when the user asks for a human

on_off_topic'exit_playbook' | 'stay_in_playbook'

Deviation behavior when the user goes off topic

on_off_script'search_knowledge' | 'skip_knowledge'

Deviation behavior when the conversation goes off script

acknowledgment_instructionstring nullable

Instruction for the acknowledgment message

chat_acknowledgment_overrideboolean

Request an acknowledgment for this playbook on messaging platforms even when the Agent-wide messaging acknowledgment setting (enable_acknowledgment_messages) is off. Never suppresses.

Response

Created

idstring required

The unique identifier for the playbook

namestring required

Display name for the playbook

descriptionstring

Short description of the playbook (routing-facing)

versioninteger required

The playbook schema version. Always 2 on this surface.

enabledboolean required

Whether the playbook is enabled. False means draft.

general_instructionsstring nullable

Instructions that apply across the whole playbook

sectionsPlaybookSectionsItems[] nullable

The ordered sections of the playbook. Each section holds an ordered list of steps (send, set, ask, run, if_else, go_to).

can_run_standaloneboolean

Whether the playbook can be triggered on its own

referenced_articlesstring[]

Ids of knowledge articles referenced by the playbook

tagsstring[]

Tag ids applied to the playbook