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.
| Value | What runs on a live call |
|---|---|
FULL_FLOW | The whole tree: every node and branch in definition |
NESTED_IVR | Only 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_versionfrom this response. This changes live inbound routing immediately. - Hand it to a person using the
confirmation_urlin 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 sendnull) to upsert the draft without a concurrency check. A stale value returns409 CALL_FLOW_STALE_LOCK.base_published_version: the published version your edit is based on. Read it from theversionof Get call flow when itsstatusisPUBLISHED. Omitting it means "no published version", so on a line that already has a published flow the request returns409 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_versiondoes not match the server's current version.400 CALL_FLOW_INVALID: thedefinitionis 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.