Skip to content
Linq
Getting Started

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.

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.

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.

  • 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 408 or a 5xx, 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.

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 5xx works like 503.
  • 480 ends the call as no answer and 600 as busy, without trying your backup; 487 ends it as canceled.
  • Any other 4xx or 6xx, such as 404 or 488, ends the call as call_voice.failed / failed, with no failover.
  • Don’t challenge Linq’s INVITE with 401 or 407: 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.

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.

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.

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 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.

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_answer and call_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}.

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-000000000000
  • 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 401 or 407.
  • 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: 486 when it’s full, or a backup URI and 503.
  • Call events: subscribe, and dedupe them on event_id.
  • A backup URI, and 503 from 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-Id of each call with your call.
  • Reconciliation: list your calls and match them to your own logs by id.