Connect your SIP endpoint
Every setting for your SIP endpoint and your SIP profile, plus codecs, custom SIP headers, failover, call events and common issues.
This page lists every setting you need to connect a SIP endpoint to your Linq numbers: what to set on your endpoint, what to set at Linq, codecs, custom SIP headers, failover, call events and how to fix common problems. It works for any SIP server or voice-agent platform. For a first call, start with the Quickstart.
Linq does:
- relay the SIP signalling, and stay in that path for the whole call
- send calls over TLS to a
sips:URI or asip:…;transport=tlsURI; TLS covers the signalling, and the audio uses RTP or SRTP as negotiated in SDP - add the custom SIP headers you set on your profile to every INVITE
- place the calls your platform sends from your Linq numbers, with outbound calling (early access)
Linq doesn’t:
- carry the audio: it flows directly between the phone network and your endpoint
- change the SDP, so the codec is negotiated end to end
- send credentials to your endpoint
- set custom SIP headers per call
- put the SIP response code or a failure reason in events or call records
- transfer calls; call transfer isn’t available yet
Encryption
Section titled “Encryption”Use TLS for the SIP signalling between Linq and your endpoint. Either form
works: a sips: URI, or a sip: URI with ;transport=tls, for example
sip:sip.example.com:5061;transport=tls. Linq keeps the ;transport=tls
parameter as you set it.
TLS covers the signalling only. The audio flows directly between the phone network and your endpoint, using RTP or SRTP as negotiated in SDP. Linq forwards the SDP unchanged, so the URI scheme doesn’t decide whether the audio uses SRTP.
A sip: URI with no ;transport= is sent over UDP, without TLS. Use it only if
your platform doesn’t support TLS.
What to enter in your platform
Section titled “What to enter in your platform”Use these values whether you run your own SIP server or use a hosted voice-agent platform. A hosted platform’s console may call this an imported number, bring your own number, or an inbound SIP trunk.
| Setting | Value | Why |
|---|---|---|
| Phone number | If your platform routes on the called number: your Linq number in E.164, including the +, for example +14155550100. |
Linq puts the called number in the Request-URI (below). |
| Allowed source addresses and inbound authentication | IP-based: allow Linq’s signalling addresses (below). Don’t challenge them with 401 or 407. |
Linq doesn’t send credentials, so a challenge fails the call. The addresses are shared by every Linq customer. |
| Transport and port | TLS for a sips: URI or a sip: URI with ;transport=tls (recommended). UDP for a sip: URI with no ;transport=, only if your platform doesn’t support TLS. Use the port in your URI; 5060 if there’s none. |
Linq keeps the URI’s scheme, ;transport= parameter and port. |
TLS certificate (sips: or ;transport=tls) |
A certificate that chains to a public certificate authority and is valid for the host in your URI. TLS 1.2 or later. | Linq checks your certificate against the URI’s host. |
| Address | A public IPv4 address: a hostname with an A record, or an IPv4 literal. Use a hostname with TLS. | Linq looks up A records. IPv6 and private addresses don’t work. |
Request-URI user part (the part before @, including the leading +) |
The called Linq number in E.164. Linq sets it on each call (below). | Route each number to its own agent, and filter out misrouted calls. |
| Codecs | At least one of PCMU, PCMA, G.722, AMR-WB or Opus. Offer G.722, AMR-WB or Opus for HD. | The best codec both sides support is used (below). |
| Media encryption | RTP or SRTP, as negotiated in SDP between the phone network and your endpoint. | Linq forwards the SDP unchanged. See Encryption. |
| Media (RTP) addresses | Accept audio from the phone network’s media addresses (below), not Linq’s. Advertise a public address in your SDP (the part of the INVITE and its answer that describes the audio). | Audio flows directly between the phone network and your endpoint, and Linq doesn’t change the SDP. |
| Hang-up | Linq relays the caller’s BYE to your endpoint. |
Linq stays in the signalling path for the whole call. |
| Registration | None. Linq sends INVITEs to your URI. | Linq doesn’t register, and refuses REGISTER. |
On a hosted platform, then point the number at your agent. Some platforms also need your app to accept the call on their side; check your platform’s inbound-call steps.
Protect your endpoint
Section titled “Protect your endpoint”Linq doesn’t register with your platform and doesn’t send credentials to it. Allow only Linq’s signalling addresses. Those addresses are shared by every Linq customer. Checking the Request-URI user part (your Linq numbers) filters out misrouted calls, but it doesn’t prove a call comes from your Linq account: anyone can create a profile that points at your URI. Don’t let calls that arrive from Linq place outbound calls through your platform.
Values to configure at Linq
Section titled “Values to configure at Linq”When you’d use this: create a profile once per agent address, and update it when your agent moves. Allow about 5 minutes before calls reach the new address; calls in progress aren’t affected.
Create a SIP profile with POST /v3/sip-profiles and change
it with PUT /v3/sip-profiles/{sipProfileId}. An update changes only the
fields you send.
| Field | Example | Notes |
|---|---|---|
name |
my-voice-agent |
Required. Keep it to 64 characters or fewer. |
primary_uri |
sips:sip.example.com:5061 |
Required. The sips: scheme, or sip: with ;transport=tls (or plain sip: for UDP), your host and the port. Don’t include a user part; Linq sets it to the called number on each call. Keep it to 512 characters or fewer. |
backup_uri |
sips:backup.example.com:5061 |
Optional. Same rules. Linq uses it only if the primary fails. |
Your account can have one profile per primary URI. Reuse that profile across
your numbers. The assigned_number_count in the response shows how many numbers
use it. You can’t delete a profile while it’s assigned to a
number. Unassign it first.
See the create and update reference pages for the full request and response. There’s no dashboard screen for SIP profiles yet, so use the API.
The Request-URI user part
Section titled “The Request-URI user part”Don’t include a user part (the part before @) in your profile URI; Linq sets it
to the called number on each call. For a profile URI of sips:sip.example.com:5061,
a call to +14155550100 arrives as INVITE sips:[email protected]:5061.
If your platform routes on its own ID, such as a project or account ID, route on the called number in the Request-URI user part instead.
Custom SIP headers
Section titled “Custom SIP headers”To send your platform extra information with each call, add custom SIP headers
to the profile URI as URI headers: after ?, as name=value, joined with &,
with each value percent-encoded.
sips:sip.example.com:5061?X-Agent=front-desk&X-Language=en- Linq adds these headers to every INVITE it sends to that URI.
- If you set a
backup_uri, add the same headers to it. - Header names must start with
X-. - The headers are fixed for each URI. You can’t set them per call.
- The headers are part of the URI. They count toward its 512 characters, and two primary URIs that differ only in their headers are different URIs, so each can have its own profile.
Header values are stored on your profile, returned by the API, and sent with
every INVITE. Without TLS (a sip: URI with no ;transport=tls) they’re sent unencrypted. Don’t put passwords or API
keys in them.
Linq also adds its own X-Linq-Call-Id header to every INVITE, with the call’s
id (Matching your call to Linq’s record).
Codecs and HD audio
Section titled “Codecs and HD audio”Linq supports PCMU, PCMA, G.722, AMR-WB and Opus. G.722, AMR-WB and Opus are HD (wideband). The best codec that both sides support is used.
A call is HD only when every leg negotiates a wideband codec, so HD is supported
but not guaranteed. If your endpoint and the call share no codec, the
call fails with 488. If your platform uses a wideband codec not on
this list, contact Linq.
Allow Linq’s addresses
Section titled “Allow Linq’s addresses”Allow SIP signalling from Linq’s addresses, and audio from the phone network’s media addresses.
Contact Linq for the current signalling and media addresses.
If these addresses change, we’ll update this page.
Add a backup endpoint (failover)
Section titled “Add a backup endpoint (failover)”Set backup_uri on your profile. Linq tries it once, and only after the primary
fails.
Linq tries your backup when the primary:
- doesn’t reply to the INVITE within 3 seconds
- returns
408or any5xx - doesn’t answer within 30 seconds
Linq doesn’t try your backup when the primary:
- returns busy or declined (
486,600or603) - returns any other
4xx, including480,487,404and488 - challenges the INVITE with
401or407
- Each attempt rings for up to 30 seconds. You can’t change the ring time through the API.
- If the caller hangs up first, the call ends as
call_voice.failedwith statuscanceled. - With no backup, a primary that doesn’t reply within 3 seconds, or doesn’t
answer in time, ends the call as
call_voice.no_answerwith statusno_answer. After a failover, the outcome is the backup’s. - If your endpoint challenges the INVITE with
401or407, the call ends ascall_voice.failedwith statusfailed. - A backup whose host is private or doesn’t resolve is skipped, so there’s no failover.
To remove the backup, set backup_uri to an empty string:
curl -X PUT https://api.linqapp.com/api/partner/v3/sip-profiles/{sipProfileId} \ -H "Authorization: Bearer $LINQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "backup_uri": "" }'Assign numbers
Section titled “Assign numbers”When you’d use this: assign a profile when you bring a number into voice; clear it to stop sending the number’s calls to your agent.
Assign the profile to each number whose calls it should take. Put the number in the path in E.164.
curl -X PUT https://api.linqapp.com/api/partner/v3/phone-numbers/{phoneNumber}/sip-profile \ -H "Authorization: Bearer $LINQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sip_profile_id": "sip_8a3f9c2b1d4e4f5a9b8c7d6e5f4a3b2c" }'A 200 response whose sip_profile_id is your profile’s id confirms the
assignment. Keep a record of which profile each number has: the API doesn’t
return a number’s profile, and GET /v3/sip-profiles/{sipProfileId} shows
only how many numbers use a profile (assigned_number_count). Don’t send the
assign request again just to check it: it replaces the number’s current profile
with the one you send.
Assigning a SIP profile takes precedence over the number’s call forwarding (its
forwarding_number), without clearing it.
Allow about 5 minutes after you assign, move or clear a number’s profile before test calls reach the new endpoint. Calls in progress keep going where they started.
To clear a number’s assignment, send null:
curl -X PUT https://api.linqapp.com/api/partner/v3/phone-numbers/{phoneNumber}/sip-profile \ -H "Authorization: Bearer $LINQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sip_profile_id": null }'Call events (webhooks)
Section titled “Call events (webhooks)”When you’d use this: subscribe once, so your own systems hear about each inbound call as it arrives, rings, is answered and ends.
Subscribe with POST /v3/webhook-subscriptions and an
HTTPS URL. You don’t need an extra permission for call events.
curl -X POST https://api.linqapp.com/api/partner/v3/webhook-subscriptions \ -H "Authorization: Bearer $LINQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "target_url": "https://webhooks.example.com/linq/voice?version=2026-02-03", "subscribed_events": [ "call_voice.initiated", "call_voice.ringing", "call_voice.answered", "call_voice.ended", "call_voice.failed", "call_voice.declined", "call_voice.no_answer" ] }'?version=2026-02-03on the URL picks the webhook version. A new subscription without it gets the latest version, which is2026-02-03.- Each URL can have only one subscription. If yours already has one, update it
with
PUT /v3/webhook-subscriptions/{subscriptionId}and send the full list: your existing events plus the call events. The update replaces the list. - Call events use the same signatures and retries as message events. See Verifying signatures with an SDK.
Linq emits call_voice.initiated when an inbound call arrives and is being
routed to your endpoint. On an answered call, it is typically followed by
call_voice.ringing (only if your endpoint sends 180 or 183),
call_voice.answered, then call_voice.ended. Each event carries the call’s
id. For each event’s payload, see the
Webhook Events reference.
Delivery is best effort. Events can be dropped, arrive out of order or arrive
twice. Dedupe on event_id, and treat the event that ends the call as its
outcome.
Find a call
Section titled “Find a call”When you’d use this: for call history, to reconcile calls with your own logs, or when you’re missing an event.
List the calls on your number, newest first, with
GET /v3/phone-numbers/{phoneNumber}/call-voice. A page holds 50 calls by default and
up to 100 with limit. To get the next page, pass next_cursor as
cursor.
curl https://api.linqapp.com/api/partner/v3/phone-numbers/{phoneNumber}/call-voice \ -H "Authorization: Bearer $LINQ_API_KEY"Take a call’s id from that list, from its webhooks, or from the
X-Linq-Call-Id header of its INVITE, and fetch the call with
GET /v3/call-voice/{callVoiceId}:
curl https://api.linqapp.com/api/partner/v3/call-voice/{callVoiceId} \ -H "Authorization: Bearer $LINQ_API_KEY"A call record looks like this (trimmed):
{ "id": "550e8400-e29b-41d4-a716-446655440000", "to": "+14155550100", "direction": "inbound", "status": "completed", "started_at": "2026-03-05T12:00:05Z", "ended_at": "2026-03-05T12:05:00Z"}status is completed, busy, no_answer, failed or canceled. It’s
null while the call is in progress. started_at is set on the
record and on call_voice.answered. The event that ends the call carries
ended_at but not started_at, so read the record for both.
Test call checklist
Section titled “Test call checklist”Call your number from a mobile phone for each test. The last column is the
webhook event and the call record’s
status you should see.
| Test | Expected result | Event / status |
|---|---|---|
| A normal call | Your agent answers. The INVITE’s Request-URI user part is the called number. The codec is the one you expect, and audio works in both directions. | call_voice.answered |
| Hang up from the mobile phone | Your endpoint receives the caller’s BYE. |
call_voice.ended / completed |
| Make your primary stop replying (for example, drop Linq’s signalling at its firewall), then call | Your backup rings about 3 seconds later. | The backup’s outcome; for an answered call, call_voice.ended / completed |
Your endpoint returns 486 |
The call ends. Linq doesn’t try your backup. | call_voice.declined / busy |
| Hang up while your endpoint is ringing | Linq cancels the INVITE. | call_voice.failed / canceled |
| Your endpoint shares no codec with the call | Your endpoint returns 488. Linq doesn’t try your backup. |
call_voice.failed / failed |
A passing test doesn’t prove the call was HD. Check the negotiated codec.
Common issues
Section titled “Common issues”No call reaches your endpoint and no webhook arrives
Section titled “No call reaches your endpoint and no webhook arrives”Most likely the call was never routed: when Linq can’t route a call, your
endpoint gets nothing and no event is sent. Webhook delivery is best
effort, though, so confirm first: list the number’s calls and
look for one at the time you called. If there’s a call record, Linq handled the
call and the missing event is a webhook delivery problem; check the record’s
status in Call outcomes and your
webhook subscription. If there’s no record either, the
call most likely wasn’t routed. Check these causes:
- You assigned the number less than 5 minutes ago. Allow about 5 minutes for the assignment to apply, then call again.
- The profile isn’t assigned to the number. Check the
200response from your assign request: itssip_profile_idshould be your profile’sid. The profile’sassigned_number_countshows how many numbers use it. - Your host doesn’t resolve, or resolves to a private or IPv6-only address. Use a hostname with a public A record, or a public IPv4 address.
Your endpoint never sees the INVITE, and you get call_voice.no_answer about 3 seconds later
Section titled “Your endpoint never sees the INVITE, and you get call_voice.no_answer about 3 seconds later”Or your backup rings instead. A firewall drops Linq’s signalling, nothing is listening on your URI’s host and port, or the host points at the wrong server. Allow Linq’s addresses and check the host and port in your profile.
Your endpoint logs a TLS handshake error
Section titled “Your endpoint logs a TLS handshake error”With TLS (sips: or ;transport=tls), your certificate must chain to a public certificate
authority and be valid for the host in your URI. Check the certificate your
endpoint presents on the URI’s port.
call_voice.failed, and your platform logged a 404
Section titled “call_voice.failed, and your platform logged a 404”Your platform doesn’t know the called number. Add the number, including the
+, in your platform. See What to enter in your platform.
call_voice.failed right away, and your endpoint logged a 401 or 407
Section titled “call_voice.failed right away, and your endpoint logged a 401 or 407”Your endpoint challenged Linq’s INVITE. Linq doesn’t send credentials. Turn off the challenge for Linq’s addresses and allow them by IP instead.
The wrong agent answers, or your platform doesn’t recognise the called number
Section titled “The wrong agent answers, or your platform doesn’t recognise the called number”If your profile URI has a user part, Linq replaces it with the called number. Remove the user part from the profile, and route on the called number in the Request-URI user part. See The Request-URI user part.
No audio, or audio in one direction only
Section titled “No audio, or audio in one direction only”Audio from the phone network’s media addresses is blocked, or your SDP advertises a private address. Allow the media addresses and advertise a public address.
call_voice.failed right after your endpoint rejects the call
Section titled “call_voice.failed right after your endpoint rejects the call”Your endpoint rejected the INVITE with a 4xx other than 408, 480, 486 or
487, or with a 5xx when there was no backup to try. A common cause is a
codec mismatch, which returns 488. Offer one of the
supported codecs.
The call drops at exactly 4 hours
Section titled “The call drops at exactly 4 hours”That’s the maximum call length. Linq hangs up both sides, and the call ends as
call_voice.ended with status completed.
Errors and what to do
Section titled “Errors and what to do”API errors during setup
Section titled “API errors during setup”| Code | When | What to do |
|---|---|---|
1001 |
A required field is missing: name or primary_uri. |
Add the field. |
1005 |
A URI has no scheme, a bad host, a port outside 1–65535, or a password. | Use sips: (or sip:), your host and the port, for example sips:sip.example.com:5061. |
2015 |
Another profile on your account already uses this primary URI, or you tried to delete a profile that’s still assigned. | Reuse the existing profile, or unassign the profile first. |
2006 |
The number isn’t yours, or your API key’s environment doesn’t match the number’s. | Use a number on your account and an API key from its environment. |
2019 |
On assign: the number or the profile wasn’t found. | Check the number (E.164) and the profile id. |
2033 |
The number isn’t published, or it can’t be set up for voice in its current state. | Use a published number. If the number is published and you still get 2033, contact Linq. |
3006 |
A temporary failure. The profile usually isn’t assigned. | Retry, then confirm the number’s assignment. Contact Linq if it keeps happening. |
Call outcomes
Section titled “Call outcomes”| Webhook event | Record status |
What happened | What to check |
|---|---|---|---|
call_voice.ended |
completed |
The call was answered, then hung up (or reached the 4-hour limit). | Nothing; this is a normal call. |
call_voice.declined |
busy |
Your endpoint returned 486, 600 or 603. |
Whether your agent was busy or set to reject the call. |
call_voice.no_answer |
no_answer |
Your endpoint returned 480, or didn’t reply within 3 seconds, didn’t answer within the ring time, or returned 408. After a failover, this is the backup’s result. |
Your firewall, that something is listening on the URI’s host and port, and how fast your agent answers. |
call_voice.failed |
canceled |
The caller hung up before you answered, or your endpoint returned 487. |
How fast your agent answers. |
call_voice.failed |
failed |
Your endpoint rejected the call (for example with 488, 401, 407 or 404), returned a 5xx with no backup to try, or the call failed another way. |
Codecs, authentication challenges, and your endpoint’s logs. |
| No event | — | Most likely the call was never routed. Delivery is best effort, so first list the number’s calls: if there’s a record, the event was lost in delivery and the record’s status is the outcome. |
No call reaches your endpoint. |
After a failover, the outcome is the backup’s. Events and records
don’t include the SIP response code or a failure reason. status is the only
outcome field.