Skip to main content
PUT
Save call flow draft
Required scope: PHONE_NUMBERS_WRITE

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. 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.

Authorizations

Authorization
string
header
required

Path Parameters

number
string
required

Allo phone number in E.164 format

Example:

"+14155551234"

Body

application/json
definition
object
required

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

schema_version
integer
required

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

Example:

1

lock_version
integer | null

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

base_published_version
integer | null

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

engine_subset
enum<string> | null

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.

Available options:
NESTED_IVR,
FULL_FLOW

Response

The saved draft

data
object

A version of a phone number's call flow.