Skip to main content
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.

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.
Keep the number unshared if it needs one fixed inbound agent, for example a support line that anyone can call.

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_id on 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_id to 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_id with 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

Then attach each agent to the number with Attach Agent Phone Number and "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

A 200 response returns the phone number in data, with:
  • shared_outbound set to the value you sent.
  • outbound_agent_ids listing every agent that can call from the number, newest link first.
  • inbound_agent_id set to null when sharing is on.
  • detached_inbound_agent_id naming the agent that stopped answering this number, or null when there was none.
If the request times out, read the number with Get Phone Number Details before retrying.

Errors and recovery

Refusals carry a code in data.code.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

Phone number ID

Example:

"phn_abc123"

Body

application/json
enabled
boolean
required

true lets several agents dial from this number. Its inbound agent is detached and each callback goes to the agent that last called the person; calls from people no linked agent has called are not answered.

Example:

true

Response

Sharing updated. Returns the phone number with detached_inbound_agent_id.

success
enum<boolean>
required
Available options:
true
error
enum<boolean>
required
Available options:
false
statusCode
integer
required
Example:

200

message
string
required
Example:

"Success"

data
object
required

A phone number owned by the workspace, as stored. Returned by the list and get endpoints.

timestamp
string<date-time>
required