API Reference

A Chat is a conversation thread with one or more participants.

To begin a chat, you must create a Chat with at least one recipient handle. Including multiple handles creates a group chat.

When creating a chat, the from field specifies which of your authorized phone numbers the message originates from. Your authentication token grants access to one or more phone numbers, but the from field determines the actual sender.

Handle Format:

• Handles can be phone numbers or email addresses
• Phone numbers MUST be in E.164 format (starting with +)
• Phone format: +[country code][subscriber number]
• Example phone: +12223334444 (US), +442071234567 (UK), +81312345678 (Japan)
• Example email: [email protected]
• No spaces, dashes, or parentheses in phone numbers

A Chat is a conversation thread with one or more participants.

To begin a chat, you must create a Chat with at least one recipient handle. Including multiple handles creates a group chat.

When creating a chat, the from field specifies which of your authorized phone numbers the message originates from. Your authentication token grants access to one or more phone numbers, but the from field determines the actual sender.

Handle Format:

• Handles can be phone numbers or email addresses
• Phone numbers MUST be in E.164 format (starting with +)
• Phone format: +[country code][subscriber number]
• Example phone: +12223334444 (US), +442071234567 (UK), +81312345678 (Japan)
• Example email: [email protected]
• No spaces, dashes, or parentheses in phone numbers

Messages are individual communications within a chat thread.

Messages can include text, media attachments, rich link previews, special effects (like confetti or fireworks), and reactions. All messages are associated with a specific chat and sent from a phone number you own.

Messages support delivery status tracking, read receipts, and editing capabilities.

Rich Link Previews

Send a URL as a link part to deliver it with a rich preview card showing the page’s title, description, and image (when available). A link part must be the only part in the message — it cannot be combined with text or media parts. To send a URL without a preview card, include it in a text part instead.

Limitations:

• A link part cannot be combined with other parts in the same message.
• Maximum URL length: 2,048 characters.

Messages are individual communications within a chat thread.

Messages can include text, media attachments, rich link previews, special effects (like confetti or fireworks), and reactions. All messages are associated with a specific chat and sent from a phone number you own.

Messages support delivery status tracking, read receipts, and editing capabilities.

Rich Link Previews

Send a URL as a link part to deliver it with a rich preview card showing the page’s title, description, and image (when available). A link part must be the only part in the message — it cannot be combined with text or media parts. To send a URL without a preview card, include it in a text part instead.

Limitations:

• A link part cannot be combined with other parts in the same message.
• Maximum URL length: 2,048 characters.

Send files (images, videos, documents, audio) with messages by providing a URL in a media part. Pre-uploading via POST /v3/attachments is optional and only needed for specific optimization scenarios.

Sending Media via URL (up to 10MB)

Provide a publicly accessible HTTPS URL with a supported media type in the url field of a media part.

{
  "parts": [
    { "type": "media", "url": "https://your-cdn.com/images/photo.jpg" }
  ]
}

This works with any URL you already host — no pre-upload step required. Maximum file size: 10MB.

Pre-Upload (required for files over 10MB)

Use POST /v3/attachments when you want to:

• Send files larger than 10MB (up to 100MB) — URL-based downloads are limited to 10MB
• Send the same file to many recipients — upload once, reuse the attachment_id without re-downloading each time
• Reduce message send latency — the file is already stored, so sending is faster

How it works:

1. POST /v3/attachments with file metadata → returns a presigned upload_url (valid for 15 minutes) and a permanent attachment_id
2. PUT the raw file bytes to the upload_url with the required_headers (no JSON or multipart — just the binary content)
3. Reference the attachment_id in your media part when sending messages (no expiration)

Key difference: When you provide an external url, we download and process the file on every send. When you use a pre-uploaded attachment_id, the file is already stored — so repeated sends skip the download step entirely.

Domain Allowlisting

Attachment URLs in API responses are served from cdn.linqapp.com. This includes:

• url fields in media and voice memo message parts
• download_url fields in attachment and upload response objects

If your application enforces domain allowlists (e.g., for SSRF protection), add:

cdn.linqapp.com

Supported File Types

