Playbooks

Update a playbook

Partially update a version 2 playbook in place (same id). Only the fields present in the body change; omit enabled to leave the active state unchanged. Setting enabled to true validates the full step graph and activates the playbook.

patch/v2/playbooks/{playbook_id}

Request

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

Path parameters

playbook_idstring required

The id of the playbook

Request body

namestring

Display name for the playbook

descriptionstring

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

sectionsPlaybookUpdateSectionsItems[]

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. Editing sections is rejected with 422 on a Playbook that has send-step attachments. Add or edit those in the dashboard. Every other field stays editable through the API.

enabledboolean

Set the playbook's active state. Omit to leave it unchanged. Setting true validates the full step graph before activating.

general_instructionsstring nullable

Instructions that apply across the whole playbook. Send null to clear.

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

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