> ## Documentation Index
> Fetch the complete documentation index at: https://help.withallo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

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

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.

<Note>
  **Required scopes:** `AGENTS_READ` to read, `AGENTS_WRITE` to write. Create a key with them in [Settings > API](https://web.withallo.com/settings/api).
</Note>

<Card title="Let the Allo MCP set it up for you" icon="https://mintcdn.com/themobilefirstcompany/I-AZGjY8JNMbLMCH/media/integrations/MCP.svg?fit=max&auto=format&n=I-AZGjY8JNMbLMCH&q=85&s=f1ec6f445ca7aa3bb3b4421b863fd105" href="/en/integrations/mcp" width="24" height="24" data-path="media/integrations/MCP.svg">
  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.
</Card>

## 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: free text, scraped websites, uploaded documents.                                                                                      |

## 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](/en/v2/api-reference/agent/set-agent-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

<CardGroup cols={2}>
  <Card title="Get configuration" href="/en/v2/api-reference/agent/get-agent">
    The whole receptionist configuration of a line, in one call
  </Card>

  <Card title="Update configuration" href="/en/v2/api-reference/agent/update-agent">
    Business details, voice, capabilities, hours, transfer rules, calendars, knowledge text
  </Card>

  <Card title="Set prompt" href="/en/v2/api-reference/agent/set-agent-prompt">
    Replace the prompt sections the receptionist answers with
  </Card>

  <Card title="Turn on or off" href="/en/v2/api-reference/agent/set-agent-status">
    Put the receptionist on the line, or send calls to your business phone
  </Card>

  <Card title="Add website knowledge" href="/en/v2/api-reference/agent/add-website-knowledge">
    Scrape a page for the receptionist to answer from
  </Card>

  <Card title="Enable or disable a website" href="/en/v2/api-reference/agent/update-website-knowledge">
    Turn an entry off without losing its scraped content
  </Card>

  <Card title="Delete website knowledge" href="/en/v2/api-reference/agent/delete-website-knowledge">
    Remove a scraped page from the receptionist's knowledge
  </Card>

  <Card title="Delete file knowledge" href="/en/v2/api-reference/agent/delete-file-knowledge">
    Remove an uploaded document from the receptionist's knowledge
  </Card>

  <Card title="List calendars" href="/en/v2/api-reference/agent/list-calendars">
    The calendars connected to your workspace
  </Card>

  <Card title="Get a calendar" href="/en/v2/api-reference/agent/get-calendar">
    One calendar with the event types its provider offers
  </Card>

  <Card title="List voices" href="/en/v2/api-reference/agent/list-voices">
    The voices a receptionist can speak with
  </Card>
</CardGroup>