--- title: "Update AI receptionist configuration" method: PATCH path: "/v2/api/numbers/{number}/agent" tags: ["AI Receptionist"] --- # Update AI receptionist configuration `PATCH /v2/api/numbers/{number}/agent` ## Request - Base URL: `https://api.withallo.com` - URL: `https://api.withallo.com/v2/api/numbers/{number}/agent` - Auth: API key in header `Authorization` 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`. ## Path parameters - `number` string, required ## Request body - UpdateAgentRequest: 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. - `name` string - `business_name` string - `business_address` string - `business_phone` string: E.164 format. - `business_email` string - `business_website` string - `business_industry` string - `language` 'fr' | 'fr-CA' | 'en-US' | 'en-GB' | 'es' | 'de' | 'hr' - `voice_id` string: An `id` from `GET /v2/api/voices`, listed under the receptionist's language. - `greeting_message` string - `closing_message` string - `tone_of_voice` 'FRIENDLY' | 'PROFESSIONAL' | 'NEUTRAL' | 'ENTHUSIASTIC' - `answer_type` 'CONCISE' | 'STANDARD' | 'DETAILED' - `capabilities` object: 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. - `business_hours` object: Replaces the whole week. `schedule` is required when this key is sent. - `timezone` string: IANA timezone identifier. - `schedule` AgentDaySchedule[], required - `day` 'MO' | 'TU' | 'WE' | 'TH' | 'FR' | 'SA' | 'SU', required - `schedule` AgentTimeInterval[], required: The open periods of that day. An empty array closes the day. - `start_time` integer, required - `end_time` integer, required - `transfer_rules` AgentTransferRule[]: Replaces the whole rule set. Send `[]` to remove every rule. - `description` string: 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. - `type` 'EXTERNAL_NUMBER' | 'MEMBER' | 'INBOX': `EXTERNAL_NUMBER` transfers to any phone number, `MEMBER` to a teammate, `INBOX` to another Allo line. - `transfer_message` string, nullable: What the receptionist says before transferring. - `target_number` string, nullable: Required for `EXTERNAL_NUMBER`. E.164 format. - `target_member_id` string, nullable: Required for `MEMBER`. A user id from `GET /v2/api/users`. - `target_line_number` string, nullable: Required for `INBOX`. Another of your Allo numbers, in E.164 format. - `scheduling` object - `calendars` object: 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. - `knowledge` object: Only the free-text knowledge is writable here. Websites and files have their own endpoints. - `text` string: Deprecated: add websites instead. Stored as the line's "Business knowledge" text source in the team's knowledge library; a different text edits that source in place, an empty string turns it off for this line. ## Response `200` The configuration after the write - object - `data` AgentSnapshot: The whole configuration of one line's AI receptionist. - `agent` AgentConfig: 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`. - `id` string, nullable - `status` 'ACTIVE' | 'FORWARDING': `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` string, nullable: The name the receptionist gives itself on a call. - `is_default` boolean: True while the line still runs Allo's default receptionist, with no prompt, greeting, closing or knowledge of its own. - `business_name` string, nullable - `business_address` string, nullable - `business_phone` string, nullable: The business's own phone number, in E.164 format. - `business_email` string, nullable - `business_website` string, nullable - `business_industry` string, nullable - `language` 'fr' | 'fr-CA' | 'en-US' | 'en-GB' | 'es' | 'de' | 'hr', nullable: The language the receptionist speaks. Pick a `voice_id` listed under the same language. - `voice_id` string, nullable: Identifier of a voice from `GET /v2/api/voices`. - `greeting_message` string, nullable: What the receptionist says when it picks up. - `closing_message` string, nullable: What the receptionist says before hanging up. - `tone_of_voice` 'FRIENDLY' | 'PROFESSIONAL' | 'NEUTRAL' | 'ENTHUSIASTIC' - `answer_type` 'CONCISE' | 'STANDARD' | 'DETAILED': How long the receptionist's answers run. - `created_at` string, date-time, nullable - `updated_at` string, date-time, nullable - `prompt` 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 - `capabilities` AgentCapabilities: What the receptionist is allowed to do on a call. All three are always reported. - `SCHEDULING` boolean: Book appointments on the calendars in `scheduling.calendars`. - `CALL_TRANSFER` boolean: Transfer the call using the rules in `transfer_rules`. - `WARM_TRANSFER` boolean: Announce the caller to the person taking the transfer before connecting them. - `business_hours` AgentBusinessHours: When the business is open. A day left out of `schedule` is closed. - `timezone` string, nullable: IANA timezone identifier. - `schedule` AgentDaySchedule[] - `day` 'MO' | 'TU' | 'WE' | 'TH' | 'FR' | 'SA' | 'SU', required - `schedule` AgentTimeInterval[], required: The open periods of that day. An empty array closes the day. - `start_time` integer, required - `end_time` integer, required - `transfer_rules` AgentTransferRule[] - `description` string: 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. - `type` 'EXTERNAL_NUMBER' | 'MEMBER' | 'INBOX': `EXTERNAL_NUMBER` transfers to any phone number, `MEMBER` to a teammate, `INBOX` to another Allo line. - `transfer_message` string, nullable: What the receptionist says before transferring. - `target_number` string, nullable: Required for `EXTERNAL_NUMBER`. E.164 format. - `target_member_id` string, nullable: Required for `MEMBER`. A user id from `GET /v2/api/users`. - `target_line_number` string, nullable: Required for `INBOX`. Another of your Allo numbers, in E.164 format. - `scheduling` AgentScheduling - `calendars` AgentCalendar[]: 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`. - `calendar_connection_id` string - `name` string, nullable - `provider` 'GOOGLE_CALENDAR' | 'CAL_COM' | 'CALENDLY' | 'OUTLOOK' - `status` 'ACTIVE' | 'DISCONNECTED' - `is_team_default` boolean - `owner` CalendarOwner: The teammate who connected the calendar. - `user_id` string - `user_name` string, nullable - `email` string, nullable - `is_current_user` boolean - `event_types` SchedulingEventType[] - `id` string, required: The provider's own event-type identifier. - `slug` string, required - `title` string, required - `length_in_minutes` integer, nullable - `description` string, nullable: 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. - `required_questions` SchedulingQuestion[], nullable - `id` string - `label` string - `knowledge` AgentKnowledge: What the receptionist knows about the business: facts, prices, policies, hours. - `text` string, nullable: Deprecated. Free-text knowledge, up to 25000 characters, stored as the line's "Business knowledge" text source. - `websites` AgentWebsiteKnowledge[] - `id` string - `url` string - `status` 'ACTIVE' | 'DISABLED': `ACTIVE` when this line's receptionist answers from the website, `DISABLED` when this line does not use it. - `created_at` string, date-time, nullable - `updated_at` string, date-time, nullable - `files` AgentFileKnowledge[] - `id` string - `file_name` string - `status` 'ACTIVE' | 'DISABLED' - `created_at` string, date-time, nullable - `updated_at` string, date-time, 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/patch.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)