Puts the receptionist on the line ( ACTIVE ) or takes it off ( FORWARDING , which sends calls to your business phone instead). This reprograms how a live…
PUT/v2/api/numbers/{number}/agent/status
Behavior
Puts the AI receptionist on the line or takes it off, and returns the whole configuration with the new status.
ACTIVE: the receptionist answers incoming calls.
FORWARDING: it does not, and calls go to your business phone instead.
Turning the receptionist off forwards calls to your workspace's business phone number, so one has to be set. That number is not the receptionist's business_phone and is not writable through this API.
Errors
400 AGENT_NO_FORWARDING_NUMBER: FORWARDING was requested and no business phone is set on the workspace. Until one is, the receptionist can only stay ACTIVE.
409 AGENT_LINE_NOT_ASSIGNED: the line has no phone number assigned, so it can neither answer nor forward.
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
statusenum<string>required
ACTIVE puts the receptionist on the line. FORWARDING takes it off and sends calls to your business phone.
ACTIVEFORWARDING
Responses
200The configuration, with the new status
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.
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.