• Images: JPEG, PNG, GIF, HEIC, HEIF, TIFF, BMP
• Videos: MP4, MOV, M4V
• Audio: M4A, AAC, MP3, WAV, AIFF, CAF, AMR
• Documents: PDF, TXT, RTF, CSV, Office formats, ZIP
• Contact & Calendar: VCF, ICS

Audio: Attachment vs Voice Memo

Audio files sent as media parts appear as downloadable file attachments in iMessage. To send audio as an iMessage voice memo bubble (with native inline playback UI), use the dedicated POST /v3/chats/{chatId}/voicememo endpoint instead.

File Size Limits

• URL-based (url field): 10MB maximum
• Pre-upload (attachment_id): 100MB maximum

Security & Ownership

Every attachment is bound to the partner account that created or received it. The API enforces ownership on every operation that touches an attachment — sending, retrieving, deleting.

What this means for you:

• An attachment created under your API key can only be referenced by your API key.
• Submitting another partner’s attachment_id returns 404 Not Found. We do not disclose whether the id exists or belongs to someone else.
• Submitting a CDN URL that resolves to another partner’s attachment is rejected before the send is attempted.
• Ownership enforcement applies uniformly across send, create-chat, voice memo, retrieve, and delete operations.

Every attachment-affecting endpoint requires a valid partner API key. Unauthenticated calls return 401 Unauthorized.

Attachment URL Patterns

Attachment URLs in API responses and webhook payloads use one of two layouts, depending on the attachment’s tier:

Inbound media you receive over webhooks uses the same layout your outbound sends produce, so the URL you store and the URL you build look identical — no special casing in your client.

Ephemeral Attachments (Privacy Tier)

For regulated or sensitive content, opt in to the ephemeral attachments tier by contacting your Linq support contact. You can request it at two scopes:

Behavioral differences vs the persistent default:

When to choose ephemeral:

• Your downstream system processes the file immediately on receipt and does not need to re-read it later.
• You have a compliance requirement that the platform must not retain attachments beyond a short window.
• The content is high-sensitivity (PHI, financial documents, identity verification) and you do not want it sitting behind a long-lived URL.

Important: ephemeral applies in both directions — outbound files you upload and inbound media received by the phone numbers in that scope. Download bytes you need to keep promptly, or fetch a fresh signed URL via the API when needed.

Deleting an Attachment

To permanently remove an attachment you own, use:

DELETE /v3/attachments/{attachmentId}
Authorization: Bearer <your_api_key>

What this does:

1. Verifies the attachment is owned by your account. Returns 404 otherwise.
2. Removes the underlying file from Linq storage.
3. Records an audit entry (timestamp, partner, attachment id).

Response codes:

Effect on message history:

• Messages that referenced the deleted attachment remain visible.
• The message part that pointed at the attachment is preserved with no attachment reference.
• Webhook payloads previously delivered to you retain the original URL string, but downloads from that URL return 404 going forward.

Deletion is irreversible. Once 204 is returned, the bytes are gone — there is no undelete.

Inbound Media Flow

When one of your phone numbers receives a message with media (image, video, audio, document), the platform:

1. Stores the file under your partner account.
2. Records metadata linked to the inbound message.
3. Delivers a webhook whose parts[] array includes a media part with a url pointing at cdn.linqapp.com.
4. If the receiving phone is opted in to ephemeral, the url is a short-TTL signed URL.

You can acknowledge the webhook without fetching the file inline, and lazy-load via GET /v3/attachments/{attachmentId} later. For ephemeral attachments, retrieving via the API always returns a freshly-signed URL.

Data Lifecycle Summary

In transit: TLS 1.2+ everywhere. At rest: AES-256 (server-side encryption).

Compliance Checklist

If you’re integrating Linq under a security or privacy review, here is the short list:

• Allowlist exactly one outbound domain: cdn.linqapp.com.
• Decide whether you need ephemeral attachments (high-sensitivity content) — request enablement through your Linq support contact.
• Implement DELETE /v3/attachments/{attachmentId} calls in your deletion workflow.
• Persist any attachments your application needs long-term — Linq is the authoritative source until you delete, but the ephemeral tier auto-purges after 1 day.
• For audit: every deletion is logged on Linq’s side. Surface a confirmation in your application UI based on the 204 response.
• For end-user “right to delete” requests: enumerate attachment ids and DELETE each. The platform does not provide a partner-wide wipe endpoint — deletion is per-attachment by design.

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.

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.

