> ## 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. # Modifier la configuration > Updates any part of the configuration except the prompt and the on/off status. Single values are merged, collections are replaced. This does not put the receptionist on the line: that is `PUT /v2/api/numbers/{number}/agent/status`. **Scope requis :** `AGENTS_WRITE` ## Comportement Modifie toute partie de la configuration du réceptionniste, sauf le prompt et l'activation. Renvoie la configuration complète après l'écriture, dans la même forme que [Lire la configuration](/fr/v2/api-reference/agent/get-agent). Deux règles de fusion s'appliquent : * **Les valeurs simples sont fusionnées.** `name`, les informations sur l'activité, `language`, `voice_id`, `greeting_message`, `closing_message`, `tone_of_voice`, `answer_type` et `knowledge.text` gardent leur valeur actuelle si vous les omettez. * **Les collections sont remplacées.** `capabilities`, `business_hours`, `transfer_rules` et `scheduling.calendars` sont des ensembles complets. Envoyez-en un et il remplace ce qui était configuré, omettez-le et il reste intact. Pour ajouter une seule règle de transfert, lisez d'abord les règles existantes et renvoyez-les avec la nouvelle. Pour garder une capacité activée, incluez-la dans chaque map `capabilities` que vous envoyez. Un champ que cet endpoint ne déclare pas est refusé avec `400 UNKNOWN_FIELD`, y compris les champs en lecture seule comme `custom_prompt`, `prompt_metadata` et `status`. Rien n'est ignoré en silence. ## Règles de transfert `description` est le champ qui décide si un transfert fonctionne. Le réceptionniste compare ce que dit l'appelant à ce texte : écrivez-le comme le motif de l'appelant (« questions de facturation », « veut réserver une intervention »), pas comme une instruction adressée au réceptionniste. Chaque règle a besoin de la cible qu'implique son `type` : | Type | Champ requis | Destination | | ----------------- | -------------------- | ------------------------------------------------------------- | | `EXTERNAL_NUMBER` | `target_number` | N'importe quel numéro, au format E.164 | | `MEMBER` | `target_member_id` | Un membre de l'équipe, par son id issu de `GET /v2/api/users` | | `INBOX` | `target_line_number` | Une autre de vos lignes Allo | Visez une cible autre que la ligne que vous configurez. Une règle qui renvoie l'appelant vers la même ligne le rend au réceptionniste qui vient de le transférer, et l'appel boucle. L'API accepte une telle règle : c'est à vous de l'éviter. Les règles sont recréées à chaque écriture : une erreur désigne l'entrée fautive par son index, par exemple `transfer_rules[1].description`. ## Horaires d'ouverture `schedule` est obligatoire dès que vous envoyez `business_hours`. Les heures sont exprimées en secondes depuis minuit : 9h à 17h s'écrit `32400` à `61200`, et un jour absent de la liste est fermé. ## Agendas de réservation `scheduling.calendars` est une map dont les clés sont des `id` d'agenda issus de [Lister les agendas](/fr/v2/api-reference/agent/list-calendars). Un agenda que le réceptionniste n'a pas encore lui est rattaché, un agenda associé à `[]` reste rattaché sans type d'événement sélectionné, et un agenda absent de la map perd l'accès. Les types d'événement viennent de [Lire un agenda](/fr/v2/api-reference/agent/get-calendar). Renvoyez `id`, `slug`, `title` et `length_in_minutes` tels quels, et ajoutez votre propre `description` pour indiquer quand le réceptionniste doit réserver celui-là plutôt qu'un autre. Connecter un agenda à l'espace de travail est un flux OAuth, réalisé dans l'app Allo. Cet endpoint choisit parmi les connexions qui existent déjà. ## Limites des champs | Champ | Limite | | ---------------------------------------------------------------------------------- | ---------------- | | `name`, `business_name`, `business_email`, `business_website`, `business_industry` | 64 caractères | | `business_address` | 255 caractères | | `greeting_message`, `closing_message` | 1000 caractères | | `transfer_rules[].description` | 255 caractères | | `transfer_rules[].transfer_message` | 1000 caractères | | `knowledge.text` | 25000 caractères | ## Erreurs * `400 UNKNOWN_FIELD` : un champ que cet endpoint n'accepte pas, nommé dans `param`. * `400 INVALID_REQUEST_BODY` : un champ déclaré n'a pas passé la validation. Le champ fautif est dans `errors[]`. * `400 MISSING_FIELD` : une partie obligatoire d'une collection manque, nommée dans `param`. * `400 INVALID_AGENT_LANGUAGE` / `400 INVALID_AGENT_CAPABILITY` : une valeur inconnue. Les valeurs acceptées sont listées dans le message. * `400 INVALID_TIMEZONE` : `business_hours.timezone` n'est pas un identifiant IANA. * `400 INVALID_PHONE_NUMBER` : `business_phone` n'est pas un numéro exploitable. * `400 AGENT_TRANSFER_RULE_TARGET_REQUIRED` : une règle n'a pas la cible qu'exige son type. * `403 AGENT_TRANSFER_RULE_MEMBER_NO_LINE_ACCESS` : le membre visé n'a pas accès à cette ligne. * `404 AGENT_VOICE_NOT_FOUND` : aucune voix ne porte ce `voice_id`. Listez-les avec [Lister les voix](/fr/v2/api-reference/agent/list-voices). * `404 AGENT_CALENDAR_NOT_FOUND` : un id d'agenda de la map n'est pas visible pour vous. * `404 PHONE_NUMBER_NOT_FOUND` : ce numéro n'est pas un numéro auquel vous avez accès. ## OpenAPI ````yaml PATCH /v2/api/numbers/{number}/agent 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: patch: tags: - AI Receptionist summary: Update AI receptionist configuration description: >- Updates any part of the configuration except the prompt and the on/off status. Single values are merged, collections are replaced. This does not put the receptionist on the line: that is `PUT /v2/api/numbers/{number}/agent/status`. operationId: updateAgent 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/UpdateAgentRequest' responses: '200': description: The configuration after the write content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AgentSnapshot' '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: UpdateAgentRequest: type: object description: >- Two merge rules apply. Single values are merged: omit one and it keeps its current value. The collections `capabilities`, `business_hours`, `transfer_rules` and `scheduling.calendars` are complete sets: send one and it replaces what was configured, omit it and it is left alone. An undeclared field is rejected with `400 UNKNOWN_FIELD` rather than ignored. properties: name: type: string maxLength: 64 example: Maya business_name: type: string maxLength: 64 example: Acme Plumbing business_address: type: string maxLength: 255 business_phone: type: string maxLength: 64 description: E.164 format. example: '+14155551234' business_email: type: string maxLength: 64 business_website: type: string maxLength: 64 business_industry: type: string maxLength: 64 language: type: string enum: - fr - fr-CA - en-US - en-GB - es - de - hr example: en-US voice_id: type: string description: >- An `id` from `GET /v2/api/voices`, listed under the receptionist's language. example: maya greeting_message: type: string maxLength: 1000 closing_message: type: string maxLength: 1000 tone_of_voice: type: string enum: - FRIENDLY - PROFESSIONAL - NEUTRAL - ENTHUSIASTIC answer_type: type: string enum: - CONCISE - STANDARD - DETAILED capabilities: type: object description: >- The complete set of toggles. A capability left out of the map is turned off, so read the current ones first and send them all back. additionalProperties: type: boolean example: SCHEDULING: true CALL_TRANSFER: true WARM_TRANSFER: false business_hours: type: object description: >- Replaces the whole week. `schedule` is required when this key is sent. required: - schedule properties: timezone: type: string description: IANA timezone identifier. example: America/New_York schedule: type: array items: $ref: '#/components/schemas/AgentDaySchedule' transfer_rules: type: array description: Replaces the whole rule set. Send `[]` to remove every rule. items: $ref: '#/components/schemas/AgentTransferRule' scheduling: type: object properties: calendars: type: object description: >- The complete set of calendars the receptionist may book on, keyed by an `id` from `GET /v2/api/calendars`. A calendar it does not have yet is linked to it, one mapped to `[]` stays linked with no event type selected, and one left out loses access. additionalProperties: type: array items: $ref: '#/components/schemas/SchedulingEventType' knowledge: type: object description: >- Only the free-text knowledge is writable here. Websites and files have their own endpoints. properties: text: type: string maxLength: 25000 example: We serve the Austin metro area and open at 7am. AgentSnapshot: type: object description: The whole configuration of one line's AI receptionist. properties: agent: $ref: '#/components/schemas/AgentConfig' prompt: $ref: '#/components/schemas/AgentPrompt' capabilities: $ref: '#/components/schemas/AgentCapabilities' business_hours: $ref: '#/components/schemas/AgentBusinessHours' transfer_rules: type: array items: $ref: '#/components/schemas/AgentTransferRule' scheduling: $ref: '#/components/schemas/AgentScheduling' knowledge: $ref: '#/components/schemas/AgentKnowledge' AgentDaySchedule: type: object required: - day - schedule properties: day: type: string enum: - MO - TU - WE - TH - FR - SA - SU schedule: type: array description: The open periods of that day. An empty array closes the day. items: $ref: '#/components/schemas/AgentTimeInterval' AgentTransferRule: type: object description: >- One reason the receptionist hands the call over, and where it hands it to. properties: description: type: string description: >- The caller's reason, in the caller's words. This is what the receptionist matches what it hears against, so phrase it as a reason ('billing or invoice questions'), not as an instruction. example: Billing or invoice questions type: type: string enum: - EXTERNAL_NUMBER - MEMBER - INBOX description: >- `EXTERNAL_NUMBER` transfers to any phone number, `MEMBER` to a teammate, `INBOX` to another Allo line. transfer_message: type: string nullable: true description: What the receptionist says before transferring. example: Let me put you through to billing. target_number: type: string nullable: true description: Required for `EXTERNAL_NUMBER`. E.164 format. example: '+14155551234' target_member_id: type: string nullable: true description: Required for `MEMBER`. A user id from `GET /v2/api/users`. target_line_number: type: string nullable: true description: Required for `INBOX`. Another of your Allo numbers, in E.164 format. SchedulingEventType: type: object description: >- An event type the receptionist may book. Send `id`, `slug`, `title` and `length_in_minutes` back as `GET /v2/api/calendars/{id}` reported them. required: - id - slug - title properties: id: type: string description: The provider's own event-type identifier. example: '42' slug: type: string example: intro-call title: type: string example: Intro call length_in_minutes: type: integer nullable: true example: 30 description: type: string nullable: true description: >- Your own note on when the receptionist should book this one rather than another. This is what it routes on when several event types are bookable, so write it as the caller's reason. example: Book this one when the caller wants a quote. required_questions: type: array nullable: true items: $ref: '#/components/schemas/SchedulingQuestion' AgentConfig: type: object description: >- The AI receptionist's own settings. Everything here except `id`, `status`, `is_default`, `created_at` and `updated_at` is writable with `PATCH /v2/api/numbers/{number}/agent`. properties: id: type: string nullable: true example: agt-abc123 status: type: string enum: - ACTIVE - FORWARDING description: >- `ACTIVE`: the receptionist answers incoming calls. `FORWARDING`: it does not, and calls go to your business phone. Read-only here, change it with `PUT /v2/api/numbers/{number}/agent/status`. name: type: string nullable: true description: The name the receptionist gives itself on a call. example: Maya is_default: type: boolean description: >- True while the line still runs Allo's default receptionist, with no prompt, greeting, closing or knowledge of its own. business_name: type: string nullable: true example: Acme Plumbing business_address: type: string nullable: true example: 12 Main Street, Austin TX business_phone: type: string nullable: true description: The business's own phone number, in E.164 format. example: '+14155551234' business_email: type: string nullable: true example: hello@acme.test business_website: type: string nullable: true example: https://acme.test business_industry: type: string nullable: true example: Plumbing language: type: string nullable: true enum: - fr - fr-CA - en-US - en-GB - es - de - hr description: >- The language the receptionist speaks. Pick a `voice_id` listed under the same language. example: en-US voice_id: type: string nullable: true description: Identifier of a voice from `GET /v2/api/voices`. example: maya greeting_message: type: string nullable: true description: What the receptionist says when it picks up. example: Thanks for calling Acme Plumbing, how can I help? closing_message: type: string nullable: true description: What the receptionist says before hanging up. example: Thanks for calling, have a good day. tone_of_voice: type: string enum: - FRIENDLY - PROFESSIONAL - NEUTRAL - ENTHUSIASTIC answer_type: type: string enum: - CONCISE - STANDARD - DETAILED description: How long the receptionist's answers run. created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true 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 AgentCapabilities: type: object description: >- What the receptionist is allowed to do on a call. All three are always reported. properties: SCHEDULING: type: boolean description: Book appointments on the calendars in `scheduling.calendars`. CALL_TRANSFER: type: boolean description: Transfer the call using the rules in `transfer_rules`. WARM_TRANSFER: type: boolean description: >- Announce the caller to the person taking the transfer before connecting them. AgentBusinessHours: type: object description: When the business is open. A day left out of `schedule` is closed. properties: timezone: type: string nullable: true description: IANA timezone identifier. example: America/New_York schedule: type: array items: $ref: '#/components/schemas/AgentDaySchedule' AgentScheduling: type: object properties: calendars: type: array description: >- The calendars this receptionist may book on. Empty when it has none, which is not the same as the workspace having none: list those with `GET /v2/api/calendars`. items: $ref: '#/components/schemas/AgentCalendar' AgentKnowledge: type: object description: >- What the receptionist knows about the business: facts, prices, policies, hours. properties: text: type: string nullable: true description: Free-text knowledge, up to 25000 characters. websites: type: array items: $ref: '#/components/schemas/AgentWebsiteKnowledge' files: type: array items: $ref: '#/components/schemas/AgentFileKnowledge' 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 AgentTimeInterval: type: object description: >- One open period of a day, in seconds since midnight (0 to 86399). 9am to 5pm is 32400 to 61200. required: - start_time - end_time properties: start_time: type: integer minimum: 0 maximum: 86399 example: 32400 end_time: type: integer minimum: 0 maximum: 86399 example: 61200 SchedulingQuestion: type: object description: >- A question the calendar provider rejects a booking without, so the receptionist asks it during the call. Read-only: it is snapshotted when the event type is selected. properties: id: type: string example: notes label: type: string example: Anything we should know before the visit? 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' AgentCalendar: type: object description: >- A calendar this receptionist can book on, with the event types selected for it. properties: calendar_connection_id: type: string example: exc-abc123 name: type: string nullable: true example: Acme bookings provider: type: string enum: - GOOGLE_CALENDAR - CAL_COM - CALENDLY - OUTLOOK status: type: string enum: - ACTIVE - DISCONNECTED is_team_default: type: boolean owner: $ref: '#/components/schemas/CalendarOwner' nullable: true event_types: type: array items: $ref: '#/components/schemas/SchedulingEventType' AgentWebsiteKnowledge: type: object description: >- A page Allo scraped and summarized for the receptionist to answer from. The scraped text itself is not reported: it is what the receptionist reads, not something you configure. properties: id: type: string example: wkb-abc123 url: type: string example: https://acme.test/pricing status: type: string enum: - ACTIVE - DISABLED description: >- `DISABLED` keeps the entry and its scraped text, and stops the receptionist using it. created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true AgentFileKnowledge: type: object description: >- A document uploaded in the Allo app for the receptionist to answer from. Uploading is done in the app; this API lists and deletes. properties: id: type: string example: fkb-abc123 file_name: type: string example: pricing.pdf status: type: string enum: - ACTIVE - DISABLED created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time 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 CalendarOwner: type: object description: The teammate who connected the calendar. properties: user_id: type: string user_name: type: string nullable: true email: type: string nullable: true is_current_user: type: boolean 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 ````