Give your agent a phone number

About 10 minutesNo code neededUpdated July 2026

After this guide, people can call a real phone number and your agent will answer — and your agent can dial out, too. You bring a number from your carrier and connect it in two short steps, all from the dashboard.

Before you start, make sure you have:

A voice agent — if you don't have one yet, follow Create your first agent (5 minutes)

A phone number purchased from a carrier — Telnyx or Twilio — with its SIP credentials handy

An admin role in your Qalyb organization — phone setup is admin-only

Note:

Qalyb doesn't sell phone numbers — there's no search-and-buy flow in the product. You bring your own number from a carrier and connect it here. Your carrier's dashboard is where you buy the number and find the SIP credentials.

Admin-only, and plan-gated:

every create, edit, and delete action on the phone setup page needs an admin role — other members can view the lists but see no buttons. Adding a number also needs a plan with the voice (SIP) channel enabled; the number counts against your channel limit, and assigning an agent counts against your deployed-agent limit. On the Free plan that limit is 0, so Free can't take live phone calls. (Adding a trunk on its own isn't gated — only the number is.)

You set up two things, in order:

A SIP trunk — tells Qalyb which carrier your number lives with and how to talk to it. Think of it as the cable between Qalyb and your carrier.
A phone number — your actual number, pointed at the agent that should answer it. This is what makes incoming calls reach your agent.

Qalyb handles all the call routing behind the scenes — there's nothing else to wire up.

First, connect your carrier

Open phone setup

In the dashboard, click Deploy in the left menu, then Connect a channel. Pick Phone number under the Voice group and click Open phone setup. The page has two tabs: Phone Numbers and SIP Trunks.

Screenshot: the phone setup page with the Phone Numbers tab selected, showing a table of numbers with direction, assigned agent, and SIP trunk columns — Phone setup. Each number row maps a phone number to an agent, trunk, and direction.

Add a trunk and name it

Switch to the SIP Trunks tab and click Add Trunk. Give it a name you'll recognize, like Telnyx Main or Twilio Outbound.

Choose your carrier

Pick Twilio, Telnyx, or Custom. The choice auto-fills the SIP server address for you (Telnyx → sip.telnyx.com, Twilio → {account}.pstn.twilio.com), and an inline note tells you exactly where to find the credentials in that carrier's dashboard.

Pick a direction and enter the details

Choose Inbound (receive calls), Outbound (place calls), or Both. Then add your purchased phone number(s) (comma-separated), the SIP server address, username, and password. For inbound, you can optionally add Allowed Inbound Addresses — a safety list of your carrier's network addresses.

Screenshot: the Add SIP Trunk modal with a provider dropdown, an inline carrier setup note, a direction selector, and SIP server, username, and password fields — The Add Trunk modal. Picking a carrier fills in the SIP address and shows a credential hint for that carrier.

Create it

Click Create Trunk. Qalyb provisions its side of the connection automatically — when the status badge shows a green check, the trunk is ready.

Telnyx fills itself in:

choosing Telnyx configures the extras for you: the outbound username is passed as an X-Telnyx-Username header, and if you leave the inbound allowlist empty it defaults to Telnyx's signaling ranges 64.16.0.0/16 and 185.246.0.0/16.

Then, point your number at your agent

Add the number in international format

On the Phone Numbers tab, click Add Number and type the number in full international (E.164) format — the + and country code included, like +97180012345 (UAE) or +966512345678 (Saudi Arabia). No spaces, dashes, or leading zeros.

Choose the trunk

Select the SIP trunk you created above — or leave it as No trunk if you're only staging the record for later.

Assign the agent

Pick the voice agent that should handle the calls. A number with no agent can't answer incoming calls — assigning the agent is what switches it on.

Pick a direction and save

Choose Inbound, Outbound, or Both, then click Add Number. For inbound (or both) with an agent assigned, Qalyb wires up the incoming-call routing automatically.

Screenshot: the Add Phone Number modal with an E.164 number field, a SIP Trunk select, an Assign to Agent select, and a Direction selector — The Add Number modal. A direction plus an assigned agent is what enables incoming calls.

Call it yourself

Dial the number from your own phone — your agent should pick up.

You're live:

every call now appears in your logs with its transcript and recording.

When customers call

Once a number is inbound-capable with an assigned agent, incoming calls just work: the agent answers, the call is recorded, and the transcript is saved when it ends. You'll find each call in Logs with its transcript and recording — and, on Pro and above, a post-call report with sentiment and success scoring.

A number with no agent will not answer:

