Chats

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.

Ephemeral Messages (Privacy Tier)

For regulated or sensitive conversations, opt in to the ephemeral messages tier by contacting your Linq support contact. When enabled, every message on the covered phone numbers is automatically given a fixed 24-hour retention window — after that window the platform permanently deletes the message from Linq storage. There is no per-message flag; ephemerality is applied automatically based on your configuration.

You can request it at two scopes:

Scope	Effect
Partner-wide	Every outbound and inbound message on every phone number under your account is retained for 24 hours, then deleted.
Per phone number	Only the specified phone numbers have their messages auto-deleted. The rest follow the standard message-retention policy.

Behavioral differences vs the standard default:

Aspect	Standard	Ephemeral
Retention	Retained per the standard message-retention policy	Hard backstop: 24 hours from when the message is created
After expiry	Message stays retrievable	Message is permanently deleted — GET /v3/messages/{messageId} returns 404 and it no longer appears in GET /v3/chats/{chatId}/messages
Content on expiry	N/A	Text, formatting, and attachment references are scrubbed; the message is gone, not blanked out
Cross-partner isolation	Enforced	Enforced

How the 24-hour window works:

• The window is fixed at 24 hours from message creation (created_at) and cannot be configured per message.
• It mirrors the ephemeral attachments 1-day backstop, so a message and any media it carries expire together.
• Expiry is delivery-independent — the clock starts when the message is created, not when it is delivered or read.

What you observe:

• No expiry timestamp is exposed. API responses and webhook payloads do not include the deletion time. If you need it, compute created_at + 24h yourself.
• No deletion webhook is sent. There is no message.deleted event — a message simply stops being retrievable once its window passes.
• Delivery is unaffected. Ephemeral messages send, deliver, and fire the usual message.sent / message.received and status webhooks exactly like standard messages. Only retention changes.

When to choose ephemeral:

• You have a compliance requirement that the platform must not retain message content beyond a short window.
• The conversation is high-sensitivity (PHI, financial, identity verification) and you do not want it sitting in storage long-term.
• Your application is the system of record — you capture what you need from the delivery webhook in real time and do not rely on reading message history back from Linq later.

Important: ephemeral applies in both directions — messages you send and messages received by the phone numbers in that scope. Because Linq can no longer return the message after 24 hours, persist anything you need to keep from the webhook payload at the time it is delivered.

Request a contact’s location, retrieve location for contacts sharing with you, and subscribe to webhooks when someone starts or stops sharing.

Coordinates are returned in GeoJSON format: [longitude, latitude] or [longitude, latitude, altitude] if altitude is available.

Reading location is poll-based

Poll GET /v3/chats/{chatId}/location whenever you need the latest position. There is no webhook that pushes updated coordinates — the location.sharing.started / location.sharing.stopped webhooks fire only when a contact begins or ends sharing, not on each position update. To track a moving contact, poll the GET endpoint.

Freshness

Each feature’s properties.updated_at tells you when that participant’s location was last updated — use it to judge freshness.

Polling guidance

Locations refresh on Apple’s cadence, not per request — polling faster than a participant’s location actually updates just returns the same position. Poll at a modest interval (for example, once every few minutes per chat) rather than continuously.

Why is location empty after location.sharing.started fired?

If the contact started sharing from the standalone Find My app instead of the Messages conversation, the share may be tied to their Apple ID email rather than their phone number — the webhook’s shared_by field shows the email in that case. Location is readable only through a chat with the handle that shared, so GET /v3/chats/{chatId}/location on the phone-number chat stays empty.

The fix: have the contact stop sharing and re-share from Find My inside the Messages conversation with your number.