Allo

Enregistrer le brouillon du flux d'appel

Crée ou met à jour le brouillon de travail du flux d'appel d'un numéro. Le brouillon est validé de manière souple et n'affecte pas le routage en direct tant…

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

Comportement

Crée ou met à jour le brouillon de travail du flux d'appel d'un numéro. Le brouillon est validé de manière souple et n'affecte pas le routage en direct tant qu'il n'est pas publié. Le paramètre de chemin {number} est le numéro Allo au format E.164.

Envoyez le document definition complet ainsi que la schema_version à laquelle il se conforme.

Sous-ensemble du moteur

engine_subset détermine quelle part de votre flux s'exécute sur les appels réels. Envoyez "engine_subset": "FULL_FLOW" pour tout flux que vous construisez via l'API.

ValeurCe qui s'exécute sur un appel réel
FULL_FLOWL'arbre entier : chaque nœud et chaque branche de definition
NESTED_IVRUniquement le menu téléphonique racine, et seulement sur une ligne déjà réglée pour répondre par un menu téléphonique. La publication remplace les touches de ce menu par celles de la racine du flux. Une touche qui mène à un sous-menu, une condition, une messagerie ou un raccrochage est retirée du menu en direct. Ce mode existe pour les lignes qui n'avaient qu'un menu téléphonique simple

Si vous omettez engine_subset, Allo le déduit des nœuds. Un flux qui contient un nœud horaires d'ouverture, propriété de contact, indicatif pays ou envoi de SMS est FULL_FLOW. Tout autre flux est déduit en NESTED_IVR, même s'il contient des sous-menus, des sonneries et une réceptionniste IA : seul son menu racine s'exécuterait alors.

Une fois que le flux d'une ligne est FULL_FLOW, un brouillon ultérieur ne peut pas le rétrograder en NESTED_IVR : la requête conserve FULL_FLOW.

Mise en ligne

Enregistrer un brouillon ne modifie jamais le routage en direct. Deux façons de le mettre en ligne :

  • Le publier vous-même avec Publier le flux d'appel, en passant la lock_version de cette réponse. Le routage des appels entrants en direct change immédiatement.
  • Le confier à une personne via la confirmation_url de cette réponse : un lien où un utilisateur connecté ouvre ce brouillon, le vérifie et le publie. Préférez cette option lorsqu'un humain doit approuver la modification.

Traitez la confirmation_url comme opaque : renvoyez-la telle quelle, ne la reconstruisez jamais à partir d'un hôte d'application codé en dur et ne l'analysez pas. (Elle n'est présente que lorsque le status de la réponse est DRAFT.)

Concurrence

  • lock_version : passez la valeur du brouillon que vous avez lu. Omettez-la (ou envoyez null) pour mettre à jour le brouillon sans contrôle de concurrence. Une valeur périmée renvoie 409 CALL_FLOW_STALE_LOCK.
  • base_published_version : la version publiée sur laquelle repose votre modification. Lisez-la dans le champ version de Récupérer le flux d'appel quand son status vaut PUBLISHED. L'omettre signifie « aucune version publiée » : sur une ligne qui a déjà un flux publié, la requête renvoie 409 CALL_FLOW_CONCURRENT_EDIT. La même erreur est renvoyée si quelqu'un a publié une nouvelle version pendant votre édition.

Erreurs

  • 400 CALL_FLOW_SCHEMA_VERSION_MISMATCH : schema_version ne correspond pas à la version actuelle du serveur.
  • 400 CALL_FLOW_INVALID : le definition est mal formé ou a échoué à la validation.
  • 404 PHONE_NUMBER_NOT_FOUND : le numéro ne fait pas partie des numéros de votre compte.
  • 409 CALL_FLOW_STALE_LOCK / 409 CALL_FLOW_CONCURRENT_EDIT : voir Concurrence ci-dessus.

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Paramètres de chemin

numberstringrequis

Allo phone number in E.164 format

Corps

definitionobjectrequis

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

schema_versionintegerrequis

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

Réponses

200The saved draft
dataobject

A version of a phone number's call flow.

11 champs
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