---
title: "Turn the AI receptionist on or off"
method: PUT
path: "/v2/api/numbers/{number}/agent/status"
tags: ["AI Receptionist"]
---

# Turn the AI receptionist on or off

`PUT /v2/api/numbers/{number}/agent/status`

## Request

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

Puts the receptionist on the line (`ACTIVE`) or takes it off (`FORWARDING`, which sends calls to your business phone instead). This reprograms how a live line routes real calls, so confirm with a person before calling it.

## Path parameters

- `number` string, required

## Request body

- SetAgentStatusRequest
  - `status` 'ACTIVE' | 'FORWARDING', required: `ACTIVE` puts the receptionist on the line. `FORWARDING` takes it off and sends calls to your business phone.

## Response `200`

The configuration, with the new status

- 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

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: API key lacks the required scope or access to the resource
- `404`: Resource not found
- `409`: Conflict with existing resource
- `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/status/put.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)