---
title: "Run one turn of the assistant builder conversation."
method: POST
path: "/ai_builder/chat"
tags: ["AI"]
---

# Run one turn of the assistant builder conversation.

`POST /ai_builder/chat`

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 assistant configuration once it has enough information. Nothing is saved: the draft only fills the AI create form, and the user reviews it and saves it through `POST /ais`.

The server keeps no conversation. The client sends the full history on every turn, so a refresh does not lose it only if the client stored it. Each message must be `user` or `assistant`, and the last one must be `user`. Strict alternation is not enforced.

The request body may not exceed 160 KiB (163840 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 are reported by `GET /ai_builder/status`.

Each call counts against a per-customer daily limit, 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.

## Request body

- AIManagerAIBuilderChatRequest
  - `messages` AIManagerAIBuilderMessage[], required — The whole conversation so far, oldest first. The assistant entries are the earlier `message` values the server returned.
    - `role` 'user' | 'assistant', required — Who wrote the message. The last message of a request must be `user`.
    - `content` string, required — The message text. At most 2000 characters (not bytes) per message, and 40000 in total across the conversation.
  - `current_draft` AIManagerAIBuilderDraft — The assistant configuration the builder proposes. It is not saved. The user reviews it and saves it through `POST /ais`.
    - `name` string, required — Proposed name of the assistant.
    - `detail` string, required — Proposed one-line description.
    - `init_prompt` string, required — Proposed instructions for the assistant.
    - `tool_names` AIManagerToolName[], required — Tools the assistant may use. In a response only `connect_call`, `stop_service`, `send_email`, `send_message`, `set_variables` and `case_create` can appear. In a request at most 6 entries are accepted.

## Response `200`

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

- AIManagerAIBuilderChatResponse
  - `message` string, required — The builder's next message to show the user. Plain text.
  - `draft` AIManagerAIBuilderDraft — The assistant configuration the builder proposes. It is not saved. The user reviews it and saves it through `POST /ais`.
    - `name` string, required — Proposed name of the assistant.
    - `detail` string, required — Proposed one-line description.
    - `init_prompt` string, required — Proposed instructions for the assistant.
    - `tool_names` AIManagerToolName[], required — Tools the assistant may use. In a response only `connect_call`, `stop_service`, `send_email`, `send_message`, `set_variables` and `case_create` can appear. In a request at most 6 entries are accepted.
  - `assumptions` string[] — Things the draft assumes that the user did not say, to be confirmed.
  - `draft_warnings` string[] — 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 `draft_discarded`, `tool_names_invalid`, `tool_removed`, `tools_section_removed`, `forbidden_tool_mentioned`, `init_prompt_truncated`, `name_truncated` and `detail_truncated`. For example `tool_removed: create_call` says a tool that is not allowed here was removed.

## Other responses

- `400` — The request is invalid (INVALID_ARGUMENT), the body is not valid JSON (INVALID_JSON_BODY), or the body exceeded the size limit (BUILDER_INPUT_TOO_LARGE).
- `401` — Authentication required (UNAUTHENTICATED).
- `403` — Insufficient permission (PERMISSION_DENIED).
- `429` — The daily limit was reached (BUILDER_DAILY_LIMIT), or the service is busy and the request was not run (BUILDER_BUSY). Only the busy case is worth retrying soon. The per-customer and per-IP request rate limits can also answer 429 with the reason RATE_LIMIT_EXCEEDED, which is worth retrying after a short wait.
- `500` — Internal error (INTERNAL).
- `503` — The builder is not available. The `reason` is one of BUILDER_UNAVAILABLE (no key is configured, or the counter is down; the same reason covers both, so a retry helps only in the second case), BUILDER_TIMEOUT (took too long), BUILDER_RESPONSE_INVALID (the model's answer or the provider failed), or SERVICE_UNAVAILABLE (the service is temporarily cut off). BUILDER_TIMEOUT, BUILDER_RESPONSE_INVALID and SERVICE_UNAVAILABLE are worth retrying.

## Changes

- **2026-10-01** `0394066c8927` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/voipbin/apis/voipbin-api/changes/ai_builder/chat/post.md)

---

[API](https://skmtc.dev/voipbin/apis/voipbin-api.md) · [All operations](https://skmtc.dev/voipbin/apis/voipbin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voipbin/apis/voipbin-api/revisions/6a2b13260ccc?raw)