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

# Connect your first AI agent to a phone number

> Bind one of your Orbit AI agents to a number, place a real inbound call from your phone, and verify the whole path: the binding, the disclosure, the live conversation, and the quality readout.

# Connect your first AI agent to a phone number

An Orbit AI agent answers phone calls as soon as you bind it to one of your numbers: the carrier delivers the inbound call, Orbit connects the caller to your agent, and the conversation lands in your call log with a transcript and a quality score. This guide walks the full path once, on one number and one agent, with the dashboard and the equivalent API calls side by side.

## Prerequisites

* **An active AI agent.** If you don't have one yet, build and activate one in [Build an AI agent from a prompt](/guides/agent-from-prompt). Only active agents can answer; note the agent id (`agt_…`) from the AI Agents hub.
* **A number with the voice capability.** If you don't have one, buy one as described in [Buy numbers](/guides/buy-numbers). Local and toll-free numbers both work for inbound voice.
* **A mobile phone you can call from.** You will place a real PSTN call so you hear exactly what your callers hear.
* **An API key**, if you prefer the API path. Every step below shows both.

```bash theme={null}
export PHONE_NUMBER="+14155550123"   # the number your agent will answer
export AGENT_ID="agt_..."          # the active agent from AI Agents
```

## Decide where the agent runs

Two shapes exist for an AI agent answering an Orbit number:

* **Orbit-native agent.** You build and prompt the agent under **AI Agents** in the dashboard, and Orbit runs the conversation end to end: speech, tool calls, transcripts, handoff, and quality scoring stay in-platform. This is the path this guide covers.
* **Third-party voice agent** (callers.ai, Retell, Vapi, or your own SIP endpoint). Orbit still owns the number and the carrier side, then forwards the call over SIP while the vendor runs the conversation. Follow [AI Voice Agents via sip\_forward](/guides/ai-voice-agent-sip-forward) for that path instead.

If you are unsure, start native: you can repoint the same number at a `sip_forward` target later without changing the number.

## Assign the agent to the number

In the dashboard, open **Numbers**, select the number, and under inbound routing choose **AI agent**, pick your active agent, and save. The same binding is available as a drag-and-drop on the **Numbers → Assignments** board, where you drop the number onto the agent card.

The equivalent API call sets the number's inbound route to `agent`:

```bash theme={null}
curl -s -X PUT "https://api.orbit.devotel.io/api/v1/numbers/$PHONE_NUMBER/routing" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "agent",
    "config": {
      "agentId": "'"$AGENT_ID"'"
    }
  }'
```

Read the route back to confirm it took:

```bash theme={null}
curl -s "https://api.orbit.devotel.io/api/v1/numbers/$PHONE_NUMBER/routing" \
  -H "X-API-Key: dv_live_sk_..."
```

Expect `"type": "agent"` with your `agentId` in the response. If the write returns a 422 saying the route requires `{ agentId }`, the `config` shape is wrong; if the agent id is rejected, the agent is not active or not in this workspace.

The binding is per number. Replacing an existing route (a softphone, IVR, or queue) with `agent` means this number rings the agent from now on; every other number keeps its own route.

## Disclosure and consent for voice

Callers should know they are talking to an AI, and several jurisdictions require you to say so. Set your workspace posture under **Settings → Compliance → AI Disclosure**, then make sure the agent's opening line states that the caller is speaking with an AI assistant. [AI disclosure pre-publish setup & evidence](/guides/ai-disclosure-setup) walks through choosing the regimes that apply to your traffic and verifying the notice actually renders.

A PSTN call has no consent screen between the caller and the agent, so the disclosure lives in what the agent says when it answers. If you also run the web-call widget, that channel carries its own notice and consent copy under **Settings → Channels → AI Voice Agent**; the [Voice Agent channel toggles walkthrough](/guides/channel-voice-agent-toggles) covers it.

## Place a real call

From your mobile phone, dial the number. Within a couple of seconds you should hear the agent's greeting, including the AI disclosure. While you are on the call, try:

* Ask something the agent knows, and check the answer matches its prompt or knowledge base.
* Interrupt it mid-sentence; a healthy voice agent stops and listens.
* Ask for a human, if you configured a handoff, and confirm the transfer behaves the way you designed it.

While the call is live, open **Voice → Calls** in the dashboard and watch the row appear with its status. When the call ends, the row keeps the duration, the disposition, and links into the recording and transcript.

## Read what happened

After the call, three surfaces tell you how the agent did:

* **Transcript and tool history.** Open the call's conversation to see every turn, including which tools the agent called and what they returned. [Debug an agent conversation](/guides/agent-conversation-debug) walks through reading it.
* **Quality score.** [Voice agent quality (VAQI)](/guides/voice-agent-quality-vaqi) explains the per-call score and its components, so a bad call tells you whether understanding, latency, or task completion was the problem.
* **The call log entry.** The row in **Voice → Calls** carries the duration, disposition, and recording for the call you just placed.

Then close the loop: read the transcript, tighten the prompt, call again. Agent changes apply to the next call; no re-bind needed.

## Common misconfigs

* **Agent not active.** A draft or paused agent cannot answer. The routing picker lists active agents only, and the API rejects any other status. Activate the agent under **AI Agents**, then save the binding again.
* **Number not bound.** The call rings a person or an IVR because the number still carries its old route type. Read the route back and confirm `"type": "agent"`.
* **Call never rings.** Business hours or quiet hours set on the number or workspace mute calls outside their window. Check the schedule before suspecting the agent.
* **Missing disclosure.** The agent's greeting never says it is an AI. Fix the opening line in the agent prompt and re-run the verification from [AI disclosure pre-publish setup & evidence](/guides/ai-disclosure-setup).
* **Agent answers but misbehaves.** That is a prompt or grounding problem, not a wiring problem. [Troubleshooting agent errors](/troubleshooting/agent-errors) maps the common symptoms to their fixes.

## See also

* [Build an AI agent from a prompt](/guides/agent-from-prompt)
* [Buy numbers](/guides/buy-numbers)
* [AI Voice Agents via sip\_forward](/guides/ai-voice-agent-sip-forward)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.