Conversation Design

Cette page n’est pas encore disponible en français. Vous consultez la version anglaise.

A Conversation Design is the document you read from GET /v1/conversations/{id}/design and write to PUT /v1/conversations/{id}/design (see Resources). It’s a portable representation of what the conversation says and does — a set of steps wired together by named outcomes — with no implementation detail (no internal node types, editor coordinates, or secrets) ever included. Reading a document and writing it back unchanged always round-trips exactly.

Machine-readable schema: conversation-design.v1.schema.json.

Document shape

{
  "schemaVersion": "cd/1",
  "entry": { "stepId": "greeting-1" },
  "steps": {
    "greeting-1": { "kind": "greeting", "introLine": "Hi, thanks for calling — this is an AI assistant.", "on": { "next": "talk-1" } },
    "talk-1": { "kind": "talk", "topic": "answer questions about our product", "on": { "done": "end-1" } },
    "end-1": { "kind": "end" }
  },
  "knowledge": [],
  "variables": [],
  "integrations": [],
  "compliance": { "aiDisclosure": { "greeting-1": { "status": "ok" } } }
}

Field	Meaning
`schemaVersion`	Always `"cd/1"`.
`entry`	`{ stepId, alternates? }` — where the conversation starts (`alternates` for more than one entry point).
`steps`	Map of step id → step (see below). Step ids are stable across reads and writes — outcomes and references point at them.
`knowledge?`	Knowledge items referenced from `talk` steps (see below).
`variables?`	Variables collected during the conversation.
`integrations?`	References to the project’s integrations (id + kind only — never credentials).
`hooks?`	`{ before?, after? }` — pre-call and post-call side-effect graphs (see below).
`compliance?`	Read-only. The AI-disclosure check result per step (see below).
`layout?`	Editor node coordinates, carried through opaquely.

Every object in the document is closed — an unrecognized field is rejected on write.

Steps

Each step has a kind and, under on, its outcomes (each naming the target step id to move to next).

`kind`	Fields	Outcomes
`greeting`	`introLine?`, `persona? {whoAmI?, purpose?}`	`next`
`talk`	`topic`, `knowledgeRefs?`, `strict?`	`done`, `offTopic`
`route`	`ask?`, `question?`, `options? [{id, title?, description?, target?}]`	`default` + each option’s `target`
`collect`	`format` (`text`\|`number`\|`object`), `prompt`, `variable?`	`answered`, `fallback`
`keypad`	`prompt`, `variable?`, `timeoutSeconds?`	`completed`, `timeout`
`confirm`	`prompt`	`yes`, `no`
`recordingConsent`	`prompt`	`consent`, `decline`
`end`	`summarize?`, `allowCancel?`	`cancel?`
`transfer`	`target {type: internal\|phone, phoneNumber?}`, `timeoutSeconds?`	`timeout`
`callback`	`schedule?`, `timeFrames?`, `askForName?`, `integrationRef?`	`success`, `failure`

A route option needs either a target, or both title and description — one of title/ description without the other, or neither the pair nor a target, is rejected.

A handful of step kinds are reserved for future use (evaluate, logic, agent, say) — a conversation using one of these can’t currently be read through this API (501 unsupported_step); edit it in the dashboard instead.

Root collections

knowledge[] — { id, kind: "knowledgeBase", knowledgeBaseId } or { id, kind: "text", text }. Referenced by a talk step’s knowledgeRefs.
variables[] — { id, name?, type: "text" | "number" | "object" }. Written by collect/ keypad steps and readable in prompts and hooks.
integrations[] — { id, kind: "crm" | "calendar" | "knowledge", integrationId }. Only a reference — credentials and configuration stay on the project’s Integrations resource. On write, an integrationId your project doesn’t have is rejected (422 unknown_integration_ref), and a ref whose kind doesn’t match the integration’s actual kind is rejected too (422 integration_kind_mismatch).

Hooks

hooks.before and hooks.after are graphs of side-effect actions that run before or after the conversation itself: webhook, fetch, condition, setVariable, sendSms, crmLookup, crmWrite. A hook node’s transition can re-enter the conversation graph at a named step. Webhook signing secrets are never returned in full — only a display hint.

Compliance (read-only)

compliance.aiDisclosure reports, per step, whether that step’s spoken line was recognized as clearly disclosing the caller is speaking with an AI ({ status, checkedText, reason? }). This is computed by the server and is read-only — anything sent under compliance on a write is ignored.

Saving a design

PUT /v1/conversations/{id}/design runs, in order:

AI-disclosure check — if you changed a greeting.introLine or recordingConsent.prompt, its text must clearly tell the caller they’re speaking with an AI (checked in German, English, French, and Italian). An unchanged line keeps its previous result. Failing this is 422 ai_disclosure_required.
Structural validation — invalid transitions, invalid knowledge/integration/layout references, and similar document-shape problems are rejected before anything is saved (see Errors for the specific codes).
Server-side validation against the full conversation engine. A rejected design is 422 design_invalid with issues: [{ stepId, message }]; if this check can’t be reached at all, nothing is saved and the response is 503 validation_unavailable.
Plan limits — exceeding your plan’s node limit is 422 plan_limit_exceeded.
Save = publish — a successful save both creates the new version and makes it active in one step. There’s no separate draft state.

The response is 201 with the saved document (after a full round-trip through the format, so it reflects exactly what will be read back).

Also see

Resources — the Conversation and version operations this document is read from and written to.
Errors — the full error code reference.