Skip to main content

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

​
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 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:
Read the route back to confirm it took:
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. 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 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 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 walks through reading it.
  • Quality score. 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.
  • Agent answers but misbehaves. That is a prompt or grounding problem, not a wiring problem. Troubleshooting agent errors maps the common symptoms to their fixes.

​
See also