Allo

Get configuration

Returns the whole configuration of a line's AI receptionist in one call: business details, voice and language, prompt, capabilities, business hours, transfer…

GET/v2/api/numbers/{number}/agent

Behavior

Returns the whole configuration of one line's AI receptionist. The {number} path parameter is the Allo phone number in E.164 format.

Read this before any write. Update configuration replaces whole collections, so you need the current state to avoid dropping configuration you did not mean to touch.

What comes back

  • agent holds the receptionist's own settings, plus status and is_default, which are read-only here.
  • prompt carries either sections or custom_prompt, never both. custom_prompt is what an older line has when its prompt was written as freeform text.
  • capabilities always reports all three toggles, so false means off, not unavailable.
  • scheduling.calendars lists only the calendars this receptionist books on. To see every calendar connected to the workspace, call List calendars.
  • knowledge.websites and knowledge.files list your team's whole knowledge library, without the crawled or extracted text. status is ACTIVE when this line's receptionist answers from the entry and DISABLED when this line does not use it.
  • knowledge.text is deprecated. It is still returned, see Update configuration.

Errors

  • 403 API_KEY_INSUFFICIENT_SCOPE: the key does not hold AGENTS_READ.
  • 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

Responses

200The line's receptionist configuration
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
401
403
404
429