API V3 FAQs

Getting Started

Where can I access the API toolkit?

Everything related to the API can be found in the API toolkit within the Linq dashboard. There, you'll be able to find your API Key, documentation, manage your webhook subscriptions, view webhook delivery logs, and see the status of your phone lines.

Where can I view a list of my phone lines?

You can view a list of your phone lines by visiting the analytics page in the dashboard, or the phone numbers page in the API toolkit. You can also retrieve a list of available numbers programmatically by using the GET /v3/phone_numbers request. This returns each number's status, type, country code, and capabilities (SMS, MMS, voice).

What’s the best place to monitor the usage and health of my lines?

To view usage analytics, visit the analytics page. To check operational status of your lines, check in the phone numbers section of the API toolkit. To receive updates programmatically regarding the operational status of your lines, you can subscribe to the phone_number.status_updated webhook event.

How can I view messages and manage inboxes for my lines?

You can view inboxes within the Linq dashboard in one of two ways. By viewing a single inbox in the messages tab, or by viewing multiple inboxes in the team inboxes tab.

How do I rotate my API key?

Please reach out to your Linq Representative to have this done.

How do I debug API issues?

Every API response includes a trace_id field. When contacting support, provide this trace ID to help us quickly identify and diagnose your issue.

iMessage, RCS, and SMS

Can my lines send RCS/SMS in addition to iMessage? Can I select between them?

Your line has the ability to send iMessages, RCS, and SMS messages. You can control which service to use via the preferred_service parameter when sending messages:

• iMessage: Enforces iMessage without fallback to RCS or SMS. The message will fail if the recipient doesn't support iMessage.
• RCS: Enforces RCS or SMS (no iMessage). Uses RCS if the recipient supports it, otherwise falls back to SMS.
• SMS: Enforces SMS (no iMessage). Uses RCS if the recipient supports it, otherwise falls back to SMS.

If preferred_service is not specified, the default fallback chain is: iMessage → RCS → SMS.

How can I check what service my recipients are on?

You can use POST /v3/capability/check_imessage to check whether a recipient is iMessage capable, and POST /v3/capability/check_rcs to check whether a recipient is RCS capable. You can also find the recipient’s service via the message.sent or message.received webhook, where we display either iMessage, RCS, or SMS in the service field of the event payload.

Using Share Contact Card

What does the Share Contact Card POST request do?

The Share Contact Card request calls an endpoint that pushes an Apple contact card to recipients. This utilizes an iMessage exclusive feature that presents itself as a popup at the top of the recipient's message thread prompting them to add your contact to their phone. Even without pressing "Add," your suggested name and picture will still display in the recipient's thread and inbox. The information shared in a contact card is limited to one phone number, a name (first and last), and photo.

How can I get the Share Contact Card feature enabled?

You must set up a contact card via the contact card section of the Linq dashboard, or programmatically via the POST /v3/contact_card request for this feature to work.

We recommend using a picture with a 1:1 aspect ratio with at least 200x200 px resolution.

How do I use Share Contact Card?

We recommend calling the share endpoint after your first outbound activity, then once per day following that. This polling interval is recommended as recipients may sometimes initially neglect to add your contact information to their phones. Also, if you’ve updated your contact card, you will want to call the endpoint again to ensure the latest information is being pushed to recipients.

NOTE: an outbound message is required for the contact card to show to recipients.

Does Share Contact Card work with non-iPhone users too?

Share Contact Card will not work with non-iPhone users, as it's an iMessage exclusive feature.

How can I share my contact information with non-iPhone users?

We recommend sending recipients a .vcf file with your name, picture, number, and any other information you wish to share (including, but not limited to email, website, address, etc.). You can add multiple backup numbers to a .vcf file as well. You can utilize a .vcf file generator online, or create a .vcf file in the contacts app on your mobile device or desktop, and download it to your machine for use.

If a user shares their contact card with me, am I able to add them to my contact list?

If they send a .vcf file to you, you can download that file and save it to your contact list. However, if they’re sharing their contact using the Apple contact card feature, there is currently no way to read or save that information.

Chat Messages

How do message reactions (tapbacks) work? What types are supported?

You can both react to messages as well as get message reactions via the API. We support basic iMessage reactions: love, like, dislike, laugh, emphasize, and question. You can also use custom emoji reactions by setting the type to custom and specifying the emoji in the custom_emoji field (e.g., 🚀, 😍, 🎉).

There are reaction.added and reaction.removed webhook events you can subscribe to.

What iMessage effects can I send with my messages?

