Sign in
Flow

Run one turn of the flow builder conversation.

Changed on

Not released and not yet evaluated by a human; do not build on it. There is no on/off setting: wherever the platform key is configured this endpoint answers and the platform pays for each call.

Sends the whole conversation so far and receives the builder's next message, plus a draft flow once it has enough information. Nothing is saved: the draft only fills the flow editor, and the user reviews it and saves it through POST /flows.

The server keeps no conversation. The client sends the full history and the latest draft on every turn. Each message must be user or assistant, and the last one must be user. Strict alternation is not enforced.

supported_action_types is the list of action types the client's editor can render and round-trip faithfully. The server uses only the types that are both allowed for the builder and in this list, so a client can only narrow what the builder offers.

The draft is decided by the server, not by the model's prose. Every id is generated by the server and every reference between actions is resolved by it. Resource references (queues, assistants, other flows, and so on) are always left empty and reported with select_resource in draft_warnings; the user picks them in the editor.

The request body may not exceed 512 KiB (524288 bytes), which is enforced while the body is read; a larger body is answered with BUILDER_INPUT_TOO_LARGE (400). The per-message and total limits of the conversation are the ones reported by GET /ai_builder/status. A draft may have at most 60 actions.

Each call counts against a per-customer daily limit that is separate from the assistant builder's, from the moment it starts running. That includes a call that then fails (a provider error, a timeout, or a model answer that could not be used). A call refused because the request was invalid, the builder was unavailable, or the service was busy, is not counted.

Requires an Agent identity with the customer admin or manager permission. Availability is reported by GET /ai_builder/status.

post/flow_builder/chat

Request

  • Base URL: https://api.voipbin.net/v1.0
  • URL: https://api.voipbin.net/v1.0/flow_builder/chat
  • Auth: none declared

Request body

supported_action_typesstring[] required

The action types the client's editor can render and round-trip. The builder uses only the types that are both allowed for it and listed here.

Example request

{
  "messages": [
    {
      "role": "user",
      "content": "I run a dental clinic and want an assistant that answers the phone."
    }
  ],
  "current_draft": {
    "actions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "next_id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "talk",
        "tm_execute": "2026-01-15T09:30:00.000000Z"
      }
    ]
  },
  "supported_action_types": [
    "talk",
    "digits_receive",
    "branch",
    "hangup"
  ]
}

Response

The builder's next message and, when ready, a draft.

messagestring required

The builder's next message to show the user. Plain text.

assumptionsstring[]

Things the draft assumes that the user did not say, to be confirmed.

draft_warningsstring[]

Facts the server found about the draft. Each entry starts with a fixed key, optionally followed by : and a detail, so a client may key on the part before : . The keys are duplicate_label, unsupported_action, invalid_label_ref, invalid_option, select_resource, open_end, empty_action_ref, unreachable, next_ignored, missing_required, media_mixed, empty_draft and draft_discarded. For example select_resource: sales.queue_id says the queue_id of the action the builder named sales has to be picked in the editor.

sensitive_nodesstring[]

The id of every action in the draft that costs money or sends data outside the platform (for example sending a message or calling a webhook). The editor should make these easy to see. Decided by the server from the action type.

Example response

{
  "message": "Should callers be able to leave a message when nobody answers?",
  "draft": {
    "actions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "next_id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "talk",
        "tm_execute": "2026-01-15T09:30:00.000000Z"
      }
    ]
  },
  "assumptions": [
    "Callers speak English."
  ],
  "draft_warnings": [
    "select_resource: sales.queue_id"
  ],
  "sensitive_nodes": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

Changes