Overview

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.

​

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.

​

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_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.

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