Chats
List all chats
Update a chat
Share your contact card with a chat
Send a voice memo to a chat
ChatsParticipants
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
Add a participant to a chat
Remove a participant from a chat
ChatsTyping
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
ChatsMessages
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
linkpart cannot be combined with other parts in the same message. - Maximum URL length: 2,048 characters.
App Clips
An app_clip part sends a registered App Clip — not only Linq’s Apple Pay
checkout, but any partner’s own App Clip. Like a link part it must be the
only part in the message, and it is iMessage only — it never downgrades
to SMS or RCS. The payment-checkout use of this part is covered in the
Payments section.
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 given a retention window configured for your account. After that window, the message’s text, formatting, and attachment references are no longer retrievable through the API — see the Attachments row below for how the attachment media itself is handled. Metadata about the message is retained: message identifiers, timestamps, phone numbers, and delivery state. Metadata retention is not bounded by this window. Bounded operational copies, such as backups and delivery queues, expire on their own separate schedules. There is no per-message flag; ephemerality is applied automatically based on your configuration.
The window can be set anywhere from 60 minutes to 24 hours, and defaults to 24 hours. Ask your Linq support contact to configure a shorter window; it cannot be changed through the API.
You can request it at two scopes:
| Scope | Effect |
|---|---|
| Partner-wide | Every outbound and inbound message on every phone number under your account has its content removed from the API surface after your configured window. Metadata is retained. |
| Per phone number | Only the specified phone numbers have message content removed from the API surface this way. 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: your configured window (60 minutes – 24 hours, default 24 hours) from when the message is created |
| After expiry | Message stays retrievable | Message content is no longer retrievable — 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 removed from the API surface, not blanked out in place. Metadata (identifiers, timestamps, phone numbers, delivery state) is retained; its retention is not bounded by this window |
| Attachments | Retained | Media sent on the ephemeral attachments tier is removed on its own storage backstop — within roughly 24–48 hours of upload — independently of the message window, so it can outlast a window shorter than a day. Attachments on the persistent tier (including pre-uploads via POST /v3/attachments) are kept until you DELETE them |
| Cross-partner isolation | Enforced | Enforced |
How the retention window works:
- The window runs from message creation (
created_at). It is configured for your account (60 minutes – 24 hours, default 24 hours) and cannot be set per message. - Attachment media follows its own storage backstop rather than the message window — see the Attachments row above.
- Expiry is delivery-independent — the clock starts when the message is created, not when it is delivered or read.
- Deletion happens shortly after the window, not exactly at it. A background sweep runs every ~5 minutes, so a message typically stops being retrievable within about 5 minutes of its expiry, and longer while a backlog is being worked through. Treat the window as the guaranteed minimum retention, never as an exact deletion time or an upper bound.
What you observe:
- No expiry timestamp is exposed. API responses and webhook payloads do not include the deletion time, and they do not report your configured window either — so if you are on a window shorter than 24 hours you cannot derive a message’s expiry from the API today. Track the window you agreed with your Linq support contact and compute
created_at + windowyourself. - No deletion webhook is sent. There is no
message.deletedevent — a message simply stops being retrievable once its window passes. - The attachment backstop is separate from the message window. API retrievability (the
404behavior above) ends at your configured window. Ephemeral-tier media objects are removed on their own storage backstop — within roughly 24–48 hours of upload — which is independent of the message window and can outlast a window shorter than a day. Removal of the corresponding entries from the sending device happens asynchronously and can complete after the backstop. - Delivery is unaffected. Ephemeral messages send, deliver, and fire the usual
message.sent/message.receivedand 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 once its window passes, persist anything you need to keep from the webhook payload at the time it is delivered.
Send a message to an existing chat
Get messages from a chat
ChatsLocation
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].
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.
Request location sharing
Get location data
Stop location sharing
ChatsPolls
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
linkpart cannot be combined with other parts in the same message. - Maximum URL length: 2,048 characters.
App Clips
An app_clip part sends a registered App Clip — not only Linq’s Apple Pay
checkout, but any partner’s own App Clip. Like a link part it must be the
only part in the message, and it is iMessage only — it never downgrades
to SMS or RCS. The payment-checkout use of this part is covered in the
Payments section.
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 given a retention window configured for your account. After that window, the message’s text, formatting, and attachment references are no longer retrievable through the API — see the Attachments row below for how the attachment media itself is handled. Metadata about the message is retained: message identifiers, timestamps, phone numbers, and delivery state. Metadata retention is not bounded by this window. Bounded operational copies, such as backups and delivery queues, expire on their own separate schedules. There is no per-message flag; ephemerality is applied automatically based on your configuration.
The window can be set anywhere from 60 minutes to 24 hours, and defaults to 24 hours. Ask your Linq support contact to configure a shorter window; it cannot be changed through the API.
You can request it at two scopes:
| Scope | Effect |
|---|---|
| Partner-wide | Every outbound and inbound message on every phone number under your account has its content removed from the API surface after your configured window. Metadata is retained. |
| Per phone number | Only the specified phone numbers have message content removed from the API surface this way. 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: your configured window (60 minutes – 24 hours, default 24 hours) from when the message is created |
| After expiry | Message stays retrievable | Message content is no longer retrievable — 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 removed from the API surface, not blanked out in place. Metadata (identifiers, timestamps, phone numbers, delivery state) is retained; its retention is not bounded by this window |
| Attachments | Retained | Media sent on the ephemeral attachments tier is removed on its own storage backstop — within roughly 24–48 hours of upload — independently of the message window, so it can outlast a window shorter than a day. Attachments on the persistent tier (including pre-uploads via POST /v3/attachments) are kept until you DELETE them |
| Cross-partner isolation | Enforced | Enforced |
How the retention window works:
- The window runs from message creation (
created_at). It is configured for your account (60 minutes – 24 hours, default 24 hours) and cannot be set per message. - Attachment media follows its own storage backstop rather than the message window — see the Attachments row above.
- Expiry is delivery-independent — the clock starts when the message is created, not when it is delivered or read.
- Deletion happens shortly after the window, not exactly at it. A background sweep runs every ~5 minutes, so a message typically stops being retrievable within about 5 minutes of its expiry, and longer while a backlog is being worked through. Treat the window as the guaranteed minimum retention, never as an exact deletion time or an upper bound.
What you observe:
- No expiry timestamp is exposed. API responses and webhook payloads do not include the deletion time, and they do not report your configured window either — so if you are on a window shorter than 24 hours you cannot derive a message’s expiry from the API today. Track the window you agreed with your Linq support contact and compute
created_at + windowyourself. - No deletion webhook is sent. There is no
message.deletedevent — a message simply stops being retrievable once its window passes. - The attachment backstop is separate from the message window. API retrievability (the
404behavior above) ends at your configured window. Ephemeral-tier media objects are removed on their own storage backstop — within roughly 24–48 hours of upload — which is independent of the message window and can outlast a window shorter than a day. Removal of the corresponding entries from the sending device happens asynchronously and can complete after the backstop. - Delivery is unaffected. Ephemeral messages send, deliver, and fire the usual
message.sent/message.receivedand 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 once its window passes, persist anything you need to keep from the webhook payload at the time it is delivered.
Create and send a poll in a chat
ChatsBackground
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