Every Allo line has an AI receptionist. These endpoints read its whole configuration in one call and write any part of it: business details, voice and language, the prompt it answers with, what it is allowed to do on a call, business hours, transfer rules, the calendars it books on, and what it knows about the business.
Connect the Allo MCP to your AI assistant and configuring a receptionist becomes a conversation about your business instead of a set of requests to write. Same endpoints as this page, a better way to drive them.
How the configuration is laid out
GET /v2/api/numbers/{number}/agent answers "how is this receptionist set up?" in one response, split into seven blocks.
| Block | What it holds |
|---|---|
agent | Who the receptionist is: name, business details, language, voice, greeting and closing message, tone, answer length. Also its status, which is read-only here. |
prompt | What it is trying to achieve and how it behaves, in six sections. Written with its own endpoint. |
capabilities | What it is allowed to do on a call: SCHEDULING, CALL_TRANSFER, WARM_TRANSFER. |
business_hours | When the business is open, per day, in the timezone you set. |
transfer_rules | The reasons it hands a call over, and where each one goes. |
scheduling | The calendars it books on, with the event types selected for each. |
knowledge | The facts it answers from: websites and uploaded documents from your team's knowledge library, plus text, which is deprecated. |
Two merge rules
PATCH /v2/api/numbers/{number}/agent applies two different rules, and mixing them up is the one mistake that costs configuration:
- Single values are merged.
name, the business details,language,voice_id,greeting_message,closing_message,tone_of_voice,answer_typeandknowledge.textkeep their current value when you omit them. - Collections are replaced.
capabilities,business_hours,transfer_rulesandscheduling.calendarsare complete sets. Send one and it replaces what was configured, omit it and it is left alone.
So adding a single transfer rule means reading the existing ones first and sending them back together with the new one. The same goes for capabilities: a capability left out of the map is turned off, not kept.
A field the API does not know is rejected with 400 UNKNOWN_FIELD rather than dropped in silence, so a typo never answers 200 OK.
Writing the prompt
The prompt has its own endpoint because it is only valid whole. objective, personality and behaviors are required, and every write re-renders the prompt the receptionist answers with, so Set prompt replaces the full section list.
Facts about the business go in knowledge, not in the prompt. Prices, hours, policies and FAQs change often and belong where the receptionist looks them up.
What this API does not do
- Uploading documents. Files are uploaded in the Allo app. Here you list and delete them.
- Connecting a calendar. That is an OAuth flow, done in the Allo app. Here you list what is connected and choose what the receptionist books on.
- Creating a receptionist. A line has one from the moment it exists.
Endpoints
The whole receptionist configuration of a line, in one call
Business details, voice, capabilities, hours, transfer rules, calendars, knowledge text
Replace the prompt sections the receptionist answers with
Put the receptionist on the line, or send calls to your business phone
Crawl a website for the receptionist to answer from
Turn a website off for this line without losing its crawled content
Remove a website from your team's knowledge library
Remove an uploaded document from your team's knowledge library
The calendars connected to your workspace
One calendar with the event types its provider offers
The voices a receptionist can speak with