Phone Numbers
Share a Phone Number Between Agents
Let several DialNexa agents call from one phone number, with callbacks routed to the agent that last called each person.
PUT
Changes state - verify before retry
Share a phone number between agents when several agents need to call leads from the same caller ID. A shared number has any number of outbound agents and no inbound agent. When someone calls the number back, DialNexa connects them to the most recent agent that called them from this number and is still linked to it.
Then attach each agent to the number with Attach Agent Phone Number and
When to use this
- One caller ID, several campaigns: a sales agent and a renewals agent both call from your main business number.
- Callbacks that reach the right agent: a lead who calls back talks to the agent that called them, not a generic inbound agent.
How callbacks are routed on a shared number
A call counts as calling the person when it reached their phone: answered, busy, or not picked up. A call that failed before ringing does not count.
A default number can be shared so several agents call from it, but it never answers inbound calls, so every callback to it is refused.
Workflows on a shared number
- Voice Call steps keep their agent. Turning sharing on sets the number’s outbound agent as
configured_agent_idon every workflow Voice Call step that uses the number and names no agent. Attaching a second outbound agent does the same first. Those steps keep calling as that agent after more agents join. - Steps on a number with several agents name their agent. A Voice Call step on a shared number with more than one agent must set
configured_agent_idto one of them, or the workflow cannot be activated. - Callbacks from workflow leads. When a workflow lead calls a shared number back, the lead moves to the workflow’s first Voice Call step on that number that calls as the agent answering. If the workflow has no such step, the call is answered and the workflow does not move.
Before you begin
- Get the number’s
phn_ID from List Phone Numbers. - Turning sharing on removes the number’s inbound agent. Check
inbound_agent_idwith Get Phone Number Details and move that agent to another number first if it must keep answering calls. - Wait for live inbound calls on the number to end. They block the change.
- Turning sharing off needs at most one outbound agent. Detach the others with Detach Agent Phone Number first.
Share a phone number request
"direction": "outbound". On a shared number the link is added next to the existing agents, and move is ignored.
Send { "enabled": false } to stop sharing. The number then has no inbound agent until you attach one.
Verify the result
A200 response returns the phone number in data, with:
shared_outboundset to the value you sent.outbound_agent_idslisting every agent that can call from the number, newest link first.inbound_agent_idset to null when sharing is on.detached_inbound_agent_idnaming the agent that stopped answering this number, or null when there was none.
Errors and recovery
Refusals carry a code indata.code.
Related endpoints
Authorizations
Body
application/json
Response
Sharing updated. Returns the phone number with detached_inbound_agent_id.