# Set prompt

> Replaces the receptionist's prompt: what it is trying to achieve, who it is, how it handles the call. A prompt is only valid whole, so read the current…

`PUT /v2/api/numbers/{number}/agent/prompt`

<Note>
**Required scope:** `AGENTS_WRITE`
</Note>

## Behavior

Replaces the receptionist's prompt: what it is trying to achieve, who it is, and how it handles the call. A prompt is only valid whole, and every write re-renders what the receptionist answers with, so read the current sections with [Get configuration](/docs/agent/get-agent) and send them all back, including the ones you are not changing.

The response echoes the prompt with a `title` derived server-side from each `section` key.

## Sections

| Section | Required | Body |
|---|---|---|
| `objective` | Yes | `content` |
| `personality` | Yes | `content` |
| `behaviors` | Yes | `content` |
| `prohibited` | No | `content` |
| `required_fields` | No | `fields` |
| `objective_completion` | No | `content` |

`required_fields` is the one section that carries `fields` instead of `content`, one entry per piece of information the receptionist has to collect. Every other section carries non-blank `content` and no `fields`. Each section may appear at most once, and `content` holds up to 3000 characters.

The three required sections are the minimum the API enforces, not the prompt a business needs. A receptionist with no `prohibited` section was never told what it must not say.

## What belongs elsewhere

Facts about the business go in `knowledge` on [Update configuration](/docs/agent/update-agent), not here. Prices, opening hours, policies and FAQs change often, and the receptionist looks them up rather than reciting them from the prompt.

The greeting and the closing message are their own fields too. Allo already handles greeting, closing, language switching, contact confirmation, transfer and booking mechanics, so restating them in the prompt makes the call worse, not better.

## Errors

- `400 PROMPT_SECTIONS_REQUIRED`: `sections` was missing or empty. It replaces the whole prompt, so it has to carry every section you want to keep.
- `400 INVALID_AGENT_PROMPT_SECTION`: an unknown section key. The allowed ones are listed in the message.
- `400 DUPLICATE_AGENT_PROMPT_SECTION`: a section appears more than once.
- `400 INVALID_AGENT_PROMPT_SECTION_BODY`: a section carries the wrong body, for example `fields` on `objective`.
- `400 MISSING_AGENT_PROMPT_SECTION`: one of `objective`, `personality` or `behaviors` is missing or blank.
- `400 AGENT_PROMPT_SECTION_TOO_LONG`: a section's `content` is over 3000 characters.
- `400 AGENT_PROMPT_TOO_LONG`: the prompt rendered from all sections is over 25000 characters.
- `404 PHONE_NUMBER_NOT_FOUND`: the number is not one you have access to.
