API Reference
API Overview
Phone Numbers
Phone Numbers represent the phone numbers assigned to your partner account.
Use the list phone numbers endpoint to discover which phone numbers are available for sending messages.
When creating chats, listing chats, or sending a voice memo, use one of your assigned phone numbers
in the from field.
Ineligible numbers. A number can temporarily lose the ability to deliver messages.
While it is in that state, requests that would produce new activity on it — sending a
message, creating a chat, reacting, typing, group actions — are rejected with 403
(error code 2027) before anything is created. Reads keep working, so your existing
chats, messages, and history stay available. Omit from on POST /v3/messages and we
pick an eligible number for you, skipping ineligible ones; if none of your assigned
numbers are eligible, you get 409 (no from number was ever chosen, so there’s no
specific number to blame with a 403).
Published vs unpublished. A published number is available for your account to use.
Only published numbers appear in GET /v3/phone_numbers.
Unpublished numbers allow GET requests. POST, PUT, PATCH, and DELETE requests that
change a chat return 403 with error code 2033 (Phone number is unpublished).
A number’s existing data is preserved when its status changes to unpublished. Unpublished status alone does not block reads, blocked-handle management, or deletion of your data. Existing authorization, retention, and endpoint rules still apply.
Webhook events are suppressed for affected numbers when their publication status is known to be unpublished.
List phone numbers
Sip Profiles
SIP configuration
Your Linq representative provides the signaling and media IP ranges and ports to allow through your firewall during onboarding.
Set primary_uri to your endpoint as scheme + host — sips: for TLS or
sip: for UDP, with no user part (we add it). Each call arrives at your
endpoint as:
sip:<called-number>@<your-host>
so you can route on the dialed number. The caller’s number is in the
From header in E.164.
Create a SIP profile
List SIP profiles
Get a SIP profile by ID
Update a SIP profile
Delete a SIP profile
Assign or clear a phone number's SIP profile
Call Voice
Read the carrier (BYOC) voice calls received on your phone numbers. Each
record is the durable form of the call_voice.* webhooks for that call and
shares the same id, so you can look a call up by the id a webhook
delivered. See SIP Profiles for routing inbound calls to your endpoint.
List carrier (BYOC) voice calls for a phone number
Get a carrier (BYOC) voice call by ID
Webhook Events
Webhook Subscriptions allow you to receive real-time notifications when events occur on your account.
Configure webhook endpoints to receive call_voice.* events as calls progress.
Failed deliveries (5xx, 429, network errors) are retried with exponential backoff for up to 30 minutes. Each event includes a unique ID for deduplication.
Webhook Headers
All webhook requests include two sets of headers. If you have an existing integration
using the X-Webhook-* headers, nothing changes — those headers are still sent on
every delivery and work exactly as before. The new webhook-* headers follow the
Standard Webhooks specification.
You can safely ignore them if your current verification code works and you don’t want to use this convention.
Standard Webhooks Headers (Recommended)
Used by our SDK and any Standard Webhooks library.
| Header | Description |
|---|---|
webhook-id | Unique event identifier (use as idempotency key) |
webhook-timestamp | Unix timestamp (seconds) when the webhook was sent |
webhook-signature | Standard Webhooks signature (v1,{base64} format) |
Legacy Headers (Deprecated)
Still sent on every delivery for backwards compatibility. Existing verification code using these headers continues to work — no changes required.
| Header | Description |
|---|---|
X-Webhook-Event | (deprecated) Event type (e.g., call_voice.ringing) |
X-Webhook-Subscription-ID | (deprecated) Webhook subscription ID |
X-Webhook-Timestamp | (deprecated) Unix timestamp (seconds) |
X-Webhook-Signature | (deprecated) HMAC-SHA256 signature (hex-encoded) |
Signing Secrets
Signing secrets use the Standard Webhooks format: a whsec_ prefix followed
by base64-encoded random bytes (e.g., whsec_bGlucS1leGFtcGxlLXNlY3JldC1kby1ub3QtdXNlLTMyYg==).
Strip the whsec_ prefix and base64-decode the remainder to get the raw key bytes.
Verifying Webhook Signatures
Webhooks are signed following the Standard Webhooks specification. You can use any Standard Webhooks library to verify signatures, or implement verification manually:
Signed content: {webhook-id}.{webhook-timestamp}.{body}
Verification Steps:
- Extract the
webhook-id,webhook-timestamp, andwebhook-signatureheaders - Reject if the timestamp is more than 5 minutes from the current time, in either direction (replay protection)
- Get the raw request body bytes (do not parse and re-serialize)
- Construct signed content:
"{webhook-id}.{webhook-timestamp}.{body}" - Strip the
whsec_prefix from your secret and base64-decode to get key bytes - Compute HMAC-SHA256 using the key bytes over the signed content
- Base64-encode the result and compare with the value after
v1,inwebhook-signature - Use constant-time comparison to prevent timing attacks
Example (Python):
import base64, hashlib, hmac, time
TOLERANCE_SECONDS = 5 * 60
def verify_webhook(secret: str, body: bytes, headers) -> bool:
# body: the raw request body bytes, before any JSON parsing (Flask: request.get_data())
msg_id = headers.get('webhook-id')
timestamp = headers.get('webhook-timestamp')
signature = headers.get('webhook-signature')
if not (msg_id and timestamp and signature):
return False
try:
sent_at = int(timestamp)
except ValueError:
return False
if abs(time.time() - sent_at) > TOLERANCE_SECONDS:
return False # stale or from the future: possible replay
key = base64.b64decode(secret.removeprefix('whsec_'))
signed_content = f'{msg_id}.{timestamp}.'.encode() + body
expected = base64.b64encode(
hmac.new(key, signed_content, hashlib.sha256).digest()
)
for sig in signature.split(' '):
version, _, value = sig.partition(',')
if version == 'v1' and hmac.compare_digest(expected, value.encode()):
return True
return False
Example (Node.js):
const crypto = require('crypto');
const TOLERANCE_SECONDS = 5 * 60;
// rawBody: the request body exactly as received, as a Buffer or string
// (Express: express.raw({ type: 'application/json' })), not parsed JSON.
function verifyWebhook(secret, rawBody, headers) {
const msgId = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signature = headers['webhook-signature'];
if (!msgId || !timestamp || !signature) return false;
if (!/^\d+$/.test(timestamp)) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) {
return false; // stale or from the future: possible replay
}
const secretStr = secret.startsWith('whsec_') ? secret.slice(6) : secret;
const key = Buffer.from(secretStr, 'base64');
const expected = crypto
.createHmac('sha256', key)
.update(`${msgId}.${timestamp}.`)
.update(rawBody)
.digest();
return signature.split(' ').some((sig) => {
if (!sig.startsWith('v1,')) return false;
const received = Buffer.from(sig.slice(3), 'base64');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
Security Best Practices:
- Reject webhooks whose timestamp is more than 5 minutes from the current time, to prevent replay attacks
- Always use constant-time comparison for signature verification
- Store your signing secret securely (e.g., environment variable, secrets manager)
- Return a 2xx status code quickly, then process the webhook asynchronously
List available webhook event types
Webhook Subscriptions
Webhook Subscriptions allow you to receive real-time notifications when events occur on your account.
Configure webhook endpoints to receive call_voice.* events as calls progress.
Failed deliveries (5xx, 429, network errors) are retried with exponential backoff for up to 30 minutes. Each event includes a unique ID for deduplication.
Webhook Headers
All webhook requests include two sets of headers. If you have an existing integration
using the X-Webhook-* headers, nothing changes — those headers are still sent on
every delivery and work exactly as before. The new webhook-* headers follow the
Standard Webhooks specification.
You can safely ignore them if your current verification code works and you don’t want to use this convention.
Standard Webhooks Headers (Recommended)
Used by our SDK and any Standard Webhooks library.
| Header | Description |
|---|---|
webhook-id | Unique event identifier (use as idempotency key) |
webhook-timestamp | Unix timestamp (seconds) when the webhook was sent |
webhook-signature | Standard Webhooks signature (v1,{base64} format) |
Legacy Headers (Deprecated)
Still sent on every delivery for backwards compatibility. Existing verification code using these headers continues to work — no changes required.
| Header | Description |
|---|---|
X-Webhook-Event | (deprecated) Event type (e.g., call_voice.ringing) |
X-Webhook-Subscription-ID | (deprecated) Webhook subscription ID |
X-Webhook-Timestamp | (deprecated) Unix timestamp (seconds) |
X-Webhook-Signature | (deprecated) HMAC-SHA256 signature (hex-encoded) |
Signing Secrets
Signing secrets use the Standard Webhooks format: a whsec_ prefix followed
by base64-encoded random bytes (e.g., whsec_bGlucS1leGFtcGxlLXNlY3JldC1kby1ub3QtdXNlLTMyYg==).
Strip the whsec_ prefix and base64-decode the remainder to get the raw key bytes.
Verifying Webhook Signatures
Webhooks are signed following the Standard Webhooks specification. You can use any Standard Webhooks library to verify signatures, or implement verification manually:
Signed content: {webhook-id}.{webhook-timestamp}.{body}
Verification Steps:
- Extract the
webhook-id,webhook-timestamp, andwebhook-signatureheaders - Reject if the timestamp is more than 5 minutes from the current time, in either direction (replay protection)
- Get the raw request body bytes (do not parse and re-serialize)
- Construct signed content:
"{webhook-id}.{webhook-timestamp}.{body}" - Strip the
whsec_prefix from your secret and base64-decode to get key bytes - Compute HMAC-SHA256 using the key bytes over the signed content
- Base64-encode the result and compare with the value after
v1,inwebhook-signature - Use constant-time comparison to prevent timing attacks
Example (Python):
import base64, hashlib, hmac, time
TOLERANCE_SECONDS = 5 * 60
def verify_webhook(secret: str, body: bytes, headers) -> bool:
# body: the raw request body bytes, before any JSON parsing (Flask: request.get_data())
msg_id = headers.get('webhook-id')
timestamp = headers.get('webhook-timestamp')
signature = headers.get('webhook-signature')
if not (msg_id and timestamp and signature):
return False
try:
sent_at = int(timestamp)
except ValueError:
return False
if abs(time.time() - sent_at) > TOLERANCE_SECONDS:
return False # stale or from the future: possible replay
key = base64.b64decode(secret.removeprefix('whsec_'))
signed_content = f'{msg_id}.{timestamp}.'.encode() + body
expected = base64.b64encode(
hmac.new(key, signed_content, hashlib.sha256).digest()
)
for sig in signature.split(' '):
version, _, value = sig.partition(',')
if version == 'v1' and hmac.compare_digest(expected, value.encode()):
return True
return False
Example (Node.js):
const crypto = require('crypto');
const TOLERANCE_SECONDS = 5 * 60;
// rawBody: the request body exactly as received, as a Buffer or string
// (Express: express.raw({ type: 'application/json' })), not parsed JSON.
function verifyWebhook(secret, rawBody, headers) {
const msgId = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signature = headers['webhook-signature'];
if (!msgId || !timestamp || !signature) return false;
if (!/^\d+$/.test(timestamp)) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) {
return false; // stale or from the future: possible replay
}
const secretStr = secret.startsWith('whsec_') ? secret.slice(6) : secret;
const key = Buffer.from(secretStr, 'base64');
const expected = crypto
.createHmac('sha256', key)
.update(`${msgId}.${timestamp}.`)
.update(rawBody)
.digest();
return signature.split(' ').some((sig) => {
if (!sig.startsWith('v1,')) return false;
const received = Buffer.from(sig.slice(3), 'base64');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
Security Best Practices:
- Reject webhooks whose timestamp is more than 5 minutes from the current time, to prevent replay attacks
- Always use constant-time comparison for signature verification
- Store your signing secret securely (e.g., environment variable, secrets manager)
- Return a 2xx status code quickly, then process the webhook asynchronously