> 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. # Create a playbook POST https://example.ada.support/api/v2/playbooks/ Content-Type: application/json 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. Reference: https://docs.ada.cx/reference/playbooks/create ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects a PlaybookCreate. - `name` (string, required) — Display name for the playbook - `sections` (list of PlaybookCreateSectionsItems, 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. - `description` (string, optional) — 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. - `enabled` (boolean, optional, default: false) — Whether the playbook is enabled. False (the default) creates a draft; true validates the full step graph and activates the playbook. - `general_instructions` (string, optional) — Instructions that apply across the whole playbook - `on_human_request` (enum, optional) — Deviation behavior when the user asks for a human - Allowed values: `exit_playbook`, `stay_in_playbook` - `on_off_topic` (enum, optional) — Deviation behavior when the user goes off topic - Allowed values: `exit_playbook`, `stay_in_playbook` - `on_off_script` (enum, optional) — Deviation behavior when the conversation goes off script - Allowed values: `search_knowledge`, `skip_knowledge` - `acknowledgment_instruction` (string, optional, nullable) — Instruction for the acknowledgment message - `chat_acknowledgment_override` (boolean, optional) — 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_rules` (AvailabilityRule, optional, nullable) — 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 ### 201 Created - `id` (string, required) — The unique identifier for the playbook - `name` (string, required) — Display name for the playbook - `version` (integer, required) — The playbook schema version. Always 2 on this surface. - `enabled` (boolean, required) — Whether the playbook is enabled. False means draft. - `description` (string, optional) — Short description of the playbook (routing-facing) - `general_instructions` (string, optional, nullable) — Instructions that apply across the whole playbook - `sections` (list of PlaybookSectionsItems, optional, 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_standalone` (boolean, optional) — Whether the playbook can be triggered on its own - `referenced_articles` (list of string, optional) — Ids of knowledge articles referenced by the playbook - `tags` (list of string, optional) — Tag ids applied to the playbook - `acknowledgment_instruction` (string, optional, nullable) — Instruction for the acknowledgment message - `chat_acknowledgment_override` (boolean, optional) — 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_request` (enum, optional) — Deviation behavior when the user asks for a human - Allowed values: `exit_playbook`, `stay_in_playbook` - `on_off_topic` (enum, optional) — Deviation behavior when the user goes off topic - Allowed values: `exit_playbook`, `stay_in_playbook` - `on_off_script` (enum, optional) — Deviation behavior when the conversation goes off script - Allowed values: `search_knowledge`, `skip_knowledge` - `availability_rules` (AvailabilityRule, optional, nullable) — 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 Bad Request - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 401 Unauthorized Error Unauthorized - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 409 Conflict Error Conflict - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 422 Unprocessable Entity Error Unprocessable Content - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 429 Too Many Requests Error Too Many Requests - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 500 Internal Server Error Internal Server Error - `errors` (list of ErrorsErrorsItems, required) — A list of errors ## Types ### PlaybookCreateSectionsItems ### AvailabilityRule A two-level tree of conditions that determines availability based on variable values during a conversation. The root group has a `match` combinator and a list of conditions or condition groups. A rule may contain at most 1000 conditions in total, counting every condition across the root and all nested condition groups. - `match` (enum, required) — Whether all conditions must pass (`all`) or any one condition must pass (`any`). - Allowed values: `all`, `any` - `conditions` (list of AvailabilityRuleConditionsItems, required) — List of conditions or condition groups. Must contain at least one entry. Each entry is either a `Condition` object (with `variable`, `operator`, and optional `value`) or a `ConditionGroup` object (with its own `match` and nested `conditions` list). ### PlaybookSectionsItems ### ErrorsErrorsItems - `type` (string, required) — The error type - `message` (string, required) — The error message - `details` (string, optional, nullable) — Extra information about the error ### AvailabilityRuleConditionsItems ### AvailabilityRuleCondition A single condition comparing a variable to a value. - `variable` (AvailabilityRuleConditionVariable, required) — The variable to test, referenced by `id`. Look up the ids for your Agent through the variables endpoint. Not every variable can be used in a rule; referencing one that can't returns a `400`. - `operator` (enum, required) — The comparison operator. Unary operators (`is_set`, `is_not_set`) must not include a `value` field. - Allowed values: `equals`, `does_not_equal`, `greater_than`, `less_than`, `starts_with`, `ends_with`, `contains`, `does_not_contain`, `is_set`, `is_not_set` - `value` (AvailabilityRuleConditionValue, optional) — The value to compare against. Omit for unary operators (`is_set`, `is_not_set`). - `case_sensitive` (boolean, optional) — Whether the comparison is case-sensitive. Defaults to `false`. Only meaningful for the equality (`equals`, `does_not_equal`) and string (`starts_with`, `ends_with`, `contains`, `does_not_contain`) operators. Omitted from responses when `false`. ### AvailabilityRuleConditionGroup A nested group of conditions inside a rule's top-level `conditions` list. Condition groups may contain only `Condition` objects — further nesting is not supported. - `match` (enum, required) — Whether all conditions must pass (`all`) or any one condition must pass (`any`). - Allowed values: `all`, `any` - `conditions` (list of AvailabilityRuleCondition, required) — List of conditions inside this condition group. Must contain at least one entry. ### AvailabilityRuleConditionVariable The variable to test, referenced by `id`. Look up the ids for your Agent through the variables endpoint. Not every variable can be used in a rule; referencing one that can't returns a `400`. - `id` (string, required) — The id of the variable. ### AvailabilityRuleConditionValue The value to compare against. Omit for unary operators (`is_set`, `is_not_set`). ## Examples **Request** ```json { "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." } ``` **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 } ``` **SDK Code** ```python 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 ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://example.ada.support/api/v2/playbooks/'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"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."}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://example.ada.support/api/v2/playbooks/" payload := strings.NewReader("{\n \"name\": \"Refund flow\",\n \"sections\": [\n {\n \"id\": \"5df263b7db5a7e6ea03fae9b\",\n \"title\": \"Main\",\n \"steps\": [\n {\n \"id\": \"5df263b7db5a7e6ea03faea0\",\n \"type\": \"send\",\n \"message\": \"Let me pull up that order.\"\n }\n ]\n }\n ],\n \"description\": \"How to process a refund\",\n \"general_instructions\": \"Confirm the order number before issuing a refund.\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://example.ada.support/api/v2/playbooks/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Refund flow\",\n \"sections\": [\n {\n \"id\": \"5df263b7db5a7e6ea03fae9b\",\n \"title\": \"Main\",\n \"steps\": [\n {\n \"id\": \"5df263b7db5a7e6ea03faea0\",\n \"type\": \"send\",\n \"message\": \"Let me pull up that order.\"\n }\n ]\n }\n ],\n \"description\": \"How to process a refund\",\n \"general_instructions\": \"Confirm the order number before issuing a refund.\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://example.ada.support/api/v2/playbooks/") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"Refund flow\",\n \"sections\": [\n {\n \"id\": \"5df263b7db5a7e6ea03fae9b\",\n \"title\": \"Main\",\n \"steps\": [\n {\n \"id\": \"5df263b7db5a7e6ea03faea0\",\n \"type\": \"send\",\n \"message\": \"Let me pull up that order.\"\n }\n ]\n }\n ],\n \"description\": \"How to process a refund\",\n \"general_instructions\": \"Confirm the order number before issuing a refund.\"\n}") .asString(); ``` ```php request('POST', 'https://example.ada.support/api/v2/playbooks/', [ 'body' => '{ "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 ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://example.ada.support/api/v2/playbooks/"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Refund flow\",\n \"sections\": [\n {\n \"id\": \"5df263b7db5a7e6ea03fae9b\",\n \"title\": \"Main\",\n \"steps\": [\n {\n \"id\": \"5df263b7db5a7e6ea03faea0\",\n \"type\": \"send\",\n \"message\": \"Let me pull up that order.\"\n }\n ]\n }\n ],\n \"description\": \"How to process a refund\",\n \"general_instructions\": \"Confirm the order number before issuing a refund.\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "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." ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://example.ada.support/api/v2/playbooks/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```