The largest consumer companies in the world are building on our API, and they all hit the same wall at scale: at any given point in time, which Linq number is most optimal to assign to a user?

Today we’re taking on all the work involved in answering that question through two new endpoints in our API. These endpoints take routing, health checks, failover, and number migration off your plate. You send a message to a recipient, and we pick the line, create or reuse the chat, and route around numbers that can't send.

Load balancing has been a rough edge in our API since the beginning. If you send at any real volume, you’ve experienced the pain. You spread traffic across a pool of lines, watch for numbers that get throttled or flagged, and migrate conversations off the bad ones before your delivery rates fall. You track which chat lives on which line, and you keep a table of chat IDs so replies land in the right place. None of this is your actual product. It is undifferentiated work that every high-volume sender rebuilds. So we built it for you.

Here is how the two endpoints work and when to use each.

## The two endpoints

`GET /v3/available_number` tells you the best line to send from right now.

`POST /v3/messages` sends a message without asking you for a `from` number at all.

Most integrations only need the second endpoint. 

The first is there for the cases where you need a number to render before you send anything, like a click-to-text button or a contact card on a landing page.

## Getting a line to display: `available_number`

`available_number` returns the healthiest line in your pool at a point in time, in E.164 format. Health here is a function of internal line reputation plus rolling volume over the last hour and the last 24 hours.

```
curl https://api.linqapp.com/api/partner/v3/available_number \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY"
```

```json
{
  "phone_number": "+12025551234",
  "vcf_url": "https://s3.us-east-1.amazonaws.com/linq-attachments/vcf/9716d5c5/12025551234.vcf?X-Amz-Signature=..."
}
```

Two things to know about it.

It is advisory. The call does not reserve the line or change any selection state. If you want to guarantee a chat starts on the number you just got back, pass that `phone_number` as `from` when you create the chat. You can also pass a `to` set to the endpoint. When you do, and an existing chat with those recipients is already on a healthy line, the response reuses that line instead of picking a fresh one.

It also returns a `vcf_url`. That is a time-limited link to a vCard for the selected line. The card carries the line's name and photo, sets the selected number as the primary `TEL`, and lists your other healthy lines as backups. Share it so recipients can save the number as a contact. The backups matter later: if you have to move a recipient to a different line, the number is already in their contacts, so the transition doesn't look like a stranger texting them. The link expires, so call the endpoint again to mint a fresh one.

## Sending without a `from`: `POST /v3/messages`

This is the endpoint that removes the load balancing work. You give it recipients and a message. You do not give it a `from` number, and you do not give it a chat ID. It resolves both.

```
curl -X POST https://api.linqapp.com/api/partner/v3/messages \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": ["+12025550147"],
      "message": {
        "parts": [
          { "type": "text", "value": "Your table for 4 is confirmed for 7:30 tonight." }
        ]
      },
      "continuation_message": {
        "text": "Confirming your table for 4 at 7:30 tonight."
      }
    }'
```

`to` is an order-independent set of handles, either E.164 numbers or email addresses. One handle is a direct chat. Multiple handles is a group chat. The set identifies the chat, so you never look up or store a chat ID to continue a conversation.

The response tells you exactly what happened.

```json
{
  "chat_id": "b1c0a2d4-...",
  "created_new_chat": true,
  "from": "+12025551234",
  "from_selection": {
    "reason": "new_best_number",
    "reused_existing_chat": false
  },
  "is_group": false,
  "message": {
    "id": "9f3e...",
    "created_at": "2026-07-08T15:04:05Z",
    "delivery_status": "queued",
    "parts": [ ... ]
  }
}
```

The endpoint always responds `202 Accepted`. Chat creation is incidental to the send.

## How the line gets chosen

`from_selection.reason` reports which of three branches ran.

`reused_active_chat`. A chat with exactly these recipients already exists, and the line it lives on is healthy. The message goes into that chat on its existing line. This is what keeps a conversation on one number across many sends, so the whole exchange stays in a single thread for the recipient.

`new_best_number`. No chat exists for this recipient set. We create one on the best available line, using the same health and volume signals as `available_number`.

`failover_flagged`. A matching chat exists, but its line has been flagged and can no longer send. This is the case you used to handle by hand. We create a new chat on a fresh best line, abandon the flagged one, and set `previous_chat_id` on the response. If you supplied a `continuation_message`, its text is sent as the single message instead of `message`. That is the opener in the curl above. The recipient is now on a new number, so a short reintroduction usually reads better than replaying the original content. Exactly one message is sent on this branch either way. The `continuation_message` is ignored on the other two branches.

You do not choose the branch. You send the same request every time and read `reason` if you care what happened.

## Scaling and migration come for free

Add a line to your pool and it enters rotation automatically. You do not register it anywhere or change your send code. As your volume grows, more of the pool absorbs it. When a number degrades, failover moves new sends to a healthy line and, with `continuation_message`, does it with copy you wrote for that situation. You are no longer writing migration jobs.

## A few details worth knowing

The `message` object carries `parts` (text, media, or link), plus optional `effect`, `preferred_service` (`iMessage`, `RCS`, or `SMS`), `idempotency_key`, and `reply_to`. A text part goes up to 10,000 characters. A `link` part must be the only part in the message.

