---
title: "Set the AI receptionist prompt"
method: PUT
path: "/v2/api/numbers/{number}/agent/prompt"
tags: ["AI Receptionist"]
---

# Set the AI receptionist prompt

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

## Request

- Base URL: `https://api.withallo.com`
- URL: `https://api.withallo.com/v2/api/numbers/{number}/agent/prompt`
- Auth: API key in header `Authorization`

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 sections with `GET /v2/api/numbers/{number}/agent` and send them all back, including the ones you are not changing. Facts about the business belong in `knowledge`, not here.

## Path parameters

- `number` string, required

## Request body

- SetAgentPromptRequest: Replaces the whole prompt. `objective`, `personality` and `behaviors` are required; each section may appear once; a `content` section holds at most 3000 characters.
  - `sections` object[], required
    - `section` 'objective' | 'personality' | 'behaviors' | 'prohibited' | 'required_fields' | 'objective_completion', required
    - `content` string: Required for every section except `required_fields`.
    - `fields` AgentPromptField[]: Required for `required_fields`, and rejected on every other section.
      - `label` string, required
      - `question` string, required
      - `complete_when` string, required: How the receptionist knows it has the answer.

## Response `200`

The prompt after the write, with server-derived titles

- object
  - `data` AgentPrompt: The receptionist's prompt. Exactly one of the two keys is present: `sections` for a prompt written in the section format, `custom_prompt` for an older line whose prompt was written as freeform text. `custom_prompt` is the render of the sections, so it is never reported alongside them.
    - `sections` AgentPromptSection[], nullable
      - `section` 'objective' | 'personality' | 'behaviors' | 'prohibited' | 'required_fields' | 'objective_completion'
      - `title` string: Human-readable title, derived server-side from `section`.
      - `content` string, nullable
      - `fields` AgentPromptField[], nullable
        - `label` string, required
        - `question` string, required
        - `complete_when` string, required: How the receptionist knows it has the answer.
    - `custom_prompt` string, nullable

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: API key lacks the required scope or access to the resource
- `404`: Resource not found
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `46c77103dd14`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withallo/apis/allo-api/changes/v2/api/numbers/:number/agent/prompt/put.md)

---

[API](https://skmtc.dev/withallo/apis/allo-api.md) - [All operations](https://skmtc.dev/withallo/apis/allo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withallo/apis/allo-api/revisions/46c77103dd14?raw)