> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat SDK adapter

> Use the Inkbox Chat SDK adapter to receive email, SMS, iMessage, Slack, A2A and call transcripts as chat messages and reply on the same channel.

`@inkbox/chat-sdk-adapter` connects an Inkbox identity's conversations to the TypeScript [Chat SDK](https://chat-sdk.dev/docs). Signed Inkbox webhooks become Chat SDK messages, and replies go back out on the channel and conversation the message came from.

Use the adapter when your application needs Inkbox as a conversation transport, with inbound delivery and outbound replies. It does not need an MCP connection. To give an agent callable Inkbox tools instead, see [Connect with MCP](https://inkbox.ai/docs/mcp-server.md). You can use the adapter directly with Chat SDK or with Eve's Chat SDK channel bridge.

## Prerequisites

* Node.js 22 or later. Use Node.js 26 for Eve.
* Chat SDK (`chat`) 4.45 or later within major version 4.
* An existing identity and an identity-scoped [API key](https://inkbox.ai/docs/api-keys.md) for that identity. The adapter rejects organization-wide keys.
* The identity's webhook [signing secret](https://inkbox.ai/docs/signing-keys.md).
* A persistent Chat SDK state backend, such as Redis, shared by every process that handles the application's conversations.
* A public HTTPS endpoint for incoming webhooks.

## Install

```bash theme={null}
npm install @inkbox/chat-sdk-adapter chat @chat-adapter/state-redis
```

The adapter and `@inkbox/sdk` release with matching versions. Install the SDK separately only when your application uses its other APIs.

## Quick start

Create the adapter, register it with Chat SDK, and mount the webhook handler:

```ts theme={null}
import { Chat } from "chat";
import { createRedisState } from "@chat-adapter/state-redis";
import { createInkboxAdapter, type InkboxMessage } from "@inkbox/chat-sdk-adapter";

const inkbox = createInkboxAdapter({
  apiKey: process.env.INKBOX_API_KEY!,
  agentHandle: process.env.INKBOX_AGENT_HANDLE!,
  signingSecret: process.env.INKBOX_SIGNING_SECRET!,
  onMessage: (message) => !(message.route.channel === "slack" && message.isBot === true),
});

const bot = new Chat({
  userName: "assistant",
  adapters: { inkbox },
  concurrency: "queue",
  state: createRedisState({
    url: process.env.REDIS_URL!,
    keyPrefix: `inkbox:${process.env.INKBOX_AGENT_HANDLE!}`,
  }),
});

bot.onNewMention(async (thread, message) => {
  await thread.subscribe();
  const route = (message.raw as InkboxMessage).route;
  if (route.channel === "voice") {
    await thread.setState({ lastCall: { id: message.id, text: message.text } });
    return;
  }
  await inkbox.send(thread.id, "Hello from Inkbox.", {
    idempotencyKey: `reply:${message.id}`,
    ...(route.channel === "email" ? { replyToMessageId: message.id } : {}),
    ...(route.channel === "a2a" ? { a2aTaskId: route.taskId } : {}),
  });
});

// Mount at a public HTTPS endpoint using your framework's Fetch API support.
export function POST(request: Request) {
  return bot.webhooks.inkbox(request);
}
```

Register the same handler with `bot.onSubscribedMessage` to answer follow-ups in conversations you already subscribed to. `concurrency: "queue"` makes overlapping inputs wait instead of being dropped while a handler is busy. The `onMessage` check rejects Slack messages from bots to avoid automated reply loops.

Pass the original request body to `bot.webhooks.inkbox` without parsing or reserializing it. If your host provides `waitUntil`, pass it through with `bot.webhooks.inkbox(request, { waitUntil })`.

## Supported channels

| Channel | Incoming context | Replies |
| - | - | - |
| Email | Message, thread, body, attachments | Reply-all within the existing email thread |
| SMS/MMS | Conversation, sender, text, media | Text and media in the same conversation |
| iMessage | Conversation, sender, text, media, reply thread | Text and media, supported reactions and typing |
| Slack | Conversation, thread, and file attachments | Text or one file per post, message edits and deletes, reactions |
| A2A | Context conversation, incoming task, and message parts | Explicit task-bound reply |
| Voice | Completed-call transcript | SMS or iMessage follow-up in a matching conversation |

WhatsApp is not supported. Use `@inkbox/sdk` directly for tunnels, vault, and other resources that are not conversations.

You cannot edit or unsend email and phone messages through the adapter. Typing indicators do nothing on channels that do not support them. Other unsupported operations throw an error. Streamed replies (`thread.post(stream)`) are buffered and sent as one completed message.

### Call transcripts

The adapter delivers a `call.ended` transcript as a normal incoming message when the call has a transcript and exactly one matching direct conversation:

* Calls on a dedicated phone number route to SMS on that number.
* Calls on a shared or dedicated iMessage number route to an active iMessage conversation with the caller.

Your application can then send a text follow-up after the call. The adapter does not provide realtime call audio.

The conversation must already have message history. A call alone does not create a messaging destination. Calls without a transcript, with no or several matching conversations, or with additional connected parties arrive on a `voice` thread as observations. You cannot reply on a `voice` thread.

### Voice notes

Inkbox transcribes MMS and iMessage voice notes automatically. Voice-note handling requires adapter version `0.7.40` or later. When an attachment's transcription is still pending, the adapter waits up to 60 seconds for the signed `message.transcription_finished` webhook. If it does not arrive, the adapter reads the original message once, with a 10-second limit.

Your handler then receives the original message once, not a second turn:

* `message.text` contains the typed caption followed by one label per voice note. A transcribed note appears as `[Voice note 2 — automatically transcribed]` with the transcript on the next line.
* A completed recording with no speech appears as `[Voice note 2: no speech detected]`.
* When transcription fails, the label says the transcript is unavailable and the original attachment remains for normal processing.
* The original attachments stay on the message.
* `message.raw.text` keeps only the typed caption.
* `message.raw.voiceNotes` lists each audio attachment's result with `attachmentId`, one-based `position`, `status`, `text`, and `errorCode`.

Treat transcribed speech as content from the sender, not as approval to perform privileged actions. WhatsApp voice notes are not delivered through the adapter, because it has no WhatsApp channel. See [Audio transcription notifications](https://inkbox.ai/docs/webhooks.md#audio-transcription-notifications) for the underlying webhook.

### A2A replies

An A2A thread covers one context, so several tasks in the same context share a conversation. Each incoming message carries its own task ID in `message.raw.route.taskId`. Always pass that task ID when you reply:

```ts theme={null}
const route = (message.raw as InkboxMessage).route;
if (route.channel === "a2a") {
  await inkbox.send(thread.id, "The result is ready.", {
    a2aTaskId: route.taskId,
    a2aIntent: "complete",
  });
}
```

`thread.post()` fails on A2A threads because it has no task binding. The adapter checks that the task belongs to the context and the receiving identity before it replies.

The default intent is `"progress"`, which leaves the task open. Set `a2aIntent` to `"ask_caller"`, `"complete"`, or `"fail"` for the matching task transition. Completing one task does not close the context or other tasks. See [Agent-to-Agent](https://inkbox.ai/docs/capabilities/a2a.md) for task states.

### Email replies

Pass the triggering message ID as `replyToMessageId` when you reply to an email. It controls the reply-all recipients. The adapter refuses an email send without it when the thread's recipients make the audience ambiguous.

## Configuration

| Option | Description |
| - | - |
| `apiKey` | Identity-scoped Inkbox API key, or a sync or async function that returns it |
| `agentHandle` | Handle of the existing identity that receives and sends messages |
| `signingSecret` | Webhook signing secret, or a sync or async function that returns it |
| `onMessage` | Optional sync or async admission hook. Return `false` to ignore an input. |
| `defaultA2AIntent` | Intent for task-bound A2A replies that do not set `a2aIntent`. Defaults to `"progress"`. |

`onMessage` runs before the adapter loads full message content, so email text can still be a truncated preview. Use it for admission based on event metadata, not for authorization decisions.

Use a separate state key prefix for each application or identity. In-memory state loses subscriptions and replay state on restart.

### Idempotent sends

Pass a stable `idempotencyKey` to `inkbox.send` when you may retry an outbound operation. Each call to `thread.post()` is a new send operation. For SMS/MMS and iMessage sends with media, retries with the same key reuse the same prepared payload and media URLs, even after a restart. Reusing a key with different text or attachments is rejected.

## Subscribe to webhook events

Create an identity-owned [webhook subscription](https://inkbox.ai/docs/webhooks.md#one-subscription-across-channels) that points at your public endpoint. The adapter exports `INKBOX_CHAT_EVENTS`, the full list of events it handles:

```ts theme={null}
import { Inkbox } from "@inkbox/sdk";
import { INKBOX_CHAT_EVENTS } from "@inkbox/chat-sdk-adapter";

const client = new Inkbox({ apiKey: process.env.INKBOX_API_KEY! });
const identity = await client.getIdentity(process.env.INKBOX_AGENT_HANDLE!);

const subscription = await client.webhooks.subscriptions.create({
  agentIdentityId: identity.id,
  url: "https://example.com/api/inkbox",
  eventTypes: [...INKBOX_CHAT_EVENTS],
});
```

When the identity has no signing key yet, the response includes a one-time `signingKey`. Store it in your secret manager as the adapter's signing secret. If the identity already has a key, use your existing copy. Rotating it affects every subscription on the identity.

A subscription does not provision a mailbox, phone number, Slack connection, or call configuration. Enable the channels you want on the identity separately.

`INKBOX_CHAT_EVENTS` includes `message.transcription_finished` from adapter version `0.7.40`. If you created a subscription with an earlier version, add that event to the same endpoint's subscription. The [Chat SDK example](https://github.com/inkbox-ai/inkbox/tree/main/examples/chat-sdk) setup script adds it to a subscription that has exactly the previous default events and leaves custom subscriptions unchanged.

## Recover pending voice notes

Pending voice notes need persistent Chat state shared by every process. The adapter saves the pending original message in that state before the webhook returns success, even when you do not pass `waitUntil`.

Schedule a signed recovery request to your own webhook endpoint every minute, including when no messages arrive. Run it in a trusted recurring job:

```ts theme={null}
import { createVoiceNoteRecoveryRequest } from "@inkbox/chat-sdk-adapter";

const response = await fetch(createVoiceNoteRecoveryRequest(webhookUrl, signingSecret));
if (!response.ok) throw new Error(`Recovery failed: HTTP ${response.status}`);
```

The job delivers saved originals after a restart or a missing `message.transcription_finished` webhook. The request waits for dispatch, so allow time for the remaining 60-second wait, the 10-second lookup, and your handler. Without the job, a quiet host cannot guarantee delivery when the wait times out. Memory-only state cannot recover after a restart.

Use the stable message ID to make your handler idempotent. A crash after an external effect but before the adapter records completion can replay that effect.

## Use with Eve

Eve's `chatSdkChannel` bridge routes Inkbox conversations into durable Eve sessions. Register the adapter in an Eve channel file, such as `agent/channels/inkbox.ts`:

```ts title="agent/channels/inkbox.ts" theme={null}
import { createInkboxAdapter } from "@inkbox/chat-sdk-adapter";
import { createRedisState } from "@chat-adapter/state-redis";
import { chatSdkChannel } from "eve/channels/chat-sdk";

const inkbox = createInkboxAdapter({
  apiKey: () => process.env.INKBOX_API_KEY!,
  agentHandle: process.env.INKBOX_AGENT_HANDLE!,
  signingSecret: process.env.INKBOX_SIGNING_SECRET!,
});

export const { bot, channel, send } = chatSdkChannel({
  userName: "inkbox-assistant",
  adapters: { inkbox },
  state: createRedisState({
    url: process.env.REDIS_URL!,
    keyPrefix: `inkbox-eve:${process.env.INKBOX_AGENT_HANDLE!}`,
  }),
  concurrency: "concurrent",
  streaming: false,
});

export default channel;
```

Then register `bot.onNewMention` and `bot.onSubscribedMessage` handlers that forward each message to the Eve session with `send`. The channel mounts at `POST /eve/v1/inkbox`, so point your webhook subscription at that path on your deployment. `streaming: false` sends completed replies, because email and phone messages cannot be edited after they are sent.

For voice-note recovery, set `INKBOX_WEBHOOK_URL` to your app's own `/eve/v1/inkbox` URL. The Eve example includes a `voice-notes` schedule that sends the signed recovery request to that route every minute. Run it on a deployment that supports one-minute Eve schedules. `eve dev` does not fire cron schedules automatically.

The [Eve example](https://github.com/inkbox-ai/inkbox/tree/main/examples/eve-agent) shows the complete channel, including A2A task binding and approval prompts. The [Chat SDK example](https://github.com/inkbox-ai/inkbox/tree/main/examples/chat-sdk) shows a framework-neutral handler and subscription setup.

To give an Eve agent Inkbox tools instead of a conversation channel, see [Vercel and Eve](https://inkbox.ai/docs/integrations/vercel-eve.md).

## Related

* [Webhooks](https://inkbox.ai/docs/webhooks.md)
* [Signing keys](https://inkbox.ai/docs/signing-keys.md)
* [API keys](https://inkbox.ai/docs/api-keys.md)
* [Chat SDK documentation](https://chat-sdk.dev/docs)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.