incoming calls are routed by looking up the dialed number and handing the call to its assigned agent — no agent, no answer. Inbound numbers are also unique across Qalyb: only one organization can own a number for incoming calls (the same number may exist elsewhere as outbound-only).

Note:

post-call analysis is a Pro+ feature. On plans without it, calls still record and transcribe normally — the report is simply skipped and reads as not_available.

Calling out

Outbound dialing needs an outbound-enabled trunk plus an active number whose direction is Outbound or Both. There are three ways to place a call:

Playground — the fastest way to test. Select the agent, choose the Voice channel, switch the direction to Outbound, and type the destination number. The screen shows which number the call will come from before you dial, and the status updates live from ringing to completed.
Campaigns — dial a whole contact list at scale. Create a campaign, pick an outbound number, and set a default country code (GCC countries are preferred) so local numbers in your list are normalized automatically.
API — place calls programmatically; see Place calls via API and the developer section below.

Screenshot: the Playground voice tab in Outbound direction showing the destination phone number input and the resolved From number — Outbound from the Playground. The From number is shown before you dial; status updates live from ringing to completed.

Common outbound errors:

outbound needs both an active number and an outbound trunk. Missing a number returns No outbound phone number configured; missing a trunk returns No outbound SIP trunk configured. Some error messages still mention the old Settings > Telephony location — that's now the phone setup page. If the agent never joins the call, it's marked agent_timeout.

If something looks off

The Status badge on a trunk (green check vs. amber alert) tells you whether Qalyb's side of the carrier connection was fully set up. If it's amber, the trunk was saved but the connection didn't finish — click Reconnect on the SIP Trunks tab to retry. The sync only touches records your organization owns; it never adopts anything else.

Changing a carrier address or credentials:

editing a trunk updates the saved record only — it does not re-push address or transport changes to the calling infrastructure. If your carrier address or credentials change, delete the trunk and recreate it. The password field is write-only: an existing password shows as ••••••••, and leaving it blank keeps the current value.

For developers

Everything on this page is also available over the API. All endpoints require the channels:read or channels:write permission.

Endpoint	Purpose
`GET /sip/trunks`	List SIP trunks.
`POST /sip/trunks`	Create a trunk and connect it to your carrier for inbound/outbound calls.
`PATCH /sip/trunks/:id`	Update the trunk record (does not re-push carrier connection changes).
`DELETE /sip/trunks/:id`	Delete the trunk and its carrier connection.
`GET /sip/phone-numbers`	List phone numbers.
`POST /sip/phone-numbers`	Create a number and (for inbound/both with an agent) its call routing.
`PATCH /phone-numbers/:id`	Assign an agent to an existing number.
`POST /sip/sync`	Reconcile this org's trunks and call routing with your carrier.

Create a trunk

curl · bash

curl -X POST https://api.qalyb.ai/sip/trunks \
  -H "Authorization: Bearer sk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Telnyx Main",
    "provider": "telnyx",
    "inboundEnabled": true,
    "inboundNumbers": ["+97180012345"],
    "inboundAllowedAddresses": ["64.16.0.0/16", "185.246.0.0/16"],
    "outboundEnabled": true,
    "outboundAddress": "sip.telnyx.com",
    "outboundUsername": "qalyb_acme",
    "outboundPassword": "••••••••"
  }'

Map a number to an agent

curl · bash

curl -X POST https://api.qalyb.ai/sip/phone-numbers \
  -H "Authorization: Bearer sk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+97180012345",
    "sipTrunkId": "trk_5a1b",
    "agentId": "agt_abc123",
    "direction": "both"
  }'

List your numbers

curl · bash

curl https://api.qalyb.ai/sip/phone-numbers \
  -H "Authorization: Bearer sk-live-..."

Place an outbound call

curl · bash

curl -X POST https://api.qalyb.ai/calls/outbound \
  -H "Authorization: Bearer sk-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_abc123",
    "toNumber": "+97155123456",
    "fromNumberId": "pn_9f2c"
  }'

If you omit fromNumberId, Qalyb resolves the from-number by preference: the agent's assigned active number first, then any active number in your org. Call status moves through ringing → in_progress → completed / no_answer / failed, and the Playground polls it every couple of seconds.

How routing works:

Creating a trunk connects Qalyb to your carrier for inbound and/or outbound calls, and adding an inbound-capable number with an assigned agent sets up the call routing automatically — there's no separate routing screen. Incoming calls reach the agent assigned to the dialed number, and recordings are saved with download URLs signed on read.

Was this guide helpful?

← Previous

Voice calls on your site