Webhook Subscriptions allow you to receive real-time notifications when events occur on your account.

Configure webhook endpoints to receive events such as messages sent/received, delivery status changes, reactions, typing indicators, and more.

Failed deliveries (5xx, 429, network errors) are retried up to 10 times over ~25 minutes with exponential backoff. Each event includes a unique ID for deduplication.

Webhook Headers

Each webhook request includes the following headers:

Verifying Webhook Signatures

All webhooks are signed using HMAC-SHA256. You should always verify the signature to ensure the webhook originated from Linq and hasn’t been tampered with.

Signature Construction:

The signature is computed over a concatenation of the timestamp and payload:

{timestamp}.{payload}

Where:

• timestamp is the value from the X-Webhook-Timestamp header
• payload is the raw JSON request body (exact bytes, not re-serialized)

Verification Steps:

1. Extract the X-Webhook-Timestamp and X-Webhook-Signature headers
2. Get the raw request body bytes (do not parse and re-serialize)
3. Concatenate: "{timestamp}.{payload}"
4. Compute HMAC-SHA256 using your signing secret as the key
5. Hex-encode the result and compare with X-Webhook-Signature
6. Use constant-time comparison to prevent timing attacks

Example (Python):

import hmac
import hashlib

def verify_webhook(signing_secret, payload, timestamp, signature):
    message = f"{timestamp}.{payload.decode('utf-8')}"
    expected = hmac.new(
        signing_secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Example (Node.js):

const crypto = require('crypto');

function verifyWebhook(signingSecret, payload, timestamp, signature) {
  const message = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(message)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Security Best Practices:

• Reject webhooks with timestamps older than 5 minutes 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

Webhook Subscriptions allow you to receive real-time notifications when events occur on your account.

Configure webhook endpoints to receive events such as messages sent/received, delivery status changes, reactions, typing indicators, and more.

Failed deliveries (5xx, 429, network errors) are retried up to 10 times over ~25 minutes with exponential backoff. Each event includes a unique ID for deduplication.

Webhook Headers

Each webhook request includes the following headers:

Verifying Webhook Signatures

All webhooks are signed using HMAC-SHA256. You should always verify the signature to ensure the webhook originated from Linq and hasn’t been tampered with.

Signature Construction:

The signature is computed over a concatenation of the timestamp and payload:

{timestamp}.{payload}

Where:

• timestamp is the value from the X-Webhook-Timestamp header
• payload is the raw JSON request body (exact bytes, not re-serialized)

Verification Steps:

1. Extract the X-Webhook-Timestamp and X-Webhook-Signature headers
2. Get the raw request body bytes (do not parse and re-serialize)
3. Concatenate: "{timestamp}.{payload}"
4. Compute HMAC-SHA256 using your signing secret as the key
5. Hex-encode the result and compare with X-Webhook-Signature
6. Use constant-time comparison to prevent timing attacks

Example (Python):

import hmac
import hashlib

def verify_webhook(signing_secret, payload, timestamp, signature):
    message = f"{timestamp}.{payload.decode('utf-8')}"
    expected = hmac.new(
        signing_secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Example (Node.js):

const crypto = require('crypto');

function verifyWebhook(signingSecret, payload, timestamp, signature) {
  const message = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(message)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Security Best Practices:

• Reject webhooks with timestamps older than 5 minutes 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

Check whether a recipient address supports iMessage or RCS before sending a message.

Contact Card lets you set and share your contact information (name and profile photo) with chat participants via iMessage Name and Photo Sharing.

Use POST /v3/contact_card to create or update a card for a phone number. Use PATCH /v3/contact_card to update an existing active card. Use GET /v3/contact_card to retrieve the active card(s) for your partner account.

Sharing behavior: Sharing may not take effect in every chat due to limitations outside our control. We recommend calling the share endpoint once per day, after the first outbound activity.