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

# Get configuration

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

<Note>
  **Required scope:** `AGENTS_READ`
</Note>

## Behavior

Returns the whole configuration of one line's AI receptionist. The `{number}` path parameter is the Allo phone number in E.164 format.

Read this before any write. [Update configuration](/en/v2/api-reference/agent/update-agent) replaces whole collections, so you need the current state to avoid dropping configuration you did not mean to touch.

## What comes back

* `agent` holds the receptionist's own settings, plus `status` and `is_default`, which are read-only here.
* `prompt` carries either `sections` or `custom_prompt`, never both. `custom_prompt` is what an older line has when its prompt was written as freeform text.
* `capabilities` always reports all three toggles, so `false` means off, not unavailable.
* `scheduling.calendars` lists only the calendars this receptionist books on. To see every calendar connected to the workspace, call [List calendars](/en/v2/api-reference/agent/list-calendars).
* `knowledge.websites` reports each entry without its scraped text. That text is what the receptionist reads, not something you configure.

## Errors

* `403 API_KEY_INSUFFICIENT_SCOPE`: the key does not hold `AGENTS_READ`.
* `404 PHONE_NUMBER_NOT_FOUND`: the number is not one you have access to.


## OpenAPI

````yaml GET /v2/api/numbers/{number}/agent
openapi: 3.0.3
info:
  title: Allo API
  description: >-
    Allo API provides programmatic access to your Allo account, allowing you to
    manage webhooks, retrieve calls and contacts, and send SMS messages.


    All requests to `/v1/api/**` endpoints automatically go through quota
    checking and scope validation.
  version: 1.0.0
  contact:
    name: Allo Support
servers:
  - url: https://api.withallo.com
    description: Production server
security: []
tags:
  - name: Summary Templates
    description: >-
      Manage call summary templates that control how AI-generated call summaries
      are structured for your team.
  - name: Webhooks
    description: >-
      Manage webhook endpoints to receive real-time notifications about events
      in your Allo account. Each endpoint subscribes to one or more event topics
      and is verified with a signing secret.
  - name: Calls
    description: >-
      Retrieve and search call records with filtering and pagination. Filter
      calls by your Allo phone number.
  - name: Contacts
    description: >-
      Search and retrieve contact information with sorting and pagination.
      Includes engagement level tracking.
  - name: SMS
    description: Send SMS messages to phone numbers using your Allo numbers.
  - name: Phone Numbers
    description: Retrieve information about your Allo phone numbers.
  - name: Analytics
    description: Pre-computed call metrics, team performance, and outbound dial funnel
  - name: CRM
    description: Manage people, companies, and deals in your CRM.
  - name: Notes
    description: >-
      Internal team notes on conversations and CRM people, with @mention
      support. Notes are never visible to the contact.
  - name: Threads
    description: >-
      Team discussion threads attached to a conversation item (call, SMS, or
      conversation note). One thread per item.
  - name: AI Receptionist
    description: >-
      Read and write the AI receptionist configuration of a phone line: business
      details, voice, prompt, capabilities, business hours, transfer rules,
      scheduling calendars and knowledge sources.
