Allo

Overview

Read and write the AI receptionist of an Allo line: prompt, voice, business hours, transfer rules, calendars and knowledge

Updated on

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.

BlockWhat it holds
agentWho the receptionist is: name, business details, language, voice, greeting and closing message, tone, answer length. Also its status, which is read-only here.
promptWhat it is trying to achieve and how it behaves, in six sections. Written with its own endpoint.
capabilitiesWhat it is allowed to do on a call: SCHEDULING, CALL_TRANSFER, WARM_TRANSFER.
business_hoursWhen the business is open, per day, in the timezone you set.
transfer_rulesThe reasons it hands a call over, and where each one goes.
schedulingThe calendars it books on, with the event types selected for each.
knowledgeThe 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_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