---
title: "Get AI receptionist configuration"
method: GET
path: "/v2/api/numbers/{number}/agent"
tags: ["AI Receptionist"]
---

# Get AI receptionist configuration

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

## Request

- Base URL: `https://api.withallo.com`
- URL: `https://api.withallo.com/v2/api/numbers/{number}/agent`
- Auth: API key in header `Authorization`

Returns the whole configuration of a line's AI receptionist in one call: business details, voice and language, prompt, capabilities, business hours, transfer rules, connected calendars and knowledge sources. Call this before a write, because `PATCH` replaces whole collections.

## Path parameters

- `number` string, required

## Response `200`

The line's receptionist configuration

- object
  - `data` AgentSnapshot: The whole configuration of one line's AI receptionist.
    - `agent` AgentConfig: 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`.
      - `id` string, nullable
      - `status` 'ACTIVE' | 'FORWARDING': `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`.
      - `name` string, nullable: The name the receptionist gives itself on a call.
      - `is_default` boolean: True while the line still runs Allo's default receptionist, with no prompt, greeting, closing or knowledge of its own.
      - `business_name` string, nullable
      - `business_address` string, nullable
      - `business_phone` string, nullable: The business's own phone number, in E.164 format.
      - `business_email` string, nullable
      - `business_website` string, nullable
      - `business_industry` string, nullable
      - `language` 'fr' | 'fr-CA' | 'en-US' | 'en-GB' | 'es' | 'de' | 'hr', nullable: The language the receptionist speaks. Pick a `voice_id` listed under the same language.
      - `voice_id` string, nullable: Identifier of a voice from `GET /v2/api/voices`.
      - `greeting_message` string, nullable: What the receptionist says when it picks up.
      - `closing_message` string, nullable: What the receptionist says before hanging up.
      - `tone_of_voice` 'FRIENDLY' | 'PROFESSIONAL' | 'NEUTRAL' | 'ENTHUSIASTIC'
      - `answer_type` 'CONCISE' | 'STANDARD' | 'DETAILED': How long the receptionist's answers run.
      - `created_at` string, date-time, nullable
      - `updated_at` string, date-time, nullable
    - `prompt` AgentPrompt: 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.
      - `sections` AgentPromptSection[], nullable
        - `section` 'objective' | 'personality' | 'behaviors' | 'prohibited' | 'required_fields' | 'objective_completion'
        - `title` string: Human-readable title, derived server-side from `section`.
        - `content` string, nullable
        - `fields` AgentPromptField[], nullable
          - `label` string, required
          - `question` string, required
          - `complete_when` string, required: How the receptionist knows it has the answer.
      - `custom_prompt` string, nullable
    - `capabilities` AgentCapabilities: What the receptionist is allowed to do on a call. All three are always reported.
      - `SCHEDULING` boolean: Book appointments on the calendars in `scheduling.calendars`.
      - `CALL_TRANSFER` boolean: Transfer the call using the rules in `transfer_rules`.
      - `WARM_TRANSFER` boolean: Announce the caller to the person taking the transfer before connecting them.
    - `business_hours` AgentBusinessHours: When the business is open. A day left out of `schedule` is closed.
      - `timezone` string, nullable: IANA timezone identifier.
      - `schedule` AgentDaySchedule[]
        - `day` 'MO' | 'TU' | 'WE' | 'TH' | 'FR' | 'SA' | 'SU', required
        - `schedule` AgentTimeInterval[], required: The open periods of that day. An empty array closes the day.
          - `start_time` integer, required
          - `end_time` integer, required
    - `transfer_rules` AgentTransferRule[]
      - `description` string: 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.
      - `type` 'EXTERNAL_NUMBER' | 'MEMBER' | 'INBOX': `EXTERNAL_NUMBER` transfers to any phone number, `MEMBER` to a teammate, `INBOX` to another Allo line.
      - `transfer_message` string, nullable: What the receptionist says before transferring.
      - `target_number` string, nullable: Required for `EXTERNAL_NUMBER`. E.164 format.
      - `target_member_id` string, nullable: Required for `MEMBER`. A user id from `GET /v2/api/users`.
      - `target_line_number` string, nullable: Required for `INBOX`. Another of your Allo numbers, in E.164 format.
    - `scheduling` AgentScheduling
      - `calendars` AgentCalendar[]: 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`.
        - `calendar_connection_id` string
        - `name` string, nullable
        - `provider` 'GOOGLE_CALENDAR' | 'CAL_COM' | 'CALENDLY' | 'OUTLOOK'
        - `status` 'ACTIVE' | 'DISCONNECTED'
        - `is_team_default` boolean
        - `owner` CalendarOwner: The teammate who connected the calendar.
          - `user_id` string
          - `user_name` string, nullable
          - `email` string, nullable
          - `is_current_user` boolean
        - `event_types` SchedulingEventType[]
          - `id` string, required: The provider's own event-type identifier.
          - `slug` string, required
          - `title` string, required
          - `length_in_minutes` integer, nullable
          - `description` string, nullable: Your own note on when the receptionist should book this one rather than another. This is what it routes on when several event types are bookable, so write it as the caller's reason.
          - `required_questions` SchedulingQuestion[], nullable
            - `id` string
            - `label` string
    - `knowledge` AgentKnowledge: What the receptionist knows about the business: facts, prices, policies, hours.
      - `text` string, nullable: Deprecated. Free-text knowledge, up to 25000 characters, stored as the line's "Business knowledge" text source.
      - `websites` AgentWebsiteKnowledge[]
        - `id` string
        - `url` string
        - `status` 'ACTIVE' | 'DISABLED': `ACTIVE` when this line's receptionist answers from the website, `DISABLED` when this line does not use it.
        - `created_at` string, date-time, nullable
        - `updated_at` string, date-time, nullable
      - `files` AgentFileKnowledge[]
        - `id` string
        - `file_name` string
        - `status` 'ACTIVE' | 'DISABLED'
        - `created_at` string, date-time, nullable
        - `updated_at` string, date-time, nullable

## Other responses

- `401`: Invalid or missing API key
- `403`: API key lacks the required scope or access to the resource
- `404`: Resource not found
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `46c77103dd14`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withallo/apis/allo-api/changes/v2/api/numbers/:number/agent/get.md)

---

[API](https://skmtc.dev/withallo/apis/allo-api.md) - [All operations](https://skmtc.dev/withallo/apis/allo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withallo/apis/allo-api/revisions/46c77103dd14?raw)