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

# Définir le 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>
  **Scope requis :** `AGENTS_WRITE`
</Note>

## Comportement

Remplace le prompt du réceptionniste : ce qu'il cherche à obtenir, qui il est et comment il mène l'appel. Un prompt n'est valide qu'entier, et chaque écriture régénère ce avec quoi le réceptionniste répond. Lisez donc les sections actuelles avec [Lire la configuration](/fr/v2/api-reference/agent/get-agent) et renvoyez-les toutes, y compris celles que vous ne modifiez pas.

La réponse renvoie le prompt avec un `title` dérivé côté serveur de chaque clé `section`.

## Sections

| Section                | Obligatoire | Corps     |
| ---------------------- | ----------- | --------- |
| `objective`            | Oui         | `content` |
| `personality`          | Oui         | `content` |
| `behaviors`            | Oui         | `content` |
| `prohibited`           | Non         | `content` |
| `required_fields`      | Non         | `fields`  |
| `objective_completion` | Non         | `content` |

`required_fields` est la seule section qui porte `fields` au lieu de `content`, avec une entrée par information que le réceptionniste doit recueillir. Toutes les autres sections portent un `content` non vide et pas de `fields`. Chaque section apparaît au maximum une fois, et `content` accepte jusqu'à 3000 caractères.

Les trois sections obligatoires sont le minimum imposé par l'API, pas le prompt dont une activité a besoin. Un réceptionniste sans section `prohibited` n'a jamais appris ce qu'il ne doit pas dire.

## Ce qui se place ailleurs

Les informations factuelles sur l'activité vont dans `knowledge` sur [Modifier la configuration](/fr/v2/api-reference/agent/update-agent), pas ici. Tarifs, horaires, règles et questions fréquentes changent souvent, et le réceptionniste va les y chercher au lieu de les réciter depuis le prompt.

Le message d'accueil et le message de fin ont eux aussi leurs propres champs. Allo gère déjà l'accueil, la clôture, le changement de langue, la confirmation des coordonnées, le transfert et la mécanique de réservation : les répéter dans le prompt dégrade l'appel au lieu de l'améliorer.

## Erreurs

* `400 PROMPT_SECTIONS_REQUIRED` : `sections` est absent ou vide. Il remplace tout le prompt et doit donc porter chaque section à conserver.
* `400 INVALID_AGENT_PROMPT_SECTION` : une clé de section inconnue. Les valeurs acceptées sont listées dans le message.
* `400 DUPLICATE_AGENT_PROMPT_SECTION` : une section apparaît plusieurs fois.
* `400 INVALID_AGENT_PROMPT_SECTION_BODY` : une section porte le mauvais corps, par exemple `fields` sur `objective`.
* `400 MISSING_AGENT_PROMPT_SECTION` : `objective`, `personality` ou `behaviors` est absent ou vide.
* `400 AGENT_PROMPT_SECTION_TOO_LONG` : le `content` d'une section dépasse 3000 caractères.
* `400 AGENT_PROMPT_TOO_LONG` : le prompt généré depuis toutes les sections dépasse 25000 caractères.
* `404 PHONE_NUMBER_NOT_FOUND` : ce numéro n'est pas un numéro auquel vous avez accès.


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

````