Allo

Save call flow draft

Creates or updates the working draft of a phone number's call flow. The draft is validated leniently and is not live until published. Optimistic concurrency…

PUT/v2/api/numbers/{number}/call_flow/draft

Behavior

Creates or updates the working draft of a phone number's call flow. The draft is validated leniently and does not affect live routing until you publish it. The {number} path parameter is the Allo phone number in E.164 format.

Send the full definition document and the schema_version it conforms to.

Engine subset

engine_subset decides how much of your flow runs on live calls. Send "engine_subset": "FULL_FLOW" for any flow you build through the API.

ValueWhat runs on a live call
FULL_FLOWThe whole tree: every node and branch in definition
NESTED_IVROnly the root phone menu, and only on a line already set to answer with a phone menu. Publishing replaces that menu's keys with the flow's root keys. A key that leads to a nested menu, a condition, a voicemail or a hang-up node is removed from the live menu. This mode exists for lines that only had a simple phone menu

When you omit engine_subset, Allo infers it from the nodes. A flow with a business-hours, contact-property, country-code or send-SMS node is FULL_FLOW. Any other flow is inferred as NESTED_IVR, even one with nested menus, rings and an AI receptionist, so only its root menu would run.

Once a line's flow is FULL_FLOW, a later draft cannot downgrade it to NESTED_IVR: the request keeps FULL_FLOW.

Going live

Saving a draft never changes live routing. There are two ways to put it on the air:

  • Publish it yourself with Publish call flow, passing the lock_version from this response. This changes live inbound routing immediately.
  • Hand it to a person using the confirmation_url in this response: a link where a signed-in user opens this draft, reviews it, and publishes it. Prefer this when a human should approve the change.

Treat confirmation_url as opaque: pass it through verbatim; never build it from a hardcoded app host or parse it. (It is present only while the response status is DRAFT.)

Concurrency

  • lock_version: pass the value from the draft you read. Omit it (or send null) to upsert the draft without a concurrency check. A stale value returns 409 CALL_FLOW_STALE_LOCK.
  • base_published_version: the published version your edit is based on. Read it from the version of Get call flow when its status is PUBLISHED. Omitting it means "no published version", so on a line that already has a published flow the request returns 409 CALL_FLOW_CONCURRENT_EDIT. The same error is returned if someone published a new version while you were editing.

Errors

  • 400 CALL_FLOW_SCHEMA_VERSION_MISMATCH: schema_version does not match the server's current version.
  • 400 CALL_FLOW_INVALID: the definition is malformed or failed validation.
  • 404 PHONE_NUMBER_NOT_FOUND: the number is not one of your account's numbers.
  • 409 CALL_FLOW_STALE_LOCK / 409 CALL_FLOW_CONCURRENT_EDIT: see Concurrency above.

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

numberstringrequired

Allo phone number in E.164 format

Body

definitionobjectrequired

The call flow tree document (opaque; camelCase keys).

schema_versionintegerrequired

Must match the server's current call flow schema version.

lock_versioninteger | null

The lock_version of the draft you are updating; omit or null to upsert without a concurrency check.

base_published_versioninteger | null

The published version your edit is based on; a mismatch means someone published mid-edit (409).

engine_subsetenum<string>

FULL_FLOW runs the whole tree on live calls. NESTED_IVR runs only the root phone menu: its keys that lead to a nested menu, a condition or a voicemail node do nothing. Send FULL_FLOW for flows you build through the API. When omitted, it is inferred from the nodes: FULL_FLOW only if the flow has a business-hours, contact-property, country-code or send-SMS node, otherwise NESTED_IVR. A line whose flow is already FULL_FLOW keeps it.

NESTED_IVRFULL_FLOW

Responses

200The saved draft
dataobject

A version of a phone number's call flow.

11 fields
idstring | null

The call flow version ID. Null for a synthesized (never-persisted) flow.

flow_idstring | null

The parent call flow ID. Null for a synthesized flow.

versioninteger

Monotonic version number within the flow.

statusenum<string>

DRAFT (working copy), PUBLISHED (live), or SYNTHESIZED (in-memory representation of a legacy IVR-only line).

DRAFTPUBLISHEDSYNTHESIZED

lock_versioninteger

Optimistic-concurrency token; pass it back on the next draft save.

schema_versioninteger

The call flow schema version this definition conforms to.

engine_subsetenum<string>

FULL_FLOW runs the whole tree on live calls. NESTED_IVR runs only the root phone menu: its keys that lead to a nested menu, a condition or a voicemail node do nothing.

NESTED_IVRFULL_FLOW

numberstring | null

E.164 of the line this flow routes. Null for a never-persisted SYNTHESIZED flow.

confirmation_urlstring | null

A link where a signed-in user reviews this draft and publishes it. Present only on a DRAFT (a PUBLISHED or SYNTHESIZED version has nothing to confirm). Use it when a person should approve the change; to go live without one, call POST /v2/api/numbers/{number}/call_flow/publish. Treat it as opaque: pass it through verbatim, and never construct or parse it.

entry_node_idstring

The id of the entry node in definition.nodes.

definitionobject

The call flow tree document (opaque; camelCase keys).

400
401
404
409
429