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

# Voice (PSTN)

> Put an agent on a real phone number and answer inbound calls.

Voice is the flagship channel: a published agent answers a real phone number over the public
telephone network (PSTN), greets the caller, answers from its knowledge, runs its skills, and
hands off to a person when needed. There is nothing to host — you buy a number, point it at an
agent, and inbound calls just work.

## Get a number, point it at an agent

<Steps>
  <Step title="Search availability">
    Browse purchasable numbers by area code, city, or vanity suffix. Filter by capability
    (require `voice`, and `sms` if you plan to text from it later).
  </Step>

  <Step title="Reserve (optional), then purchase">
    Hold a number for \~30 minutes so it can't be sniped while you confirm, then purchase it.
    Purchase debits your prepaid wallet. Already own a number elsewhere? **Import** it instead —
    no wallet charge.
  </Step>

  <Step title="Assign it to an agent">
    Assigning sets the number's default agent. Inbound calls to that number are routed to this
    deployment's voice connection and reach your agent.
  </Step>
</Steps>

The agent must be **published** to take live calls — phone and chat always serve the last
published version, never your draft. See [Draft vs Published](/get-started/draft-vs-published).

## On the call

The agent opens with its configured greeting (spoken in the agent's primary language), listens
with real-time turn detection, and responds with the platform's voice engine. Knowledge lookups,
skills, and playbooks all run live. Per-agent **call control** governs the experience: a maximum
call length, "are you still there?" idle reminders, and what to do on silence.

## Transfer and handoff

When a caller needs a person, the agent transfers the call. You configure a default handoff
destination plus a **transfer-by-context** table — plain-language rules that route specific
situations (billing, Spanish line, a region) to specific numbers. A data-lookup skill can also
supply a dynamic destination at call time (for example, route to the booked technician). The
original caller ID is passed through to the receiving line.

## Keypad input (DTMF)

Callers can press keypad digits during a call — useful for menus, account numbers, or
confirmations. See [DTMF / Keypad](/channels/dtmf).

## In the API

| Action                   | Endpoint                      | Scope           |
| ------------------------ | ----------------------------- | --------------- |
| Search available numbers | `GET /numbers/search`         | `numbers:read`  |
| Reserve a number         | `POST /numbers/reserve`       | `numbers:write` |
| Purchase a number        | `POST /numbers/purchase`      | `numbers:write` |
| Import a number you own  | `POST /numbers/import`        | `numbers:write` |
| Assign to an agent       | `POST /numbers/{id}/assign`   | `numbers:write` |
| Unassign (keep, pool it) | `DELETE /numbers/{id}/assign` | `numbers:write` |
| Release a number         | `DELETE /numbers/{id}`        | `numbers:write` |
| Review call summaries    | `GET /agents/{agentId}/calls` | `calls:read`    |

```bash theme={null}
# Assign a purchased number to a published agent
curl -X POST https://builder.flowyte.com/api/v1/numbers/NUM_ID/assign \
  -H "Authorization: Bearer flowyte_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "AGENT_ID"}'
```

<Warning>
  `DELETE /numbers/{id}` permanently **releases** the number back to the carrier. To detach a
  number from an agent while keeping it, use `DELETE /numbers/{id}/assign` to move it to the pool.
</Warning>

<Tip>
  Configure the greeting, transfer rules, and call control on the agent, then republish. Editing
  without republishing changes only the draft — the live phone line keeps serving the old version.
</Tip>