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

`PATCH /v2/api/numbers/{number}/agent`

<Note>
**Required scope:** `AGENTS_WRITE`
</Note>

## Behavior

Updates any part of the receptionist's configuration except the prompt and the on/off status. Returns the whole configuration after the write, in the same shape as [Get configuration](/docs/agent/get-agent).

Two merge rules apply:

- **Single values are merged.** `name`, the business details, `language`, `voice_id`, `greeting_message`, `closing_message`, `tone_of_voice`, `answer_type` and `knowledge.text` keep their current value when you omit them.
- **Collections are replaced.** `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.

To add one transfer rule, read the existing rules first and send them back with the new one. To keep a capability on, include it in every `capabilities` map you send.

A field this endpoint does not declare is rejected with `400 UNKNOWN_FIELD`, including read-only ones such as `custom_prompt`, `prompt_metadata` and `status`. Nothing is dropped in silence.

## Transfer rules

`description` is the field that decides whether a transfer works. The receptionist matches what the caller says they want against this text, so write it as the caller's reason ("billing or invoice questions", "wants to book a repair"), not as an instruction to the receptionist.

Each rule needs the target its `type` implies:

| Type | Required field | Goes to |
|---|---|---|
| `EXTERNAL_NUMBER` | `target_number` | Any phone number, in E.164 format |
| `MEMBER` | `target_member_id` | A teammate, by their id from `GET /v2/api/users` |
| `INBOX` | `target_line_number` | Another of your Allo numbers |

Point the target at somewhere other than the line you are configuring. A rule that sends the caller back to the same line hands them to the receptionist that just transferred them, and the call loops. The API accepts such a rule, so this one is on you to avoid.

Rules are recreated on every write, so an error names the entry that failed by its index, for example `transfer_rules[1].description`.

## Business hours

`schedule` is required whenever you send `business_hours`. Times are seconds since midnight, so 9am to 5pm is `32400` to `61200`, and a day left out of the list is closed.

## Scheduling calendars

`scheduling.calendars` is a map keyed by a calendar `id` from [List calendars](/docs/agent/list-calendars). A calendar the receptionist does not have yet is linked to it, one mapped to `[]` stays linked with no event type selected, and one left out of the map loses access.

Event types come from [Get a calendar](/docs/agent/get-calendar). Send `id`, `slug`, `title` and `length_in_minutes` back as they were read, and add your own `description` to say when the receptionist should book that one rather than another.

Connecting a calendar to the workspace is an OAuth flow, done in the Allo app. This endpoint chooses among the connections that already exist.

## Knowledge text

`knowledge.text` is deprecated. Add websites with [Add website knowledge](/docs/agent/add-website-knowledge) instead.

It still works. Allo stores it as a text source named "Business knowledge" in your team's knowledge library, used by this line. Sending a different text edits that same source, and an empty string turns it off for this line.

## Field limits

| Field | Limit |
|---|---|
| `name`, `business_name`, `business_email`, `business_website`, `business_industry` | 64 characters |
| `business_address` | 255 characters |
| `greeting_message`, `closing_message` | 1000 characters |
| `transfer_rules[].description` | 255 characters |
| `transfer_rules[].transfer_message` | 1000 characters |
| `knowledge.text` (deprecated) | 25000 characters |

## Errors

- `400 UNKNOWN_FIELD`: a field this endpoint does not accept, named in `param`.
- `400 INVALID_REQUEST_BODY`: a declared field failed validation. The failing field is in `errors[]`.
- `400 MISSING_FIELD`: a required part of a collection is missing, named in `param`.
- `400 INVALID_AGENT_LANGUAGE` / `400 INVALID_AGENT_CAPABILITY`: an unknown value. The allowed ones are listed in the message.
- `400 INVALID_TIMEZONE`: `business_hours.timezone` is not an IANA identifier.
- `400 INVALID_PHONE_NUMBER`: `business_phone` is not a usable number.
- `400 AGENT_TRANSFER_RULE_TARGET_REQUIRED`: a rule is missing the target its type requires.
- `403 AGENT_TRANSFER_RULE_MEMBER_NO_LINE_ACCESS`: the target teammate has no access to this line.
- `404 AGENT_VOICE_NOT_FOUND`: no voice with that `voice_id`. List them with [List voices](/docs/agent/list-voices).
- `404 AGENT_CALENDAR_NOT_FOUND`: a calendar id in the map is not one you can see.
- `404 PHONE_NUMBER_NOT_FOUND`: the number is not one you have access to.
