Create a playbook

import requests
url = "https://example.ada.support/api/v2/playbooks/"
payload = {
    "name": "Refund flow",
    "sections": [
        {
            "id": "5df263b7db5a7e6ea03fae9b",
            "title": "Main",
            "steps": [
                {
                    "id": "5df263b7db5a7e6ea03faea0",
                    "type": "send",
                    "message": "Let me pull up that order."
                }
            ]
        }
    ],
    "description": "How to process a refund",
    "general_instructions": "Confirm the order number before issuing a refund."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "id": "65a17e3f43bec88e2792d0eb",
  "name": "Refund flow",
  "version": 2,
  "enabled": false,
  "description": "How to process a refund",
  "general_instructions": "Confirm the order number before issuing a refund.",
  "sections": [
    {
      "id": "5df263b7db5a7e6ea03fae9b",
      "title": "Main",
      "steps": [
        {
          "id": "5df263b7db5a7e6ea03faea0",
          "type": "send",
          "message": "Let me pull up that order."
        }
      ]
    }
  ],
  "can_run_standalone": true,
  "referenced_articles": [],
  "tags": [],
  "acknowledgment_instruction": null,
  "chat_acknowledgment_override": false,
  "on_human_request": "exit_playbook",
  "on_off_topic": "exit_playbook",
  "on_off_script": "search_knowledge",
  "availability_rules": null
}

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

namestringRequired1-128 characters

Display name for the playbook

sectionslist of objectsRequired

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.

descriptionstringOptional<=512 characters

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.

enabledbooleanOptionalDefaults to false

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

general_instructionsstringOptional

Instructions that apply across the whole playbook

on_human_requestenumOptional

Deviation behavior when the user asks for a human

on_off_topicenumOptional

Deviation behavior when the user goes off topic

on_off_scriptenumOptional

Deviation behavior when the conversation goes off script

acknowledgment_instructionstring or nullOptional<=500 characters

Instruction for the acknowledgment message

chat_acknowledgment_overridebooleanOptional

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

availability_rulesobject or nullOptional

The structured rule gating when the Agent uses this Playbook; omit or send null for no rule. An unknown variable id or a malformed rule is rejected with a 400.

Response

Created

idstringRead-only

The unique identifier for the playbook

namestring<=128 characters

Display name for the playbook

versionintegerRead-only=2

The playbook schema version. Always 2 on this surface.

enabledboolean

Whether the playbook is enabled. False means draft.

descriptionstringOptional

Short description of the playbook (routing-facing)

general_instructionsstring or nullOptional

Instructions that apply across the whole playbook

sectionslist of objects or nullOptionalRead-only

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

can_run_standalonebooleanOptional

Whether the playbook can be triggered on its own

referenced_articleslist of stringsOptional

Ids of knowledge articles referenced by the playbook

tagslist of stringsOptional

Tag ids applied to the playbook

acknowledgment_instructionstring or nullOptional<=500 characters

Instruction for the acknowledgment message

chat_acknowledgment_overridebooleanOptional

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

on_human_requestenumOptional

Deviation behavior when the user asks for a human

on_off_topicenumOptional

Deviation behavior when the user goes off topic

on_off_scriptenumOptional

Deviation behavior when the conversation goes off script

availability_rulesobject or nullOptionalRead-only

The structured rule that gates when the Agent uses this Playbook, with variables referenced by id, or null when no rule is attached

Errors

400

Bad Request Error

401

Unauthorized Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error