You can add screen effects or bubble effects to messages using the effect parameter:

Screen Effects: confetti, fireworks, lasers, sparkles, celebration, hearts, love, balloons, happy_birthday, echo, spotlight

Bubble Effects: slam, loud, gentle, invisible

Only one effect can be applied per message. Effects are an iMessage exclusive feature and will not display for RCS/SMS recipients.

Why isn’t my typing indicator showing up on the recipient’s device even though the API returns 204?

Typing indicators are best-effort signals. A 204 response from POST /v3/chats/{chatId}/typing means the request was accepted for processing. It does not guarantee the indicator will appear on the recipient's device.

For an outbound typing indicator to reach the recipient, the chat must be active, meaning the recipient must have sent or received a message in that chat within the last 5 minutes. If the chat is inactive, the request can still return 204, but the indicator will not be delivered.

Typing indicators in group chats are not supported. POST /v3/chats/{chatId}/typing and DELETE /v3/chats/{chatId}/typing return 403 for group chats.

What types of files can I send via the API?

We support attachments via URL or Pre-Upload using POST /v3/chats/{chatId}/messages. Use the latter for sending files larger than 10 MB, or to optimize sending the same file to many recipients at lower latency. If your application enforces domain allowlists, please add cdn.linqapp.com. Examples of media you can send include: images, videos, audio, documents, contacts, and calendar events.

How can I make URLs automatically unfurl for recipients and display a rich media preview?

To do so:

1. set part.type to link
2. send the link on its own without any additional parts
3. ensure the link has a scheme (e.g. HTTP, HTTPS, FTP, etc.)

How do I send a voice memo?

Use the dedicated POST /v3/chats/{chatId}/voicememo endpoint. Voice memos must be sent alone without text or other attachments.

Supported formats: MP3, M4A, AAC, CAF, WAV, AIFF, AMR

Maximum size: 10MB

Can I send OTP codes through the my Linq line?

Linq numbers are P2P iMessage numbers, and are not explicitly designed to deliver that category of messaging. To ensure consistent delivery of OTP codes, we recommend you utilize a traditional SMS provider to handle that function.

Do you support sending App Clips?

Yes, simply send the App Clip link on its own and it will display normally for the recipient.

Can my AI agent interact with iMessage apps?

iMessage apps are not currently supported.

How can I prevent duplicate messages?

Use the idempotency_key parameter when sending messages. If you send the same request twice with the same key, the second request will return the original message instead of creating a duplicate. This is useful for retry logic in unreliable network conditions.

Can I edit messages?

Yes, you can edit messages using PATCH /v3/messages/{messageId}, which will amend the contents of the message on your and the recipient’s end. A message can be edited up to 5 times within 15 minutes from when it was originally sent.

Can I delete messages?

You can delete messages from the Linq API records using DELETE /v3/messages/{messageId}. NOTE: this does not unsend the message—recipients will still see it. Use this to remove messages from your API responses, records, and hardware.

What’s your default data retention policy?

Group Chats

Can I add or remove participants from group chats?

Yes, you can add and remove participants from existing group chats:

• Adding participants: Use POST /v3/chats/{chatId}/participants
  • Group must have 3+ existing participants
  • New participant must support the same messaging service as the group (you can't add an RCS-only user to an iMessage group)
• Removing participants: Use DELETE /v3/chats/{chatId}/participants
  • Group must have 3+ participants after removal

For cross-service scenarios (e.g., adding an Android user to an iMessage group), create a new chat instead with all desired participants.

Can I leave a group chat?

Yes, you can use POST v3/chats/{chatId}/leave to do so. The chat must have 3+ participants after you leave.

What support do you have for threaded replies?

You can reply to messages in a threaded manner using the reply_to parameter when sending a message. Specify the message_id of the message you want to reply to, and optionally the part_index if replying to a specific part of a multi-part message.

When you receive messages via webhooks, threaded replies include a reply_to field containing the message_id (and optionally part_index) of the original message being replied to.

Do typing indicators work in group chats?

Group chat typing indicators are not currently supported.

What happens to the Chat ID if a participant is added or removed from a group chat?

If a participant is added to a group chat, the Chat ID will remain the same.

Voice Calls

How can I receive inbound voice calls?

You cannot pick up calls to the Linq number itself. You can, however, forward inbound calls to a voice-capable service of your choice. To do so, use PUT /api/partner/v2/phone_number/{id} found in V2 of the Linq API to set the forwarding path.

How can I make outbound calls?

The Linq line does not have native outbound calling capabilities. To enable outbound calling for your AI agent, we recommend you use a voice-capable service with number masking features, and set your Linq number as the masked number.

Webhooks

Where can I set up webhook subscriptions?

You can easily set up and manage webhook subscriptions in the Linq dashboard’s API toolkit.

What webhook subscriptions are available?

To view a list of the latest webhook events, visit this page.

Can webhooks be configured on a per-number basis?

By default, webhooks will emit for all numbers in your environment. However, there is an optional filter you can apply to isolate webhooks by phone number. To do so, you can create separate subscriptions, specify the phone_numbers parameter, and route to a dedicated endpoint for each number you’d like to isolate.

What is your webhook retry policy?

Webhooks are retried with exponential backoff if your endpoint fails to respond:

Retry attempts: 10 attempts per endpoint

Total retry window: ~25 minutes

What triggers a retry?

• HTTP 5xx responses (server-side errors)
• HTTP 429 (rate limited)
• Connection timeout (>10 seconds)
• Connection refused / network errors

What does NOT trigger a retry?

• HTTP 4xx responses (except 429) are considered permanent failures and are not retried.

You can check delivery logs in the API toolkit.

If I miss webhooks due to an outage, how can I retrieve the missing message data?

If an outage occurs, call the /v3/chats/{chatId} endpoint to pull missed data, or reach out to your Linq Representative to request manual event replay.

Will Linq send multiple webhooks to my server in quick succession, or send one then wait for my server to return a 200 before sending more?

Linq will send webhooks regardless of what your server returns. You will have to log them on your end and process them asynchronously.

How should I handle duplicate webhooks?

Use the event_id field to deduplicate events. The same event may arrive multiple times during retries, so your webhook handler should be idempotent—processing the same event twice should have no side effects. We recommend:

1. Store processed event_id values (e.g., in Redis or your database)
2. Check if an incoming event_id has already been processed
3. Skip processing if it's a duplicate

How do I verify webhook authenticity?

Each webhook includes X-Webhook-Signature and X-Webhook-Timestamp headers. Verify the signature using HMAC-SHA256:

1. Concatenate: {timestamp}.{raw_request_body}
2. Compute HMAC-SHA256 using your signing secret (provided when you created the subscription)
3. Compare the result to the X-Webhook-Signature header

Important: Use the raw request body exactly as received—do not re-serialize parsed JSON, as this can change key order or whitespace and break the signature.

I’m messaging certain numbers, and not receiving any message.delivered webhook events. Why is that?

Delivery status is only available for iMessage and RCS. The recipient may have an SMS-only device, in which case you’ll only be emitted a message.sent webhook.

Setting up and Managing Environments

What’s the best way to separate lines for testing, staging, and production purposes?

Although you can control which lines are used for what purposes on your end, to prevent accidental deployment of test features into production, we recommend segmenting lines into separate environments entirely.

To have this done, please reach out to your Linq Representative and request your desired setup. We will separate your numbers for you. Each environment will have its own dashboard and API key, which you can access via the admin login(s) we provide for each environment.

How can my team members to have access to the dashboard too?

You can either have your account set up with a shared team email, or you can invite users from the Users section of the dashboard.

Limitations and Usage Guidelines

How many messages can I send from each of my lines?

We recommend limiting message volume to a combined total of up to 7,000 inbound and outbound messages per day per line. Volume north of the recommended range has the potential to degrade performance.

Does Linq impose volume limitations?

While there are no hard caps on daily volume (excluding our sandbox users), the API does enforce a per-phone-pair rate limit of 30 messages per 60-second window. This applies to each unique sender–recipient pair and is designed to prevent automated feedback loops where two numbers (i.e. bots) rapidly exchange messages. When exceeded, the API returns HTTP 429 with a Retry-After header. If you have legitimate high-volume needs for a specific phone pair, contact your Linq Representative.

In all other instances apart from the above, Linq does not impose hard limitations on message volume. The aforementioned 7,000 messages per day threshold is a recommendation meant to optimize the performance of your lines. We recommend you control volume via onboarding flows and load balancing you build on your end.

How do message volume guidelines translate to concurrent users per line?

The approach to determining the number of concurrent users each of your lines can support is nuanced, given factors including how your AI agent behaves (does it send many or few messages) and how your users behave (do they converse with your AI, or simply make requests of it). We recommend utilizing a pilot line, onboarding users onto that line, and calculating the average number of inbound/outbound messages per user. You can then use the resulting amount to determine how many users can onboard onto your line before you hit the 7,000 messages/line/day guideline.

What should I expect when it comes to systemic downtime?

Scheduled maintenance will be communicated to you in advance. In the event of a platform outage, you can monitor live as well as subscribe to updates via our *status page.*

How can I mitigate the risk of line-specific downtime?

We highly recommend using backup numbers to ensure service is available should any one of your lines become inoperable. To implement this, add one or more backup numbers to a .vcf file along with your the primary number and share it with users upon onboarding (ideally via web download at signup) for them to add to their contact list. If your service were to fall back to any of the backup numbers, users would still see messages come through in their existing thread, preserving continuity.

One of my lines is disabled and I need to move users to a different line. What’s the best way to ensure people can continue to use my product?

If users need to be migrated to a new line, we recommend setting up a dedicated broadcast number to announce issues/outages, and to direct users to working lines. The best tool for this would be an A2P registered SMS line reserved for this purpose. Email and push notifications (if you have an app) are also recommended. It’s preferred that migrations to different numbers take place by prompting users to inbound to the new number rather than out bounding to users from that new number, unless you know for certain that the user is actively engaging with your service.

What typically causes individual lines to become disabled?

Flagging is one of the most common reasons why your line may become non-operational. Flagging is when Apple disables a phone line due to a high amount of spam reports from recipients or low message reciprocity. Apple may also flag your number due to sudden volume spikes (which are interpreted as automated, spammy behavior). You can monitor the status of your lines in the API toolkit in the dashboard. We also encourage you to subscribe to the phone_number.status_updated webhook to detect flagged lines programatically.

If my line gets flagged, how long should I expect it to be down?

Flagged lines typically see downtime of around 24 hours, but may be longer depending on severity. You will be able to check the recovery status in the API toolkit section of the dashboard, and will receive a phone_number.status_updated webhook event notifying you when the number is active again if you’ve subscribed to it.

If my line is flagged, will I still be able to receive inbound messages to it?

It is possible that you might receive inbound messages for a short while, but it’s expected that all activity to and from the line will fail at some point. The expected behavior is that iMessages will fail first, followed by RCS/SMS.

How can I reduce the incidence of flagging?

The following are best practices to reduce flagging risk:

• Inbound flow: Have users message your number first. This removes their ability to mark your message as spam, since they initiated the conversation.
• Load balance: Have users onboard evenly across multiple lines and over-provision by 10-20% in order to account for peak times and virality. We recommend onboarding users via deeplink from your webpage so you can rotate numbers with each signup.
• Ramp up usage gradually: Onboard users evenly and gradually to avoid large volume spikes.
• Ensure your AI isn't aggressive: AI that aggressively follows up (especially unsolicitedly) can cause users to block your number and signal to Apple that recipients are receiving spam.
• Have clear opt-out detection: Honor opt-out language from your users (e.g. stop, unsubscribe, or negative sentiment generally) by subscribing to the message.opt_in and message.opt_out webhook events.
• Use multiple lines: We recommend sharding across multiple numbers so that if one were to become unavailable, your service will still remain operational. You can also put multiple fallback Linq Blue numbers on .vcf files you share with users at onboarding to ensure they can continue to receive communications in their existing threads should the primary number become flagged.

Is adding a user to a group chat considered “outbound” first communication?

Yes, adding users to group chats is considered outbound, regardless of who actually sends the first message in the chat. Those added will be given the ability to mark the conversation as junk until there is sufficient back and forth.

How much engagement should I aim for to ensure my lines remain in good standing?

You should aim to elicit 3+ responses from a new user as soon as possible in order to keep conversations healthy. You should also aim for a message reciprocity ratio of 1:2 (inbound:outbound) for optimal results.

From a message reciprocity standpoint, what counts as a “reply” from a user?

Messages back as well as reactions (tapbacks) count as responses and boost message reciprocity.

What is Linq doing to help prevent my numbers from being flagged?

As responsible stewards of the iMessage ecosystem, we’re committed to providing you with the necessary tools and alerts to not only ensure your lines stay operational, but to help you deliver your end users the best possible experience. We’ve recently released a new beta feature called Chat Health that surfaces risky chats early, letting you make adjustments proactively to prevent flagged lines.

Miscellaneous

Do you have an Open API Spec for your API?

Yes, it can be found here.

I’d like to connect my Linq line to Claude. Is there a resource that I can use to do this?

Yes, you can find MCPs for Claude and other integrations here.

How do I rotate my API key?

You can rotate your API key from the API toolkit.