Allo

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

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.

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:

TypeRequired fieldGoes to
EXTERNAL_NUMBERtarget_numberAny phone number, in E.164 format
MEMBERtarget_member_idA teammate, by their id from GET /v2/api/users
INBOXtarget_line_numberAnother 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. 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. 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 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

FieldLimit
name, business_name, business_email, business_website, business_industry64 characters
business_address255 characters
greeting_message, closing_message1000 characters
transfer_rules[].description255 characters
transfer_rules[].transfer_message1000 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.
  • 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.

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

numberstringrequired

Allo phone number in E.164 format

Body

namestring
business_namestring
business_addressstring
business_phonestring

E.164 format.

business_emailstring
business_websitestring
business_industrystring
languageenum<string>

frfr-CAen-USen-GBesdehr

voice_idstring

An id from GET /v2/api/voices, listed under the receptionist's language.

greeting_messagestring
closing_messagestring
tone_of_voiceenum<string>

FRIENDLYPROFESSIONALNEUTRALENTHUSIASTIC

answer_typeenum<string>

CONCISESTANDARDDETAILED

capabilitiesobject

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_hoursobject

Replaces the whole week. schedule is required when this key is sent.

2 fields
timezonestring

IANA timezone identifier.

scheduleobject[]required
2 fields
dayenum<string>required

MOTUWETHFRSASU

scheduleobject[]required

The open periods of that day. An empty array closes the day.

2 fields
start_timeintegerrequired
end_timeintegerrequired
transfer_rulesobject[]

Replaces the whole rule set. Send [] to remove every rule.

6 fields
descriptionstring

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.

typeenum<string>

EXTERNAL_NUMBER transfers to any phone number, MEMBER to a teammate, INBOX to another Allo line.

EXTERNAL_NUMBERMEMBERINBOX

transfer_messagestring | null

What the receptionist says before transferring.

target_numberstring | null

Required for EXTERNAL_NUMBER. E.164 format.

target_member_idstring | null

Required for MEMBER. A user id from GET /v2/api/users.

target_line_numberstring | null

Required for INBOX. Another of your Allo numbers, in E.164 format.

schedulingobject
1 fields
calendarsobject

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.

knowledgeobject

Only the free-text knowledge is writable here. Websites and files have their own endpoints.

1 fields
textstring

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.

Responses

200The configuration after the write
dataobject

The whole configuration of one line's AI receptionist.

7 fields
agentobject

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.

18 fields
idstring | null
statusenum<string>

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.

ACTIVEFORWARDING

namestring | null

The name the receptionist gives itself on a call.

is_defaultboolean

True while the line still runs Allo's default receptionist, with no prompt, greeting, closing or knowledge of its own.

business_namestring | null
business_addressstring | null
business_phonestring | null

The business's own phone number, in E.164 format.

business_emailstring | null
business_websitestring | null
business_industrystring | null
languageenum<string>

The language the receptionist speaks. Pick a voice_id listed under the same language.

frfr-CAen-USen-GBesdehr

voice_idstring | null

Identifier of a voice from GET /v2/api/voices.

greeting_messagestring | null

What the receptionist says when it picks up.

closing_messagestring | null

What the receptionist says before hanging up.

tone_of_voiceenum<string>

FRIENDLYPROFESSIONALNEUTRALENTHUSIASTIC

answer_typeenum<string>

How long the receptionist's answers run.

CONCISESTANDARDDETAILED

created_atstring<date-time> | null
updated_atstring<date-time> | null
promptobject

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.

2 fields
sectionsobject[]
4 fields
sectionenum<string>

objectivepersonalitybehaviorsprohibitedrequired_fieldsobjective_completion

titlestring

Human-readable title, derived server-side from section.

contentstring | null
fieldsobject[]
custom_promptstring | null
capabilitiesobject

What the receptionist is allowed to do on a call. All three are always reported.

3 fields
SCHEDULINGboolean

Book appointments on the calendars in scheduling.calendars.

CALL_TRANSFERboolean

Transfer the call using the rules in transfer_rules.

WARM_TRANSFERboolean

Announce the caller to the person taking the transfer before connecting them.

business_hoursobject

When the business is open. A day left out of schedule is closed.

2 fields
timezonestring | null

IANA timezone identifier.

scheduleobject[]
2 fields
dayenum<string>required

MOTUWETHFRSASU

scheduleobject[]required

The open periods of that day. An empty array closes the day.

transfer_rulesobject[]
6 fields
descriptionstring

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.

typeenum<string>

EXTERNAL_NUMBER transfers to any phone number, MEMBER to a teammate, INBOX to another Allo line.

EXTERNAL_NUMBERMEMBERINBOX

transfer_messagestring | null

What the receptionist says before transferring.

target_numberstring | null

Required for EXTERNAL_NUMBER. E.164 format.

target_member_idstring | null

Required for MEMBER. A user id from GET /v2/api/users.

target_line_numberstring | null

Required for INBOX. Another of your Allo numbers, in E.164 format.

schedulingobject
1 fields
calendarsobject[]

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.

7 fields
calendar_connection_idstring
namestring | null
providerenum<string>

GOOGLE_CALENDARCAL_COMCALENDLYOUTLOOK

statusenum<string>

ACTIVEDISCONNECTED

is_team_defaultboolean
ownerobject

The teammate who connected the calendar.

event_typesobject[]
knowledgeobject

What the receptionist knows about the business: facts, prices, policies, hours.

3 fields
textstring | null

Deprecated. Free-text knowledge, up to 25000 characters, stored as the line's "Business knowledge" text source.

websitesobject[]
5 fields
idstring
urlstring
statusenum<string>

ACTIVE when this line's receptionist answers from the website, DISABLED when this line does not use it.

ACTIVEDISABLED

created_atstring<date-time> | null
updated_atstring<date-time> | null
filesobject[]
5 fields
idstring
file_namestring
statusenum<string>

ACTIVEDISABLED

created_atstring<date-time> | null
updated_atstring<date-time> | null
400
401
403
404
429