Skip to content
English
Go to linqapp.com
  • There are no suggestions because the search field is empty.

API V3 FAQs

V3 General FAQ 

Where do I find my API key, docs, webhooks, and delivery logs?

Log into Linq Zero and click the API (code) icon in the left toolbar. From there you can copy your API key, open documentation, manage webhook subscriptions, and view webhook delivery logs.

Where do I view line usage and analytics?

Log into Linq Zero and click Team Analytics (chart icon). You’ll see message volume and conversation metrics across timeframes (24h, 7d, 30d, 1y, custom).

How do I access a single inbox?

Log into Linq Zero → click the chat bubble icon in the left toolbar.

How do I access multiple inboxes (team view)?

Log into Linq Zero → click the file drawer icon in the left toolbar → select the user’s inbox.

How do I retrieve all phone numbers assigned to my account (v3)?

Use GET /v3/phonenumbers. It returns each number’s status, type, country code, and capabilities (SMS, MMS, voice).

What is trace_id and why do I need it?

Every API response includes a trace_id. When contacting Support, include the trace_id so we can quickly locate and diagnose the request.

How do I choose between iMessage, RCS, and SMS when sending?

Use the preferred_service parameter:

  • iMessage: iMessage only (no fallback). Fails if recipient isn’t iMessage-capable.

  • RCS: RCS or SMS only (no iMessage). Uses RCS if supported, otherwise SMS.

  • SMS: SMS only (no iMessage). Uses RCS if supported, otherwise SMS.

What happens if I don’t set preferred_service?

Default fallback chain is: iMessage → RCS → SMS.

Can Linq check iMessage capability before creating a chat?

Not prior to chat creation. After events occur, message.sent / message.received webhook payloads include a service field indicating iMessage, RCS, or SMS.

What is “Share Contact Card”?

It pushes an iMessage contact card prompt at the top of the recipient’s thread asking them to add your contact. Even if they don’t tap “Add,” your suggested name and picture may still display in their thread/inbox.

What do we need to set up Share Contact Card?

Contact cards must be set up first. For each line, provide your Linq rep:

  • Linq Blue number

  • First name (required) and last name (optional)

  • Profile picture (min 200×200, 1:1, solid backgrounds recommended)

How often should we call Share Contact Card?

Recommended:

  • Immediately after creating a chat

  • Then once per 24 hours for active chats (message activity in the last 5 minutes)
    If the contact card is updated, call it again to push the latest card.

Does Share Contact Card work for Android users?

No. It’s iMessage-only.

What’s the recommended alternative for non-iPhone users?

Share a .vcf contact file (name, picture, number, plus optional email/website/address). You can include multiple backup numbers.

Are typing indicators supported?

Yes for 1:1 chats. Auto typing indicators are on by default. You can request auto typing be disabled, then control them using startTyping and stopTyping. Group typing indicators are not supported.

Can we send message reactions via API?

Yes. Supported reactions include love, like, dislike, laugh, emphasize, and question. Custom emoji reactions are supported. Webhook events: reaction.added and reaction.removed.

Can we send iMessage effects?

Yes via the effect parameter (one effect per message). Effects are iMessage-only and won’t display for RCS/SMS recipients.

Are attachments supported?

Yes. You can send videos, voice memos, audio, URLs, PDFs, images, and more using the attachment array or attachment URL.

How do we send a voice memo?

Use POST /v3/chats/{chatId}/voicememo. Voice memos must be sent alone (no text/other attachments). Supported formats include MP3, M4A, AAC, CAF, WAV, AIFF, AMR. Max size is 10MB.

How do we prevent duplicate messages during retries?

Use idempotency_key. If the same request is sent twice with the same key, the second call returns the original result instead of creating a duplicate message.

Can we delete messages?

Yes via DELETE /v3/messages/{messageId}. This removes the message from Linq API records only; it does not unsend it from the recipient.

Can we add/remove group chat participants?

Yes:

  • Add: POST /v3/chats/{chatId}/participants

  • Remove: DELETE /v3/chats/{chatId}/participants
    Rules apply (group size minimums and service compatibility). For cross-service changes (like adding Android to an iMessage group), create a new chat.

Are threaded replies supported?

Yes using reply_to when sending messages. Webhooks include reply_to fields for replies.

Does the API support inbound/outbound voice calling?

No. Voice calling is not currently supported via the API. Use a separate VOIP provider for voice and route calls via that provider’s API.

What webhook events are available?

Common events include message.sent, message.received, message.delivered, message.read (iMessage only), message.failed, reaction.added, reaction.removed, chat.created, participant events, and group name/icon update events.

Are webhooks configured per number?

No. Webhooks fire for all numbers in your environment.

Do webhooks retry if our endpoint fails?

Yes. Retries occur with exponential backoff:

  • Timeout: 10 seconds

  • Attempts: 6

  • Backoff: 2s → 4s → 8s → 16s → 30s

  • Total window: ~60 seconds
    Retried on 5xx, 429, timeouts, and network errors. 4xx (except 429) are treated as permanent failures and are not retried.

Where do we view webhook delivery logs?

In Linq Zero → API tools section → Webhook Delivery Logs.

Will Linq stop sending webhooks if our server returns errors?

No. Linq will continue sending. Your system should log events and process them asynchronously.

How do we deduplicate webhook events?

Use event_id. Store processed event_ids and skip duplicates. Your webhook handler should be idempotent.

How do we verify webhook signatures?

Use X-Webhook-Signature and X-Webhook-Timestamp. Compute HMAC-SHA256 over {timestamp}.{raw_request_body} using your signing secret, and compare. Use the raw body exactly as received.

Should we split production and testing into separate environments?

Yes. We recommend separating lines into distinct environments to avoid accidental test deployment into production. Each environment has its own API key. Request environment setup via your Linq rep.

What message volume is recommended per line?

We recommend up to ~3,000 combined inbound/outbound messages per day per line to optimize performance. This is guidance, not a hard limit.

How do we estimate how many users a line can support?

Pilot one line, measure average inbound/outbound messages per user, then use that average to size how many users can be supported before reaching the recommended daily volume.

What is flagging and what happens if a line is flagged?

Flagging occurs when Apple disables iMessage capability for a number due to spam reports or patterns interpreted as spam (including volume spikes). Linq will notify you and provide guidance. Apple controls if/when a number is unflagged; recovery isn’t guaranteed.

How do we reduce flagging risk?

  • Prefer inbound-first when possible (user messages first)

  • Load balance across multiple lines

  • Ramp usage gradually (avoid spikes)

  • Keep AI follow-ups non-aggressive

  • Detect and honor opt-outs

  • Shard across multiple numbers for resiliency

  • Optional line warming is available upon request (typically 5–7 days)