The first message on a chat may contain a link, including on a newly created chat. Be careful with it. Sending a link as the very first message on a freshly selected line raises that line's flagging risk. It is allowed, not recommended.

Voice memos are not supported here. To send an iMessage voice-memo bubble, use `POST /v3/chats/{chatId}/voicememo` with a known chat id.

Pass an `Idempotency-Key` header, or `message.idempotency_key`, to make retries safe.

## When to use it

If you run more than five lines, use both endpoints. Migration and load balancing are where most of the value is, and they only matter at scale. If you run one or two lines, `POST /v3/messages` is still worth adopting on its own. You stop managing chat IDs and stop maintaining separate create-chat and send-message calls. One endpoint creates the chat when it needs to and appends to the existing one when it can.

The reference docs are at [available\_number](https://docs.linqapp.com/api/resources/available_number/methods/retrieve) and [messages](https://docs.linqapp.com/api/resources/messages/methods/create).

Load balancing has moved from your code to ours. Two new endpoints handle line selection, health checks, failover, and number migration automatically.

Just hit send: Introducing managed load balancing 

Linq developers can now build **iMessage Apps**: interactive mini-apps that run inside a Messages conversation.

Users can shop, play games, date, book appointments, fill out forms, or complete other workflows without leaving the thread. There is no deep link to an external browser. There is no "tap here to finish in the app." The experience renders inside the bubble, where the conversation is already happening.

The thread is the most-used surface on the phone. Until now, the best API-level option was to drop a link into a conversation and hope the user followed it somewhere else. iMessage Apps remove that handoff. The action happens in the message.

## What you can build

An iMessage App is a tappable card that opens an interactive experience in place. Here are a few examples.

**Games.** Send a move, redraw the board, and run a full turn-based match inside the thread. Since a card can be updated in place, a live game session becomes a sequence of updates to the same bubble.

**Dating.** Profiles, prompts, and matches can live where people are already talking. The interaction stays in the conversation instead of sending the user back to a standalone app.

**Payments.** Send a checkout or request-to-pay as a card. The recipient can complete it in the thread, without a redirect or copied payment link.

**Tickets.** RSVPs, event passes, and order status can update as state changes. A card can move from "Going / Not going" to a confirmed ticket, or from *Reserved* to *Confirmed*, in the same bubble.

**Flight booking.** Surface a fare, let the user pick and confirm, then update the card to a boarding pass in the same conversation.

**Music.** Drop a track into the thread and let people play it inline. The card is a player, not a link to another app.

These are examples, not a fixed menu. If your product has an interactive moment, it can happen inside the message.

## How it works

iMessage Apps are sent as a new message **part** with `type: "imessage_app"`. This replaces the `text`, `media`, and `link` parts you already use.

The card becomes your app inside the bubble. An installed Messages extension draws rich, interactive content from a URL you provide.

### Sending a card

Send a card as the first message in a new chat with **Create Chat**, or post the same part into an existing chat with **Send Message**:

```bash
curl -X POST https://api.linqapp.com/api/partner/v3/chats \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+12052535597",
    "to": ["+12052532136"],
    "message": {
      "parts": [
        {
          "type": "imessage_app",
          "app": {
            "name": "Example App",
            "team_id": "A1B2C3D4E5",
            "bundle_id": "com.example.app.MessageExtension"
          },
          "url": "https://app.example.com/card?id=abc123",
          "fallback_text": "Open in Example App",
          "layout": {
            "caption": "Example App",
            "subcaption": "You said: hello"
          }
        }
      ]
    }
  }'
```

Three details matter before your first send.

### 1. The app identity is the rendering key

The `app` object, specifically `team_id` and `bundle_id`, tells Messages which extension renders the card. The card is drawn by that extension, so you usually pass your own app's identity.

`app_store_id` is optional. If you set it, recipients who do not have the app installed see a **Get the app** affordance.

One common failure mode: an unrecognized identity silently renders as plain text. If `team_id` and `bundle_id` do not match a Messages extension installed by the recipient, the card falls back to your caption text with no error. If your card only shows text, verify the identity against your shipping app.

### 2. You control captions; the app controls the image

The `layout` object defines the text you can put directly on the card:

| Field                 | Position                       |
| --------------------- | ------------------------------ |
| `caption`             | top-left, bold primary label   |
| `subcaption`          | left, below `caption`          |
| `trailing_caption`    | top-right                      |
| `trailing_subcaption` | right, below `trailing_caption` |

At least one field must be set, or the card renders as an empty bubble.

There is no image field. The photo, icon, and interactive UI come from your app's extension, drawn from the `url`. Messages treats the `url` as opaque. Your extension interprets it and renders from it. Change the `url` to change what the card shows.

If you need an image that everyone can see, regardless of whether they have your app installed, use a rich link or media attachment instead. That is a different tool.

Install state determines what the recipient sees:

| Recipient state | Result |
| ---------------- | ------ |
| Has your app | The extension renders a rich card from your `url`. |
| Does not have your app | The recipient sees your `layout` captions, plus the **Get the app** affordance if you set `app_store_id`. |

### 3. Cards update in place

A delivered card can be replaced in place by referencing the original message. This is the primitive behind a game move redrawing the board, or an order changing from *Reserved* to *Confirmed*.

```bash
curl -X POST https://api.linqapp.com/api/partner/v3/messages/{messageId}/update \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/card?game=7f3a&move=2",
    "fallback_text": "Score update",
    "layout": { "caption": "Score: 2 - 1" }
  }'
```

Rules to account for:

- The update replaces the delivered card instead of posting a second bubble.
- Only `url`, `fallback_text`, and `layout` can change.
- The app identity is fixed for the life of the card.
- The card must already be **delivered**.
- A `409` means you should retry after the `message.delivered` webhook.
- Each update is a **new message** with its own ID and lifecycle.
- To update the card again, reference the new message ID.

You can also receive cards. Inbound messages include an `imessage_app` part in the `message.received` webhook. Your handler can read the app identity, `url`, and `layout` from a card the user sends you.

## Constraints to plan around

iMessage App parts have stricter rules than other message parts.

- **iMessage only.** They never fall back to SMS or RCS.
- **No mixed fallback request.** If you request SMS or RCS alongside an iMessage App part, the send is rejected with `2018`.
- **Async failure for unreachable recipients.** If the recipient is not reachable over iMessage, the send is accepted and then fails asynchronously with a `4005` `message.failed` webhook. Check capability before sending.
- **Must be the only part.** An `imessage_app` part cannot be combined with `text`, `media`, or `link` in the same message.

## Get started

The full guide covers send, receive, update, webhooks, and capability checks:

**[docs.linqapp.com/guides/messaging/imessage-apps](https://docs.linqapp.com/guides/messaging/imessage-apps/)**

Give your agents an interactive surface inside iMessage, where users can complete workflows without leaving the conversation. This post covers how Linq developers can send, render, update, and receive iMessage app cards, with the constraints to plan around in production.

Supercharge Your Agents With iMessage Apps

Most messaging products treat group chats as larger 1:1 conversations. That misses the point. Group chats are where coordination happens: friends plan, matchmakers introduce people, concierges loop in vendors, and deals move forward. If you are building an agent for anything social or multi-party, the group thread is not a secondary feature. It is the product surface.

Linq's v3 API treats group chats as first-class objects over iMessage and RCS, with display names, icons, participant management, and webhooks for membership changes. This post covers what that makes possible, how to implement it, and the main product problem teams hit when they add an agent to a group: deciding when the agent should speak.

The examples at the end come from the open-source [Linq AI agent example](https://github.com/linq-team/ai-agent-example).

## Group chats need different product logic

A 1:1 agent has a simple turn-taking model. Every inbound message is addressed to the agent, so the agent replies to everything.

That assumption fails as soon as a third participant joins. In a group, most messages are humans talking to each other. The core product question changes from "what should the agent say?" to "should the agent say anything?"

That shift enables products that cannot work in a 1:1 thread.

**Matchmaking and introductions.** [Ditto](https://ditto.ai/) describes itself as "your college matchmaker." It learns your type, scans the pool, and texts you a ready-to-go date over iMessage. No swiping, no long pre-date chat. Ditto reports 12,000+ dates delivered, with 70% of users getting a first date within two days.

For a matchmaker, the natural next step is the introduction itself. Put both matches in a group thread, set the group photo to a custom date card, let the agent warm up the conversation, suggest a time and place, then step back. Ditto already describes an agentic system of expert agents for analysis, matchmaking, posting, and scheduling. The group thread is where the scheduler and concierge agents become useful.

**Concierge and coordination.** A travel or events agent can pull a customer, a vendor, and itself into one thread to handle logistics. The agent answers when asked, stays quiet while humans work through details, and returns to confirm the final plan.

**Group commerce and planning.** Splitting a bill, planning a trip, and coordinating a gift all need structured work inside a social conversation. The agent can handle totals, scheduling, reminders, and follow-ups without taking over the thread.

**Community and cohort bots.** A class, club, or founder cohort can have an assistant that answers direct questions and reacts to milestones without replying to every message.

All of these products depend on the same requirement: the agent has to be a good group chat participant. If it talks too much, people mute it. If it talks too little, it feels broken. If it replies to one person but ignores another asking the same thing, users lose trust.

That consistency is the engineering problem.

## Implementing group chats on Linq

The examples below use Linq's Partner v3 API. Full endpoint specs are in the [Chats API reference](https://docs.linqapp.com/api/resources/chats), and the [group chats guide](https://docs.linqapp.com/guides/chats/group-chats/) is the canonical source for current constraints.

### Create a group

A group chat is any conversation with three or more participants. Create one by sending the first message to multiple recipients:

```bash
curl -X POST https://api.linqapp.com/api/partner/v3/chats \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+12223334444",
    "to": ["+15556667777", "+18889990000"],
    "message": {
      "parts": [
        { "type": "text", "value": "Welcome to the group!" }
      ]
    }
  }'
```

Design around two constraints from the start:

- **No links in the first outbound message.** `link` parts and text parts containing URLs are rejected on `POST /v3/chats`. Send a clean opening message, then follow up with a [rich link preview](https://docs.linqapp.com/guides/messaging/rich-link-previews) using the returned chat ID. This matters for matchmaker and concierge flows, where the first instinct is often to lead with a link.
- **Recipient caps vary by delivery path.** The `to` array supports up to **31 recipients**, but SMS/MMS fallback depends on carriers. Most cap group texts around **20** recipients, and some go as low as **10**. Plan for the strictest path your message may take.

### Name it and give it an icon

Display names and icons are group-only. This is where a matchmaker can set a custom date card as the group photo, or a concierge can brand the thread:

```bash
curl -X PUT https://api.linqapp.com/api/partner/v3/chats/{chatId} \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Team Discussion",
    "group_chat_icon": "https://example.com/group-icon.png"
  }'
```

`group_chat_icon` must be a publicly accessible HTTPS URL. Calling this endpoint on a 1:1 chat returns [error `1006`](https://docs.linqapp.com/error/codes/1xxx/1006), because names and icons only apply to groups.

### Manage participants

Adding and removing participants is supported on **iMessage group chats only** today. The API enforces two rules:

- A group must always have **at least 3 members**. You cannot remove someone or leave yourself if that would drop the group below three.
- Leaving is one-way. Once your number leaves, you lose access unless an active participant adds you back. Recreating a chat with the same people creates a new, separate chat. A [`participant.removed`](https://docs.linqapp.com/api/resources/webhooks) webhook fires after the leave is processed.

See the [add](https://docs.linqapp.com/api/resources/chats/subresources/participants/methods/add) and [remove](https://docs.linqapp.com/api/resources/chats/subresources/participants/methods/remove) participant references for the full schema.

### Account for missing 1:1 features

Group chats do not support **typing indicators, delivery receipts, or read receipts**. If your 1:1 experience relies on "agent is typing..." or read state, use a different affordance in groups. Do not expect those events to fire.

### Wire up webhooks

Chat creation, group detail updates, and participant changes all fire [webhook events](https://docs.linqapp.com/guides/webhooks/events#chat-events). Your inbound message handler should branch on group vs. 1:1 from the first event, because the response logic is different.

## Making an agent consistent in a group

Teams usually frame group-chat inconsistency as an agent framework problem. A customer put it this way:

> "Our agent is struggling to be consistent in responding to all users. I think it's an agentic framework issue. Any tips with that, or resources?"

The better framing is architecture. The fix is to separate the decision to respond from the generation of the response.

### Why one model call fails

The naive design sends every inbound group message to the main model and asks it to decide whether to respond in the same call where it writes the reply.

That fails in predictable ways:

- **The behavior varies.** A generative model asked to judge and act in one pass will make that judgment differently across runs. Two people can ask the same thing, and the agent may answer one but ignore the other.
- **The agent talks too much.** Models are optimized to be helpful. They often reply to messages that were meant for another human.
- **It is slow and expensive.** Busy groups create many messages the agent should ignore. Running the full model on each one wastes latency and tokens.
- **It can loop.** Without an explicit action gate, agents can fall into reaction spirals like repeated tapbacks.

The root issue is that "should I respond?" and "what should I say?" have different cost, latency, and consistency requirements. They should not be handled by the same model call.

### Use a cheap classifier as the gate

Patrick Sullivan, Linq's CTO, solved this in the [open-source agent example](https://github.com/linq-team/ai-agent-example):

> "The way I solved it was to add in a simple, fast, cheap model to determine if it should be responding to a message."

The pipeline has two stages.

Stage one is a small, fast, cheap model, Claude Haiku, with one job: classify each incoming group message as `respond`, `react`, or `ignore`.

Stage two is the full Sonnet agent. It only runs when the stage-one verdict is `respond` or `react`. The expensive model no longer decides whether to speak. It only runs after the system has already decided that speaking is appropriate.

The classifier makes a narrow, repeated judgment in about 20 output tokens. That makes it cheaper, faster, and easier to tune than the main agent.

Here is the classifier, lightly trimmed from [`src/claude/client.ts`](https://github.com/linq-team/ai-agent-example/blob/c4d10a72e7397f1d1d7be8f9a67261bd6f674072/src/claude/client.ts#L745):

```ts
export type GroupChatAction = 'respond' | 'react' | 'ignore';

export async function getGroupChatAction(
  message: string,
  sender: string,
  chatId: string
): Promise<{ action: GroupChatAction; reaction?: Reaction }> {
  // Pull the last few messages so the classifier has context
  const history = await getConversation(chatId);
  const recentMessages = history.slice(-4); // last 2 exchanges
  const contextBlock = /* format recent messages with sender handles */;

  const response = await client.messages.create({
    model: 'claude-haiku-4-5',          // fast and cheap, not the main agent model
    max_tokens: 20,                      // it only needs to emit one short verdict
    system: `You classify how an AI assistant "Claude" should handle messages in a group chat.

IMPORTANT: BIAS TOWARD "respond" - text responses are almost always better than reactions.
Only use "react" for very brief acknowledgments where a text response would be awkward.

Answer with ONE of these:
- "respond" - Claude should send a text reply. USE THIS BY DEFAULT when:
  * They asked Claude anything
  * They mentioned Claude (or misspelled it - cluade, cloude, cladue, claud, etc.)
  * They mentioned "AI", "bot", "assistant", or "Sullivan"
  * They're talking to Claude or continuing a conversation
  * It's a follow-up to Claude's message
  * You're unsure - default to respond
- "react:love" | "react:like" | "react:laugh" - ONLY for brief acknowledgments where text
  would be weird (a simple "thanks!" or "lol"). Do NOT overuse reactions.
- "ignore" - Human-to-human conversation not involving Claude at all

ANTI-REACTION-LOOP: If you see reactions in recent context, prefer "respond" to break the pattern.
MISSPELLING TOLERANCE: People typo "Claude" as cluade, cloude, claud, ckaude. Treat as a mention.

Examples:
- "hey claude what's the weather" -> respond
- "cluade what do u think"        -> respond   (misspelling!)
- "that's cool claude"            -> respond   (engage, don't just react)
- "thanks!"                       -> react:love
- "yo mike you coming tonight?"   -> ignore`,
    messages: [{
      role: 'user',
      content: `${contextBlock}New message from ${sender}: "${message}"\n\nHow should Claude handle this?`
    }],
  });

  // Parse the one-word verdict into an action and optional reaction
  const answer = response.content[0].type === 'text'
    ? response.content[0].text.toLowerCase().trim() : 'ignore';

  if (answer.includes('respond')) return { action: 'respond' };
  if (answer.includes('react'))   return { action: 'react', reaction: /* parse love/like/laugh */ };
  return { action: 'ignore' };
}
```

The inbound webhook handler then becomes a simple gate:

```ts
if (chatContext.isGroupChat) {
  const { action, reaction } = await getGroupChatAction(message, sender, chatId);

  if (action === 'ignore') return;                 // stay silent; most messages land here
  if (action === 'react')  return sendReaction(reaction); // cheap acknowledgment, no generation

  // action === 'respond': only now do we run the full agent
}
const reply = await chat(chatId, message, /* images, audio, context */);
```

### Why the gate works

This pattern works because it gives each model a smaller job.

**Separation of concerns reduces variance.** A narrow classifier with a fixed three-way output and concrete examples is more consistent than a general model making the same judgment while generating a reply. The behavior becomes an explicit, testable decision boundary.

**It is a routing cascade.** A cheap model handles the high-volume case and escalates only when needed. In a busy group, most messages are `ignore`, so the system avoids most frontier-model calls.

**The gate is independently tunable.** If the agent should be chattier, bias the classifier toward `respond`. If it is too noisy, tighten the criteria. You can change turn-taking behavior without editing the main agent prompt or tools. You can also unit-test the classifier against labeled messages, which is much harder to do with an open-ended generation prompt.

**It stops reaction loops early.** Anti-reaction-loop behavior belongs in the gate, before generation starts. The classifier can see recent reactions and choose `respond` or `ignore` instead of continuing the loop.

### Add sender attribution

Group consistency also depends on knowing who said what. In a 1:1 thread, "the user" is clear. In a group, the model needs names or handles.

The same repo prefixes each stored user message with the sender's handle before formatting history for the model:

```ts
function formatHistoryForClaude(messages, isGroupChat) {
  return messages.map(msg => {
    let content = msg.content;
    // In group chats, prefix user messages with who sent them
    if (isGroupChat && msg.role === 'user' && msg.handle) {
      content = `[${msg.handle}]: ${content}`;
    }
    return { role: msg.role, content };
  });
}
```

The system prompt also needs group-specific guidance: address people by name, keep replies shorter because groups move quickly, react less often because reactions can feel spammy, and remember that everyone can see the response.

The classifier decides whether to participate. Attribution helps the main agent participate competently.

## Production shape

A production Linq group-chat agent usually follows this flow:

1. **Inbound webhook** receives a new message and branches on `isGroupChat`.
2. **Gate** runs the Haiku classifier and returns `respond`, `react`, or `ignore`. Most messages stop here.
3. **Generate** runs the Sonnet agent only for `respond`, with sender-attributed history and a group-aware system prompt.
4. **Act** through the API: send the reply, set the group name or icon, add or remove participants, while respecting the 3-member floor and iMessage-only participant management.
5. **Listen** for participant webhooks and keep local state in sync.

The reference implementation is MIT-licensed and runnable: [github.com/linq-team/ai-agent-example](https://github.com/linq-team/ai-agent-example). To try it on a real Linq number across iMessage, RCS, and SMS with about a week of limited usage, request sandbox access at [dashboard.linqapp.com/sandbox-signup](https://dashboard.linqapp.com/sandbox-signup/).

For Ditto-style social agents, the group thread is the core product surface. Treat "should I respond?" as a separate, cheaper decision from "what should I say?" Once those jobs are split, the agent becomes more consistent because the architecture matches the conversation.

### Sources

- Linq docs: [Group Chats guide](https://docs.linqapp.com/guides/chats/group-chats/)
- Linq AI agent example: [repo](https://github.com/linq-team/ai-agent-example) and [`client.ts` classifier](https://github.com/linq-team/ai-agent-example/blob/c4d10a72e7397f1d1d7be8f9a67261bd6f674072/src/claude/client.ts#L745)
- [Ditto](https://ditto.ai/): AI matchmaker over iMessage


Linq's v3 API treats group chats as first-class objects over iMessage and RCS, with display names, icons, participant management, and webhooks for membership changes. This post covers what that makes possible, how to implement it, and the main product problem teams hit when they add an agent to a group: deciding when the agent should speak.

Building AI Agents That Work in Group Chats

Today we're announcing that Linq is an official vendor adapter for [Chat SDK](https://chat-sdk.dev/) — Vercel's open-source TypeScript framework for building bots and agents across every major chat platform.

That means you can now build an AI agent that texts over iMessage, RCS, and SMS — using the same unified API you'd use to build a Slack bot, a Discord bot, or a Teams integration.

## What is Chat SDK?

Chat SDK is a platform-agnostic, event-driven SDK for building chat bots. It abstracts away the differences between Slack, Microsoft Teams, Google Chat, Discord, WhatsApp, and more — so you write your bot logic once and it runs anywhere.

With 1.4M weekly downloads, 2.1K GitHub stars, and 15+ adapters, it's become the standard toolkit for teams building AI-native chat experiences. It's maintained by Vercel and integrates natively with [AI SDK](https://ai-sdk.dev/) for streaming, tool calls, and structured outputs.

## What the Linq adapter adds

With `@linqapp/chat-sdk-adapter`, your Chat SDK bot gains iMessage, RCS, and SMS as delivery channels. Linq's infrastructure handles the carrier layer — your code just sees threads, messages, and reactions like any other Chat SDK adapter.

A few things worth calling out:

**Native iMessage tapbacks.** Tapbacks (like, love, laugh, emphasize, question) map to normalized Chat SDK reaction events, so your `bot.onReaction()` handlers work exactly as they would on Slack.

**Rich media support.** Inbound attachments (images, audio, files) arrive as Chat SDK attachment objects. Outbound files under 10MB are sent by URL reference; larger files up to 100MB are pre-uploaded automatically.

**HMAC-verified webhooks with replay protection.** Every inbound webhook is verified with HMAC-SHA256 and a replay-window check before dispatch. Invalid or stale signatures return 401.

**Stable thread IDs.** Every Linq chat maps to a stable `linq:{chatId}` thread ID across webhook events and API calls, so conversations don't fragment.

## How it works

Install the adapter alongside Chat SDK:

```sh
npm install @linqapp/chat-sdk-adapter chat
```

Wire it up in your bot:

```ts
import { Chat } from "chat";
import { createLinqAdapter } from "@linqapp/chat-sdk-adapter";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    linq: createLinqAdapter({
      apiKey: process.env.LINQ_API_KEY,
      signingSecret: process.env.LINQ_WEBHOOK_SECRET,
    }),
  },
});

bot.onDirectMessage(async (thread, message) => {
  await thread.subscribe();
  await thread.post(`you said: ${message.text}`);
});
```

Then add a webhook route (Next.js example):

```ts
import { after } from "next/server";
import { bot } from "@/lib/bot";

export const runtime = "nodejs";

export async function POST(request: Request) {
  return bot.webhooks.linq(request, {
    waitUntil: (task) => after(() => task),
  });
}
```

Point a Linq webhook at your route and you're live — see the [quickstart guide](https://docs.linqapp.com/guides/integrations/chat-sdk/) for full setup instructions. For local dev, the [Linq CLI](https://www.npmjs.com/package/@linqapp/cli) provisions a sandbox number instantly:

```sh
linq signup
```

## Running a bot across iMessage, WhatsApp, and Telegram — from one codebase

Because Chat SDK is platform-agnostic, adding Linq as an adapter means your existing multi-platform bot logic just works. The [example app in our repo](https://github.com/linq-team/linq-chat-sdk/tree/main/apps/api) shows a single AI agent running across Linq, Telegram, and WhatsApp from one set of handlers — no branching, no per-platform glue.

## A community effort

This integration wouldn't have shipped as fast without [Fardeem Munir](https://x.com/FardeemM), a developer in the Linq community who reached out on Twitter and volunteered his time to help build it. Open source at its best — thanks, Fardeem.

## Get started

- **npm:** [`@linqapp/chat-sdk-adapter`](https://www.npmjs.com/package/@linqapp/chat-sdk-adapter) (Apache-2.0)
- **Docs:** [chat-sdk.dev/adapters/vendor-official/linq](https://chat-sdk.dev/adapters/vendor-official/linq)
- **Source:** [github.com/linq-team/linq-chat-sdk](https://github.com/linq-team/linq-chat-sdk)


Today we're announcing that Linq is an official vendor adapter for Chat SDK, Vercel's open-source TypeScript framework for building bots and agents across every major chat platform.

Linq is now a vendor-official adapter for Vercel's Chat SDK

By betting on iMessage as the channel and Linq as the infrastructure, Tomo built a deeply personal AI product for young people and scaled it from a single phone line to hundreds of thousands of messages through organic growth alone.

Tomo is a personalized AI that lives inside iMessage. It understands users' goals, affirms them, and helps them find ways to achieve those goals. The name means "friend" in Japanese, and there's a friendliness to the product that's core to why it works. Most of Tomo's users are between 15 and 24 years old, and if you try using it, the experience is, as the founders put it, "aggressively Gen Z coded."

Behind that experience is a messaging infrastructure challenge that required the right partner. With Linq, Tomo found a provider that matched their standards on reliability and security, and then kept pace as organic growth pushed their volume from a single phone line to hundreds of thousands of messages.

## From Retool to Tomo

Justin and Raymond, Tomo's co-founders, met while working together at Retool in San Francisco. About a couple of years ago, they left to start separate companies. Justin wanted to build something fun enough for a lot of people to use. Raymond wanted to build something practical with wide-scale impact on real people.

They spent about a year and a half exploring different areas before reuniting around a shared conviction: they wanted to build consumer AI products together.

> "My goal has always been to build for impact and actually deliver value to people. I think what's exciting about Tomo is just seeing that in real time." — Raymond, Co-founder

The result was Tomo: an AI that understands the user's goals, why they care about those goals, and helps them take action. It lives entirely inside iMessage, meeting young users in the app they already use every day.

![The Tomo team](https://res.cloudinary.com/linq/image/upload/v1772835185/website/Customer%20Story/Tomo/Frame_1597881371_kixvg0.png)

## Betting on iMessage

The decision to build on iMessage was straightforward. Tomo's target audience, 15-to-24-year-olds, lives inside the app. People chat a hundred times a day in a space where ten close friends and family members are already texting. For this demographic, anything other than a blue bubble feels like spam.

> "It doesn't take a rocket scientist to know that iMessage is so overpowered. It's almost so overpowered that it's difficult, because you can have a product that isn't really working, but you might think it's working just because iMessage is just so good." — Justin, Co-founder

That power cut both ways. iMessage distribution was a massive advantage, but it also meant they needed infrastructure they could trust completely. The channel was too important to get wrong.

## From building it themselves to finding Linq

Tomo's engineering team was confident. They had phones from other projects, strong technical chops, and the conviction that they could build iMessage infrastructure in-house. They got something working quickly. But it didn't last.

They evaluated providers across multiple companies. The conclusion was clear: the folks at Linq were the best people for the job. The evaluation criteria came down to security, latency, reliability, and price. But above all, Tomo optimized for reliability.

> "You can build a lot of trust for users over 2,000 messages, but it only takes two or three message failures, or even just one, to break that trust."

## When users start caring about privacy, you're winning

Tomo's users share deeply personal information through the product. The things they use Tomo for — their goals, their struggles, their daily lives — are hyper personal. That creates a real obligation around data security, and it makes compliance like SOC 2 matter in practice, not just on paper.

What surprised the team was an emerging signal they didn't expect. As users went deeper into the product, they started asking about data privacy. Not because something went wrong, but because they'd shared so much that the question became personal.

![Tomo on iMessage](https://res.cloudinary.com/linq/image/upload/v1773084933/website/Customer%20Story/Tomo/Tomo_phone_esv06s.jpg)

## From a single phone line to hundreds of thousands of messages

Tomo launched with a single phone line. The first users were the founders themselves, testing with friends, watching hundreds of messages flow through each day, and asking the fundamental question: does this thing have legs?

It did. When the team started promoting on TikTok and Instagram Reels, where their users actually live, demand took off. Through it all, the Linq team kept pace. Five months in, they went from hundreds of messages a day to hundreds of thousands.

## Engagement and retention that finally work

Justin and Raymond have built many consumer products before. But Tomo is the first time they've seen engagement and retention levels where things are clearly starting to work.

The team is now focused on making Tomo more helpful and fun to use with friends. One example: group chats — currently a hidden feature that only the most curious users have discovered, but one the team sees as a natural extension of the product.

## What's next

Tomo's story is still early. The team sees a massive opportunity to scale the product's impact across millions of people, and they're hiring across growth, ops, and engineering to get there. The infrastructure that Linq provides — reliable, secure, and able to scale on demand — is what lets them focus on the product instead of the plumbing.

> "The folks at Linq have always been super gracious and helpful and super responsive. That's been the case whenever we've needed to grow." — Justin, Co-founder, Tomo

How Tomo built a deeply personal AI for young people on iMessage and scaled it from a single phone line to hundreds of thousands of messages on Linq infrastructure — through organic growth alone.

Tomo: How a Personalized AI for Accountability Scaled to Millions of Messages

By treating iMessage as their primary UI and choosing Linq for security, zero data retention, and on-demand scalability, the team behind Poke built a product that scaled entirely through word of mouth — without ever worrying about infrastructure.

The Interaction Company of California builds Poke, a consumer product that treats iMessage as its primary interface. Users don't download an app. They chat. What started as a tool for managing email inside iMessage has evolved into something much broader: a conversational AI that people use for school, daily planning, and personal support.

Founded by Felix and Marvin, two German immigrants who moved to the Bay Area to start a company, the team knew from the beginning that iMessage was the channel. The question was who to trust with the infrastructure that would make it work.

> "We are treating iMessage and SMS as our first-party UI for interacting with our product. That's a space that not very many other companies work in." — Felix, Co-founder

With Linq, the team found the infrastructure partner that made that bet possible and kept pace as organic growth pushed their messaging volume through multiple orders of magnitude.

## Building a product thesis around iMessage

The original idea was straightforward: build something that triggers on every email notification, summarizes the important ones, and lets users act on them without opening an email client. But the team quickly realized people didn't want another email interface. They wanted to interact with email inside the messaging app they already used a hundred times a day.

Samyok, a Member of Technical Staff at the company, joined after interning at Robinhood and Jane Street. He'd been trying to figure out what to do after his last semester when he saw Poke's product thesis in action.

> "When I saw this opportunity, I saw that this product thesis actually works. I decided to join and take a bet. And so far it's paid off really well." — Samyok, Member of Technical Staff

As adoption grew, the team discovered that email was just a fraction of what people used Poke for. Users connected all sorts of services. They used it for school. They used it to chat when they had problems. The product had taken on a life of its own.

![Inside Poke](https://res.cloudinary.com/linq/image/upload/v1772820868/website/Customer%20Story/Poke/CleanShot_2025-09-22_at_09.28.23_1_dkabty.png)

## A waitlist that felt like the product

When it came time to launch, the team faced a constraint: high inference costs meant they had to restrict access. But they didn't want a simple waitlist. Instead, they built something that lived inside the same channel as the product itself.

Users chatted with Poke's bot in iMessage, tried to convince it to give them access, and simultaneously haggled for a good price. The waitlist wasn't a gate. It was a preview of the entire product experience.

## Finding a provider that checked every box

Treating iMessage as a primary UI meant the messaging provider wasn't just infrastructure. It was the product. The team's evaluation criteria reflected that. Functionality came first, then security, then price. They needed SOC 2 compliance, zero data retention, and a provider they could trust.

They searched extensively. Other providers surfaced, but none met the full requirements. Some lacked SOC 2. Others couldn't support zero data retention. Some were significantly more expensive.

> "We did a ton of searching, and we only found Linq to be able to fit all three of these criteria."

The stakes were made viscerally clear before the team even found Linq. While using a previous messaging provider, Poke's messages were flagged as spam. The provider blocked all of Poke's messages for every user, on the day the company closed its fundraise. The experience underscored why the right provider wasn't optional. It was existential.

## Going live with Linq, and building together

Implementation was fast. The team added Linq as a provider with minimal lift, and the first phone line was up and running quickly. But what made the relationship distinctive was what came after onboarding.

Linq built zero data retention specifically for the team, and maintained a tight feedback loop, shipping features in direct response to requests. When someone casually mentioned a Find My location feature, Linq had it done within a week.

![Poke product in action](https://res.cloudinary.com/linq/image/upload/v1772836605/website/Customer%20Story/Poke/Poke_phone_zgsv4m.jpg)

## Scaling through word of mouth, without worrying about infrastructure

The team started in April with a single phone line and a small test group. Growth came in waves: first one line, then around twenty, then hundreds right before launch. Every expansion was driven by organic demand.

Within days of joining the Linq platform, the team was processing ten thousand messages in a single day. From their perspective, the experience was seamless. "It feels like a cloud provider," they say. "We can request a large number of numbers, and you guys just accommodate everything and get it done within a couple of days."

## Launch night

For Felix, the most memorable moment of the past year was launch night. The team pulled an all-nighter. It was hectic. And then the next day, the numbers spiked alongside a wave of positive user feedback that the team says they'll never be able to recreate.

## Infrastructure that lets a team focus on what matters

The team has scaled through multiple orders of magnitude since joining Linq. Instead of planning around infrastructure constraints, the team focuses on product and growth: expanding use cases beyond email and building new interaction models.

> "It feels like a cloud provider. Every time we put in a new order for more capacity, Linq just scales with us. I think there are a lot of other providers on all parts of our infrastructure that would not be able to keep up." — Felix, Co-founder, The Interaction Company of California

How The Interaction Company of California scaled iMessage-based AI with Linq — zero data retention, SOC 2 compliance, and on-demand scalability that kept pace with viral, word-of-mouth growth.

Just hit send: Introducing managed load balancing

Latest Posts

Just hit send: Introducing managed load balancing

Supercharge Your Agents With iMessage Apps

Building AI Agents That Work in Group Chats

Linq is now a vendor-official adapter for Vercel's Chat SDK

Tomo: How a Personalized AI for Accountability Scaled to Millions of Messages

How Poke Scaled Messaging

Linq Blog

Just hit send: Introducing managed load balancing

Latest Posts

Just hit send: Introducing managed load balancing

Supercharge Your Agents With iMessage Apps

Building AI Agents That Work in Group Chats

Linq is now a vendor-official adapter for Vercel's Chat SDK

Tomo: How a Personalized AI for Accountability Scaled to Millions of Messages

How Poke Scaled Messaging