GETTING STARTED
Can I get the API documentation in YAML format?
Yes, click here to view the documentation in YAML.
Where can I find a list of Linq Blue lines I have and view their usage?
Log into https://zero.linqapp.com/login and click the “chart” icon on the left-hand toolbar to see a list of numbers and line usage analytics, including inbound/outbound message volume over different timeframes.
Where can I view messages and manage inboxes for my lines?
There are two ways to view inboxes.
- For single-inbox view, log into https://zero.linqapp.com/login and click the “chat bubble” icon on the left-hand toolbar.
- For multi-inbox view, log into https://zero.linqapp.com/login and click the “file drawer” icon on the left-hand toolbar and select the user’s inbox you would like to view.
DIFFERENTIATING BETWEEN IMESSAGE, RSC, AND SMS
Can Linq Blue send RCS/SMS in addition to iMessage? If so, is there a way I can select between these services?
Your Linq Blue line has the ability to send iMessages, RCS, and SMS messages, but there is no way to select which of these services to send from. In the event that a chat is created between your number and a non-iPhone user, the service will fall back to either RCS or SMS (dependent on the recipient’s device capabilities).
How can I tell if a recipient has an iPhone?
We have a Check iMessage Availability POST request which you can poll up to once per 10 seconds per Linq Blue line to determine whether the recipient is iMessage capable (it returns true/false).
Can I differentiate between RCS and SMS capable recipients?
Not prior to creating a chat. Check iMessage Availability only returns true/false for iMessage capability. However, upon receipt of a message.sent or message.received webhook, we do display either iMessage/RCS/SMS in the “service” field in the event payload. You can also find a service field in the response for both the Get Chat and List Chats requests.
USING SHARE CONTACT CARD
What’s the difference between Share Contact Card and sending a .vcf file?
Share Contact Card utilizes Apple’s native iCloud contact card sharing feature. iCloud contact card sharing is limited to attributing a name and photo to your iMessage number. Recipients can then add the shared name, number, and photo to either a new contact, or an existing contact in their contact list. .vcf files are files that you send as attachments to recipients. They can host information including multiple phone numbers, your company name, emails, websites, addresses, notes and more. By clicking on the file, recipients can add all of that information into their contact list. As a best practice, we recommend sharing a .vcf with at least your number and a backup Blue number for users to add at onboarding.
What does the Share Contact Card POST request do?
The Share Contact Card request calls an endpoint that pushes a contact card to recipients. This feature 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.
How can I get the Share Contact Card POST request enabled?
We will have to set up contact cards for you to be able to utilize the request. Please reach out to your point of contact on the Linq Team and, for each line you’d like to have a contact cards set up for, please send them:
- The Linq Blue number
- A first and last name (last name is optional) you’d like your number to display
- A profile picture for your number (minimum size of 200 x 200 pixels and a 1:1 aspect ratio; solid backgrounds only)
What is the best way to utilize Share Contact Card?
We recommend calling the Share Contact Card endpoint immediately after creating a chat, and then once per 24 hours for active chats (ones where there has been message activity in the last 5 minutes). This polling interval is recommended as recipients may sometimes initially neglect to add your contact information to their phones. Also, if you have us update your contact card, you will want to call the endpoint again to ensure the latest information is being pushed 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.
CHAT MESSAGES
How do typing indicators work?
Automatic typing indicators are on by default. However, to optimize performance, we recommend that you control them on your end. To do so, contact your Linq Representative and request that auto typing indicators be turned off for your Linq Blue line. You can then use the start_typing and stop_typing endpoints to initiate and cease typing indicators (you can display typing indicators for up to 60 seconds). Note: typing indicators only work for active chats—those with activity in the last 5 minutes.
How do message reactions 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. There are also reaction.sent and reaction.received webhook events you can subscribe to.
What types of files can I send via the API
We support attachments via the attachment array or attachment URL of the Send Message POST request. Examples of media you can send include, videos, voice memos (.m4a), audio files, URLs, PDFs, etc.
GROUP CHATS
Can I name/rename group chats?
Not currently. The display_name field in the Create Chat request body is internal only, and won’t change the group chat’s on-device name.
Can I add participants to existing group chats?
You can’t add participants to existing group chats. You can, however, create a new group chat with the same users plus any new participants as a way to expand the amount of users in an existing group chat.
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 should remain the same. The only time a new Chat ID is created will be if an Android participant is added to an all iPhone group chat. In all other instances, Chat IDs when participants are added or removed will remain stable.
What support do you have for threaded replies?
You can’t reply to messages in a threaded manner, but you are able to differentiate between regular and threaded inbound messages via the replied_to_chat_message_id you’ll get in the webhhook payloads for both message.received and reaction.received.
Do typing indicators work in group chats?
Typing indicators in group chats are a relatively new feature released with iOS 26. We don’t currently support them.
VOICE CALLS
Can I receive inbound voice calls via the API?
Our API doesn’t currently support inbound calling. You can, however, receive inbound calls by forwarding your Linq Blue line to a number of your choice. To do so, you can utilize the Update Phone Number PUT request.
Can I get voice call transcriptions via the API?
You will receive call transcription data in the call.completed webhook whenever a voice call is completed.
Can I make outbound voice calls via the API?
No, but if you own another phone number that allows masking (for example, a Twilio number with Verified CallerID), you can mask your Linq Blue number over your calling number so that the Linq Blue number displays when you make outbound calls.
How do I enable AI voice agents to work with my Linq Blue lines?
We recommend utilizing a VOIP number (commonly, Twilio) along with the above setups for inbound and outbound voice calls to route calls to and from your AI voice agent using the Twilio API.
WEBHOOKS
Are webhooks configured on a per number basis?
Webhooks are not configured per number. They will fire for all the numbers in your environment.
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. To avoid timeouts, we recommend immediately returning a 200.
Does Linq support webhook retries?
Webhooks time out after 15 seconds if your server fails to read them. There are currently no retries. You can check delivery logs at https://zero.linqapp.com/login in the API tools section.
SETTING UP 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.
I want to separate my numbers into different environments for testing, staging, and production. How do I do that?
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 API key, which you can access via the admin logins we provide for each environment.
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 3,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?
Linq does not impose hard limitations on message volume. The above limitations are recommendations meant to optimize the performance of your lines. We recommend you control volume via onboarding flows you build on your end.
How do message volume limitations translate into 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 3,000 messages/day recommended volume limit.
What should I expect when it comes to availability and potential downtime?
We strive for 100% uptime. 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. A copy of our Linq Blue Technical SLA can be obtained from your Linq Representative.
Besides system wide outages, what other issues may cause your Linq Blue line to become unavailable?
Flagging is one of the most common reasons why your line may become non-operational. Flagging is when Apple disables iMessage capability for a phone number due to a high amount of spam reports from recipients. Apple may also flag your number due to volume spikes (which are interpreted as automated, spammy behavior). We will contact you if your line is flagged and offer guidance on a resolution, including whether your number may be recovered, or whether we’ll have to issue you a new number.
How can I mitigate the risk 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 Linq Blue lines.
- Ramp up usage gradually: onboard users 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.
- 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 should your primary line become flagged.
- Have us warm your lines: we have a warming service that can be utilized upon request to “warm up” your lines prior to use. This takes on average 5-7 days, but increases the resiliency of your numbers when you do introduce them into production.