GETTING STARTED
Where can I access my API Key, documentation, and manage webhooks?
You can log into https://zero.linqapp.com/login and click the “code” icon on the left-hand toolbar. There, you’ll be able to find your API Key, documentation, manage your webhook subscriptions, and view wehbook delivery logs.
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 what service the recipient has.
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.
USING SHARE CONTACT CARD
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 add participants to 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 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 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.
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.
How can I mitigate the risk of downtime?
We recommend using a backup Twilio number to ensure service is available should your Linq Blue line become inoperable. To implement this, add the backup Twilio number to a .vcf file along with your Linq Blue number and share it with users upon onboarding for them to add to their contact list. If your service were to fall back to the Twilio number, the user would still see messages come through in their existing thread, preserving continuity.
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.
- 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.