How calls work for your agent
The pieces of a call, what Linq decides and what you decide, and the logic to build around calls to your agent.
This page is for a business that runs its own voice agent on its own Linq numbers. It explains how the pieces fit together, which parts of a call Linq handles, and which parts are yours to decide. For the setup steps, start with the Quickstart.
The pieces
Section titled “The pieces”caller ──► your Linq number ──► its SIP profile ──► your agent │ └── Linq keeps a call record and sends call events to your webhook- Your Linq number is the number people call. The same number can also send messages.
- A SIP profile tells Linq where to send the number’s calls: a primary URI and, optionally, a backup URI.
- Your agent is the SIP endpoint, or your voice-agent platform’s SIP address, that answers the call.
- The call record and call events. Linq can send a webhook when a call
rings, when it’s answered and when it ends, and keeps a record of the call. Both
use the same
id.
A number has at most one profile, and one profile can serve many numbers. When you assign, move or clear a number’s profile, or change a profile’s URI, allow about 5 minutes before test calls reach the new endpoint. Calls already in progress keep going where they started.
When you use each request
Section titled “When you use each request”| You want to | Request | When |
|---|---|---|
| Tell Linq where your agent answers | Create a profile: POST /v3/sip-profiles |
Once per agent: one SIP URI per agent. Reuse the profile for every number that agent answers. |
| Bring a number into voice | Assign the profile: PUT /v3/phone-numbers/{phoneNumber}/sip-profile |
Once per number. Allow about 5 minutes before test calls arrive. |
| Send a number to a different agent | Assign that agent’s profile: PUT /v3/phone-numbers/{phoneNumber}/sip-profile |
When you want it. Allow about 5 minutes before calls go to the new agent. |
| Move your agent to a new address | Update the profile’s URI: PUT /v3/sip-profiles/{sipProfileId} |
When your agent moves. Allow about 5 minutes before calls reach the new address. Calls in progress aren’t affected. |
| Stop taking calls on a number | Clear the assignment: assign null |
When you stop. Allow about 5 minutes before Linq stops sending the number’s calls to your agent. |
| See call history, or reconcile with your own logs | List calls: GET /v3/phone-numbers/{phoneNumber}/call-voice, or get one: GET /v3/call-voice/{callVoiceId} |
As often as you need. |
| Update your own systems as calls happen | Subscribe to call events: POST /v3/webhook-subscriptions |
Once. |
Connect your SIP endpoint has the full request for each one.
What happens on a call, and who decides
Section titled “What happens on a call, and who decides”Linq decides
Section titled “Linq decides”- Where the call goes: to the profile assigned to the number that was dialled.
- How long to wait: your endpoint has 3 seconds to reply to the INVITE
(the SIP request that starts the call), then up to 30 seconds to answer with
200. You can’t change the ring time through the API. - One failover: if your primary doesn’t reply, doesn’t answer in time, or
returns
408or a5xx, Linq tries your backup once. - The longest call: 4 hours. Linq then hangs up both sides.
- The outcome: Linq classifies how each call ended; see Call outcomes.
You decide: your answer
Section titled “You decide: your answer”Your endpoint’s reply to the INVITE is how you tell Linq what you want to happen to the call. On a hosted voice-agent platform, the platform sends these replies for you; check which ones it lets you control.
| Your answer | What it means | What happens | Event / status |
|---|---|---|---|
200 OK |
I’ll take the call. | Your agent is on the call. | call_voice.answered, then call_voice.ended / completed |
486 or 603 |
I’m busy, or I won’t take this call. | The call ends. Linq doesn’t try your backup. | call_voice.declined / busy |
503 |
Send it to my backup. | Linq tries your backup once. With no backup, the call ends. | The backup’s outcome; with no backup, call_voice.failed / failed |
No reply in 3 s, no answer in 30 s, or 408 |
My agent didn’t answer in time. | Linq tries your backup once. With no backup, the call ends. | The backup’s outcome; with no backup, call_voice.no_answer / no_answer |
Other replies:
- Any other
5xxworks like503. 480ends the call as no answer and600as busy, without trying your backup;487ends it as canceled.- Any other
4xxor6xx, such as404or488, ends the call ascall_voice.failed/failed, with no failover. - Don’t challenge Linq’s INVITE with
401or407: that fails the call too.
When your agent is full, reply 486, or 503 if you have a backup. With no
backup, 503 ends the call as failed.
Events and call records don’t include the SIP code you returned, so keep it in your own logs.
Logic you’ll build
Section titled “Logic you’ll build”Linq doesn’t screen callers for you: there are no opening hours, per-caller limits or block lists. Every call it can route to your number goes to your agent. Start with the simple default in each section below, and add more when you need it.
Screening before you answer
Section titled “Screening before you answer”Simple default: answer every call to your numbers.
Next step: before you answer, check the Request-URI user part (the part before
@ in the INVITE). Linq sets it to the called number. If it isn’t one of your
numbers, reject the call with a 404.
Anyone can point a SIP profile at your address, so a call from Linq isn’t
necessarily for you. This check filters out misrouted calls, but it doesn’t
prove the call comes from your Linq account; see
Protect your endpoint.
A hosted platform that routes on the called number already does this
check.
When you need more, decide before you answer: opening hours, a limit per
caller number (it can be spoofed or hidden; see
Caller identity), allow or block lists, and what to do with
callers who hide their number. To give the caller a message,
such as your opening hours, answer with 200 and have your agent say it.
486 or 603 turns the call away without one.
How a call ends
Section titled “How a call ends”The caller usually hangs up, and Linq relays the caller’s BYE to your
endpoint. Plan how your agent wraps up a call: for example, a
limit on call length, after which your agent says goodbye. Linq’s 4-hour limit
is a backstop, not a policy. Your voice platform may end
calls sooner. For example, OpenAI’s Live API ends connected calls after 2
hours.
Caller identity
Section titled “Caller identity”Caller ID can be spoofed, and some callers hide their number. Don’t use the
caller’s number to identify or authenticate a caller, and plan for calls with
no usable number. The caller is in the From header and in
each event’s from. Don’t assume a format: normalize the number before you
store or reuse it.
Events
Section titled “Events”You don’t need events to answer calls; they’re for your own records.
- The events that end a call are
call_voice.ended,call_voice.declined,call_voice.no_answerandcall_voice.failed. - Treat the event that ends the call, or the call record, as the call’s outcome.
- Dedupe on
event_id. - Events can arrive late, twice, out of order, or not at all.
- When you’re missing an event or unsure of an outcome, read the call record
with
GET /v3/call-voice/{callVoiceId}.
Matching your call to Linq’s record
Section titled “Matching your call to Linq’s record”Linq adds an X-Linq-Call-Id header to every INVITE it sends to your
endpoint. Its value is the call’s id: the id of the call record and the
data.id in each call event. Save it with your call, then use it to read the
record with GET /v3/call-voice/{callVoiceId} and to match call events
to your call.
X-Linq-Call-Id: 00000000-0000-0000-0000-000000000000Checklist
Section titled “Checklist”Minimum to go live
Section titled “Minimum to go live”- A SIP profile assigned to your number, and a test call your agent answers.
- Your firewall allows Linq’s addresses,
and your endpoint doesn’t challenge Linq’s INVITEs with
401or407. - Your certificate is valid for the host in your URI.
- If your platform routes on the called number, your Linq number is added there.
- A plan for when your agent can’t answer:
486when it’s full, or a backup URI and503.
What you’ll want later
Section titled “What you’ll want later”- Call events: subscribe, and dedupe them on
event_id. - A backup URI,
and
503from your primary when it’s down for maintenance. - Screening: a check of the called number, opening hours, limits per caller number, callers who hide their number.
- A wrap-up plan: a call-length limit, after which your agent says goodbye.
- Store the
X-Linq-Call-Idof each call with your call. - Reconciliation: list your calls and match them to your own logs by
id.
Next steps
Section titled “Next steps”- Quickstart: route your first call.
- Connect your SIP endpoint: every setting, plus call outcomes.
- Webhooks guide