Connect an agent
By the end of this page a caller who dials your number will be talking to your agent, and the call will show up in your call log.
Prerequisites
- A provisioned number in Active status — see Get a phone number.
- An AI Agent with Voice enabled — see Modes and Voice configuration.
- An active deployment that includes that agent — see Production deployments.
Why the deployment comes first
The dialog asks for a deployment before it asks for an agent, and that order matters — though not for the reason you might guess. Choosing the deployment does two things:
- It scopes the agent list to agents that are actually in that deployment, so you can’t point a number at an agent that isn’t running anywhere.
- It records the deployment against the number, which is what makes every call appear under Deployments → Executions alongside your other runs.
It does not pin a version. A call is answered by the agent’s newest Ready or Production version as of the moment the call arrives — so promoting a new version changes what callers hear immediately, and a Ready version that hasn’t been promoted will answer live calls if its version number is higher. Drafts never answer. See Versioning & promotion.
Attach the number
Open the dialog
On the number’s card click Attach Agent. The same dialog is on the number’s detail page, and it behaves identically.
Choose the deployment
Open Select Deployment. Each entry reads app-slug · vN · STATUS so you can tell versions apart.
Only deployments in this project appear. If the list is empty, you don’t have one yet.
Choose the agent
The agent list populates from the deployment you picked. Each row shows the agent’s name, its description, and a badge:
| Badge | Meaning |
|---|---|
| VOICE (green) | The agent has Voice mode enabled. This is what you want. |
| No voice mode (grey) | The agent is in the deployment but hasn’t got Voice switched on. You can attach it, but it won’t handle a call properly. |
Seeing only grey No voice mode badges means no agent in this deployment has Voice enabled. Turn Voice on for the agent, publish it, and redeploy — then come back.
Attach
Click Attach Agent. qRaptor records the binding and configures call routing with Exotel in one operation.
If routing can’t be configured, the attach fails and tells you so — the number is left genuinely unattached rather than half-connected. Retry; if it keeps failing, see Troubleshooting.
The card now reads Attached under Agent, and the number’s detail page gains an Agent Binding card naming the agent and deployment.
Verify with a real call
Do this. It’s the only check that exercises the whole path — number lookup, caller authorization, the audio bridge, and your agent’s voice pipeline.
Dial the number
From any phone. If the number is Authorized Only, make sure you’re calling from a whitelisted number first.
Have a short conversation
Say something, wait for the agent to answer, say one more thing. Ten seconds is plenty.
Check the call log
Go to Integrations → Exotel → View Call Logs. Your call should be there with status Completed and a duration roughly matching the conversation.
If the call connects but the agent doesn’t respond, the problem is the agent’s voice configuration rather than telephony. If the call doesn’t connect at all, start with Troubleshooting.
Change or remove the agent
Both actions are on the card and on the detail page.
Change Agent reopens the same dialog with the current deployment and agent already selected, so you can see what’s attached before changing it.
Changing the agent also lets you change the deployment. Switching deployment re-points where the number’s calls are attributed — if you only meant to swap the agent, leave the deployment as it was.
Detach unbinds the agent and stops calls being answered. The number stays provisioned and keeps costing credits — detaching is not the same as releasing. You’ll be asked to confirm, and the dialog says as much.
Common issues
- No deployments in the dropdown — you don’t have one in this project. Create a deployment containing the agent first.
- “No active AI agents in this deployment” — the deployment has no active AI Agent. Task Agents can’t answer calls.
- Every agent shows “No voice mode” — nobody in that deployment has Voice enabled. Enable it, publish, redeploy.
- “Could not configure call routing for this number with the provider” — qRaptor reached Exotel but the routing change was rejected. The attach was rolled back, so retry safely. If it persists, check the Connection Status card on the Exotel page.
- Attached, but calls go nowhere — confirm the number is Active and not Suspended, and that a whitelist isn’t blocking the caller. See Troubleshooting.