# iMessage guide

> **Coming soon.** Bring-your-own iMessage is not yet accepting apps — `POST /api/v1/channels/apps` with `platform: "imessage"` answers `501 coming_soon` today. The guide below describes the flow that will open up, so you can prepare your Linq account.

> iMessage rides the Linq partner API: bring your Linq account's number and end users text a real iMessage identity you own.

## Prerequisites

- A **Linq** account with a provisioned iMessage number — its partner **API key**, the **phone number**, and a **webhook secret** for the subscription you'll point at us.
- An AgentSky API token with write scope.

## Register the channel app

```bash
curl -s -X POST https://agentsky.dev/api/v1/channels/apps \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"platform": "imessage", "label": "My number", "credentials": {"api_key": "...", "phone_number": "+15551234567", "webhook_secret": "..."}}'
# -> setup: { "webhook_url": "https://.../webhooks/imessage/app_..." }
```

Linq has no webhook-registration API, so point your Linq webhook subscription at `setup.webhook_url`, signed with the same secret you stored — deliveries are verified per app.

## Connect

```bash
curl -s -X POST https://agentsky.dev/api/v1/channels/connections \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"platform": "imessage", "app": "app_...", "destination": {"session": "sess-..."}}'
```

The response carries an `sms:` deep link and a `LINK:` code; texting the code to your number claims the connection.

## Capabilities

| threads | reactions | markers | proactive | markdown | modals | ephemeral | streaming |
|---|---|---|---|---|---|---|---|
| ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ |

Outbound markdown is flattened to plain text (link labels keep their targets in parens) and long messages are chunked rather than truncated.

## Troubleshooting

- **Webhook deliveries answer 401** — the subscription's secret doesn't match the stored `webhook_secret`, or the signed timestamp is stale; Linq signatures are only accepted within a short freshness window.
- **Replies land as a new conversation** — Linq's per-conversation chat ids can shift; the service re-learns them from every inbound automatically.
- **The LINK code does nothing** — codes expire with the connect link (15 minutes); mint a new connection.