Attach a number to an agent and set outbound caller ID

A number in your workspace does nothing until an agent uses it, and the two directions work differently: inbound is set once and stays; the outbound is picked every time a call is placed. In the dashboard: Sidebar → Assistants → your agent → Attach Number.

Before you start

An agent

For inbound, an agent that takes inbound calls (agent types).

A number

Bought or imported into your workspace.

Inbound: attach a number

Attaching a number to the inbound Support line agent

Open Attach Number

Open the agent. In a single-prompt agent, expand Attach Number under Call Settings in the editor sidebar. In a multi-prompt agent, open Attach number in the global settings.

Filter by telephony (optional)

Telephony narrows the list to Ringg numbers or to one of your connected provider accounts.

Pick the number

Open Inbound Number (“Select a phone number to receive inbound calls”) and choose a number, for example +91 98765 43210. There is no separate save step.

Agent editor for Support line with Attach Number expanded in the sidebar, Telephony set to Ringg and the Inbound Number list open showing two numbers and Add Number — The Inbound Number list

You see “Number has been attached successfully”.

Attach Number panel with Telephony Ringg and Inbound Number +919876541209 selected — An attached number

Inbound Number lists only numbers that:

are not attached to another agent,
have inbound calling enabled (on by default; contact Ringg to change it), and
match the agent’s channel (phone numbers for voice agents, WhatsApp numbers for WhatsApp agents).

If the list is empty, it shows “Buy numbers to attach”. The last option, Add Number, opens the Numbers page. One agent has one inbound number, and one number serves one agent; the Used By column on the Numbers page shows which. Picking a different number replaces the old one, which stays in your workspace with no agent. Attaching takes the number out of its number pool, and an attached number can’t join one; attaching fails while a campaign is scheduled or running on that pool. Attach Number appears on inbound and WhatsApp single-prompt agents and on every multi-prompt agent. An outbound agent’s Inbound Calling switch changes its type to outbound-inbound but does not add an Attach Number panel; to answer calls on a number, use an inbound agent.

Detach a number

In the agent editor, clear the Inbound Number field. You see “Number has been detached successfully”.
Or on the Numbers page, click Detach Number in the Used By column and confirm Detach.

The number stays in your workspace and joins your Default pool. Detaching fails with “This workspace has no default number pool yet. Please create one.” when there is no Default pool, and while a campaign is scheduled or running on the Default pool.

Provider-side routing

For a number on your own telephony account, the provider must route its calls to Ringg:

Plivo, Twilio and Vobiz: Ringg links the number to its app in your provider account when you attach it. Plivo and Twilio numbers are unlinked again when you detach them.
VoiceLink: Ringg routes the number when you import or buy it.
Exotel: attach the number to the Ringg Inbound applet in Exotel yourself (Exotel).
Other providers: set the routing in the provider’s console. Ozonetel’s URLs are on its guide; for the rest, contact Ringg.

Ringg-provided numbers need no setup.

Verify it worked

Call the number from your phone.

The agent answers, and the call appears at the top of Logs with call type Inbound. Any Event Subscription you set up fires for it.

Outbound: choose the caller ID

How you call	Where you pick the caller ID
Test call from the agent editor	Choose a number (“The number assistant will call from.”). It lists Test numbers, Your numbers, and In use numbers (attached to an agent, shown but disabled).
Campaign	The Select number card: Individual numbers (pick one or more; each shows its provider and a Spam chip if flagged) or Number pool to rotate across a pool. Test numbers are not listed.
API call	`from_number_id`, `from_number` or `number_pool_id` (below).

Caller ID with the API

You need an API key, the agent’s ID (Find an agent’s ID) and a caller number from your workspace (Buy or import a number). Initiate Individual Call takes one of:

string | string[]

A workspace number ID (the ID column, or id from Get Workspace Numbers), or an array of IDs.

string | string[]

A caller number with country code, for example +919876500001, or an array of numbers.

Initiate Individual Call (Number Pool) also accepts number_pool_id (Copy pool ID on the pool list). Send at least one of the three; with a pool, the pool is used and the other field is ignored. When no pool is sent, default outbound numbers set on the agent version take precedence over from_number_id and from_number.

curl -X POST "https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual" \
  -H "X-API-KEY: $RINGG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Priya Sharma",
    "mobile_number": "+919876543210",
    "agent_id": "b1972188-038e-4605-916c-3926e9d7bde4",
    "from_number_id": "5d7f9a2b-1c3e-4f6a-8b9c-0d1e2f3a4b5c"
  }'

const res = await fetch("https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual", {
  method: "POST",
  headers: { "X-API-KEY": process.env.RINGG_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Priya Sharma",
    mobile_number: "+919876543210",
    agent_id: "b1972188-038e-4605-916c-3926e9d7bde4",
    from_number_id: "5d7f9a2b-1c3e-4f6a-8b9c-0d1e2f3a4b5c",
  }),
});
console.log(await res.json());

import os

import requests

res = requests.post(
    "https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual",
    headers={"X-API-KEY": os.environ["RINGG_API_KEY"]},
    json={
        "name": "Priya Sharma",
        "mobile_number": "+919876543210",
        "agent_id": "b1972188-038e-4605-916c-3926e9d7bde4",
        "from_number_id": "5d7f9a2b-1c3e-4f6a-8b9c-0d1e2f3a4b5c",
    },
)
print(res.json())

For campaigns, Start Campaign takes from_numbers (an array of number IDs, or numbers written exactly as listed in your workspace; each retry dials from the next one) and Start Campaign (Number Pool) takes number_pool_id.

Troubleshooting

My inbound number doesn't reach the agent

Check these in order:

The number is attached. On the Numbers page, the Used By column should show your agent. If it shows another agent, detach it there and attach it to the right one.
The agent takes inbound calls. An outbound agent has no Attach Number panel (which agents do).
The provider routes the number to Ringg. For your own telephony, finish the provider-side routing.
Look in Logs. If the call appears in Logs, it reached Ringg and the agent’s settings are the next place to look. If it doesn’t, the call never reached Ringg; check the number with your provider.

My number isn't in the Inbound Number list

Check that Telephony is set to the account the number belongs to, and that the number meets the three conditions above.

The test call says to use the IN or US test number

Test numbers are region-bound. The Indian test number calls Indian numbers only; the US test number calls numbers outside India. Click Switch or pick one of your own numbers. See Test numbers.

The API returns an error about the caller number

Send from_number_id or from_number, not both. Sending neither returns 400 unless the agent version has default outbound numbers. On Initiate Individual Call (Number Pool), both together or none of the three returns 422.

Build agents

Inventory

Deploy

Monitor

Manage account

Ringg Labs

Inbound agent number

Before you start

An agent

A number

Inbound: attach a number

Detach a number

Provider-side routing

Verify it worked

Outbound: choose the caller ID

Caller ID with the API

Troubleshooting

Next steps

Run a campaign

Read call logs

​Before you start

An agent

A number

​Inbound: attach a number

​Detach a number

​Provider-side routing

​Verify it worked

​Outbound: choose the caller ID

​Caller ID with the API

​Troubleshooting

​Next steps

Run a campaign

Read call logs

Before you start

Inbound: attach a number

Detach a number

Provider-side routing

Verify it worked

Outbound: choose the caller ID

Caller ID with the API

Troubleshooting

Next steps