paths:
  /v2/api/numbers/{number}/agent:
    get:
      tags:
        - AI Receptionist
      summary: Get AI receptionist configuration
      description: >-
        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.
      operationId: getAgent
      parameters:
        - name: number
          in: path
          required: true
          description: Allo phone number in E.164 format
          schema:
            type: string
            example: '+14155551234'
      responses:
        '200':
          description: The line's receptionist configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentSnapshot'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '403':
          $ref: '#/components/responses/ApiForbidden'
        '404':
          $ref: '#/components/responses/ApiNotFound'
        '429':
          $ref: '#/components/responses/ApiRateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AgentSnapshot:
      type: object
      description: The whole configuration of one line's AI receptionist.
      properties:
        agent:
          $ref: '#/components/schemas/AgentConfig'
        prompt:
          $ref: '#/components/schemas/AgentPrompt'
        capabilities:
          $ref: '#/components/schemas/AgentCapabilities'
        business_hours:
          $ref: '#/components/schemas/AgentBusinessHours'
        transfer_rules:
          type: array
          items:
            $ref: '#/components/schemas/AgentTransferRule'
        scheduling:
          $ref: '#/components/schemas/AgentScheduling'
        knowledge:
          $ref: '#/components/schemas/AgentKnowledge'
    AgentConfig:
      type: object
      description: >-
        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`.
      properties:
        id:
          type: string
          nullable: true
          example: agt-abc123
        status:
          type: string
          enum:
            - ACTIVE
            - FORWARDING
          description: >-
            `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:
          type: string
          nullable: true
          description: The name the receptionist gives itself on a call.
          example: Maya
        is_default:
          type: boolean
          description: >-
            True while the line still runs Allo's default receptionist, with no
            prompt, greeting, closing or knowledge of its own.
        business_name:
          type: string
          nullable: true
          example: Acme Plumbing
        business_address:
          type: string
          nullable: true
          example: 12 Main Street, Austin TX
        business_phone:
          type: string
          nullable: true
          description: The business's own phone number, in E.164 format.
          example: '+14155551234'
        business_email:
          type: string
          nullable: true
          example: hello@acme.test
        business_website:
          type: string
          nullable: true
          example: https://acme.test
        business_industry:
          type: string
          nullable: true
          example: Plumbing
        language:
          type: string
          nullable: true
          enum:
            - fr
            - fr-CA
            - en-US
            - en-GB
            - es
            - de
            - hr
          description: >-
            The language the receptionist speaks. Pick a `voice_id` listed under
            the same language.
          example: en-US
        voice_id:
          type: string
          nullable: true
          description: Identifier of a voice from `GET /v2/api/voices`.
          example: maya
        greeting_message:
          type: string
          nullable: true
          description: What the receptionist says when it picks up.
          example: Thanks for calling Acme Plumbing, how can I help?
        closing_message:
          type: string
          nullable: true
          description: What the receptionist says before hanging up.
          example: Thanks for calling, have a good day.
        tone_of_voice:
          type: string
          enum:
            - FRIENDLY
            - PROFESSIONAL
            - NEUTRAL
            - ENTHUSIASTIC
        answer_type:
          type: string
          enum:
            - CONCISE
            - STANDARD
            - DETAILED
          description: How long the receptionist's answers run.
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
    AgentPrompt:
      type: object
      description: >-
        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.
      properties:
        sections:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/AgentPromptSection'
        custom_prompt:
          type: string
          nullable: true
    AgentCapabilities:
      type: object
      description: >-
        What the receptionist is allowed to do on a call. All three are always
        reported.
      properties:
        SCHEDULING:
          type: boolean
          description: Book appointments on the calendars in `scheduling.calendars`.
        CALL_TRANSFER:
          type: boolean
          description: Transfer the call using the rules in `transfer_rules`.
        WARM_TRANSFER:
          type: boolean
          description: >-
            Announce the caller to the person taking the transfer before
            connecting them.
    AgentBusinessHours:
      type: object
      description: When the business is open. A day left out of `schedule` is closed.
      properties:
        timezone:
          type: string
          nullable: true
          description: IANA timezone identifier.
          example: America/New_York
        schedule:
          type: array
          items:
            $ref: '#/components/schemas/AgentDaySchedule'
    AgentTransferRule:
      type: object
      description: >-
        One reason the receptionist hands the call over, and where it hands it
        to.
      properties:
        description:
          type: string
          description: >-
            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.
          example: Billing or invoice questions
        type:
          type: string
          enum:
            - EXTERNAL_NUMBER
            - MEMBER
            - INBOX
          description: >-
            `EXTERNAL_NUMBER` transfers to any phone number, `MEMBER` to a
            teammate, `INBOX` to another Allo line.
        transfer_message:
          type: string
          nullable: true
          description: What the receptionist says before transferring.
          example: Let me put you through to billing.
        target_number:
          type: string
          nullable: true
          description: Required for `EXTERNAL_NUMBER`. E.164 format.
          example: '+14155551234'
        target_member_id:
          type: string
          nullable: true
          description: Required for `MEMBER`. A user id from `GET /v2/api/users`.
        target_line_number:
          type: string
          nullable: true
          description: Required for `INBOX`. Another of your Allo numbers, in E.164 format.
    AgentScheduling:
      type: object
      properties:
        calendars:
          type: array
          description: >-
            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`.
          items:
            $ref: '#/components/schemas/AgentCalendar'
    AgentKnowledge:
      type: object
      description: >-
        What the receptionist knows about the business: facts, prices, policies,
        hours.
      properties:
        text:
          type: string
          nullable: true
          description: Free-text knowledge, up to 25000 characters.
        websites:
          type: array
          items:
            $ref: '#/components/schemas/AgentWebsiteKnowledge'
        files:
          type: array
          items:
            $ref: '#/components/schemas/AgentFileKnowledge'
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            request_id:
              type: string
            retry_after_seconds:
              type: integer
              nullable: true
    AgentPromptSection:
      type: object
      description: >-
        One section of the prompt. `required_fields` carries `fields` and no
        `content`; every other section carries `content` and no `fields`.
      properties:
        section:
          type: string
          enum:
            - objective
            - personality
            - behaviors
            - prohibited
            - required_fields
            - objective_completion
        title:
          type: string
          description: Human-readable title, derived server-side from `section`.
          example: Objective
        content:
          type: string
          nullable: true
          example: Book a visit with the caller.
        fields:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/AgentPromptField'
    AgentDaySchedule:
      type: object
      required:
        - day
        - schedule
      properties:
        day:
          type: string
          enum:
            - MO
            - TU
            - WE
            - TH
            - FR
            - SA
            - SU
        schedule:
          type: array
          description: The open periods of that day. An empty array closes the day.
          items:
            $ref: '#/components/schemas/AgentTimeInterval'
    AgentCalendar:
      type: object
      description: >-
        A calendar this receptionist can book on, with the event types selected
        for it.
      properties:
        calendar_connection_id:
          type: string
          example: exc-abc123
        name:
          type: string
          nullable: true
          example: Acme bookings
        provider:
          type: string
          enum:
            - GOOGLE_CALENDAR
            - CAL_COM
            - CALENDLY
            - OUTLOOK
        status:
          type: string
          enum:
            - ACTIVE
            - DISCONNECTED
        is_team_default:
          type: boolean
        owner:
          $ref: '#/components/schemas/CalendarOwner'
          nullable: true
        event_types:
          type: array
          items:
            $ref: '#/components/schemas/SchedulingEventType'
    AgentWebsiteKnowledge:
      type: object
      description: >-
        A page Allo scraped and summarized for the receptionist to answer from.
        The scraped text itself is not reported: it is what the receptionist
        reads, not something you configure.
      properties:
        id:
          type: string
          example: wkb-abc123
        url:
          type: string
          example: https://acme.test/pricing
        status:
          type: string
          enum:
            - ACTIVE
            - DISABLED
          description: >-
            `DISABLED` keeps the entry and its scraped text, and stops the
            receptionist using it.
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
    AgentFileKnowledge:
      type: object
      description: >-
        A document uploaded in the Allo app for the receptionist to answer from.
        Uploading is done in the app; this API lists and deletes.
      properties:
        id:
          type: string
          example: fkb-abc123
        file_name:
          type: string
          example: pricing.pdf
        status:
          type: string
          enum:
            - ACTIVE
            - DISABLED
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
    AgentPromptField:
      type: object
      description: >-
        One piece of information the receptionist has to collect during the
        call.
      required:
        - label
        - question
        - complete_when
      properties:
        label:
          type: string
          example: Email
        question:
          type: string
          example: What is the best email to send the quote to?
        complete_when:
          type: string
          description: How the receptionist knows it has the answer.
          example: a valid email address is given
    AgentTimeInterval:
      type: object
      description: >-
        One open period of a day, in seconds since midnight (0 to 86399). 9am to
        5pm is 32400 to 61200.
      required:
        - start_time
        - end_time
      properties:
        start_time:
          type: integer
          minimum: 0
          maximum: 86399
          example: 32400
        end_time:
          type: integer
          minimum: 0
          maximum: 86399
          example: 61200
    CalendarOwner:
      type: object
      description: The teammate who connected the calendar.
      properties:
        user_id:
          type: string
        user_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        is_current_user:
          type: boolean
    SchedulingEventType:
      type: object
      description: >-
        An event type the receptionist may book. Send `id`, `slug`, `title` and
        `length_in_minutes` back as `GET /v2/api/calendars/{id}` reported them.
      required:
        - id
        - slug
        - title
      properties:
        id:
          type: string
          description: The provider's own event-type identifier.
          example: '42'
        slug:
          type: string
          example: intro-call
        title:
          type: string
          example: Intro call
        length_in_minutes:
          type: integer
          nullable: true
          example: 30
        description:
          type: string
          nullable: true
          description: >-
            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.
          example: Book this one when the caller wants a quote.
        required_questions:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SchedulingQuestion'
    SchedulingQuestion:
      type: object
      description: >-
        A question the calendar provider rejects a booking without, so the
        receptionist asks it during the call. Read-only: it is snapshotted when
        the event type is selected.
      properties:
        id:
          type: string
          example: notes
        label:
          type: string
          example: Anything we should know before the visit?
  responses:
    ApiUnauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiForbidden:
      description: API key lacks the required scope or access to the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiRateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````