> ## Documentation Index
> Fetch the complete documentation index at: https://help.withallo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 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.

<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](/en/v2/api-reference/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](/en/v2/api-reference/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.


## OpenAPI

````yaml PUT /v2/api/numbers/{number}/agent/prompt
openapi: 3.0.3
info:
  title: Allo API
  description: >-
    Allo API provides programmatic access to your Allo account, allowing you to
    manage webhooks, retrieve calls and contacts, and send SMS messages.


    All requests to `/v1/api/**` endpoints automatically go through quota
    checking and scope validation.
  version: 1.0.0
  contact:
    name: Allo Support
servers:
  - url: https://api.withallo.com
    description: Production server
security: []
tags:
  - name: Summary Templates
    description: >-
      Manage call summary templates that control how AI-generated call summaries
      are structured for your team.
  - name: Webhooks
    description: >-
      Manage webhook endpoints to receive real-time notifications about events
      in your Allo account. Each endpoint subscribes to one or more event topics
      and is verified with a signing secret.
  - name: Calls
    description: >-
      Retrieve and search call records with filtering and pagination. Filter
      calls by your Allo phone number.
  - name: Contacts
    description: >-
      Search and retrieve contact information with sorting and pagination.
      Includes engagement level tracking.
  - name: SMS
    description: Send SMS messages to phone numbers using your Allo numbers.
  - name: Phone Numbers
    description: Retrieve information about your Allo phone numbers.
  - name: Analytics
    description: Pre-computed call metrics, team performance, and outbound dial funnel
  - name: CRM
    description: Manage people, companies, and deals in your CRM.
  - name: Notes
    description: >-
      Internal team notes on conversations and CRM people, with @mention
      support. Notes are never visible to the contact.
  - name: Threads
    description: >-
      Team discussion threads attached to a conversation item (call, SMS, or
      conversation note). One thread per item.
  - name: AI Receptionist
    description: >-
      Read and write the AI receptionist configuration of a phone line: business
      details, voice, prompt, capabilities, business hours, transfer rules,
      scheduling calendars and knowledge sources.
paths:
  /v2/api/numbers/{number}/agent/prompt:
    put:
      tags:
        - AI Receptionist
      summary: Set the AI receptionist prompt
      description: >-
        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.
      operationId: setAgentPrompt
      parameters:
        - name: number
          in: path
          required: true
          description: Allo phone number in E.164 format
          schema:
            type: string
            example: '+14155551234'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetAgentPromptRequest'
      responses:
        '200':
          description: The prompt after the write, with server-derived titles
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentPrompt'
        '400':
          $ref: '#/components/responses/ApiValidationError'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '403':
          $ref: '#/components/responses/ApiForbidden'
        '404':
          $ref: '#/components/responses/ApiNotFound'
        '429':
          $ref: '#/components/responses/ApiRateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SetAgentPromptRequest:
      type: object
      description: >-
        Replaces the whole prompt. `objective`, `personality` and `behaviors`
        are required; each section may appear once; a `content` section holds at
        most 3000 characters.
      required:
        - sections
      properties:
        sections:
          type: array
          items:
            type: object
            required:
              - section
            properties:
              section:
                type: string
                enum:
                  - objective
                  - personality
                  - behaviors
                  - prohibited
                  - required_fields
                  - objective_completion
              content:
                type: string
                maxLength: 3000
                description: Required for every section except `required_fields`.
              fields:
                type: array
                description: >-
                  Required for `required_fields`, and rejected on every other
                  section.
                items:
                  $ref: '#/components/schemas/AgentPromptField'
    AgentPrompt:
      type: object
      description: >-
        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.
      properties:
        sections:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/AgentPromptSection'
        custom_prompt:
          type: string
          nullable: true
    AgentPromptField:
      type: object
      description: >-
        One piece of information the receptionist has to collect during the
        call.
      required:
        - label
        - question
        - complete_when
      properties:
        label:
          type: string
          example: Email
        question:
          type: string
          example: What is the best email to send the quote to?
        complete_when:
          type: string
          description: How the receptionist knows it has the answer.
          example: a valid email address is given
    AgentPromptSection:
      type: object
      description: >-
        One section of the prompt. `required_fields` carries `fields` and no
        `content`; every other section carries `content` and no `fields`.
      properties:
        section:
          type: string
          enum:
            - objective
            - personality
            - behaviors
            - prohibited
            - required_fields
            - objective_completion
        title:
          type: string
          description: Human-readable title, derived server-side from `section`.
          example: Objective
        content:
          type: string
          nullable: true
          example: Book a visit with the caller.
        fields:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/AgentPromptField'
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            request_id:
              type: string
            retry_after_seconds:
              type: integer
              nullable: true
  responses:
    ApiValidationError:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiUnauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiForbidden:
      description: API key lacks the required scope or access to the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiRateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````