Allo

Turn on or off

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.

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
409
429