@inkbox/chat-sdk-adapter connects an Inkbox identity’s conversations to the TypeScript Chat SDK. 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. 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 for that identity. The adapter rejects organization-wide keys.
- The identity’s webhook signing secret.
- 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
@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: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
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 acall.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.
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 version0.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.textcontains 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.textkeeps only the typed caption.message.raw.voiceNoteslists each audio attachment’s result withattachmentId, one-basedposition,status,text, anderrorCode.
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 inmessage.raw.route.taskId. Always pass that task ID when you reply:
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 for task states.
Email replies
Pass the triggering message ID asreplyToMessageId 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
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 stableidempotencyKey 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 that points at your public endpoint. The adapter exportsINKBOX_CHAT_EVENTS, the full list of events it handles:
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 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 passwaitUntil.
Schedule a signed recovery request to your own webhook endpoint every minute, including when no messages arrive. Run it in a trusted recurring job:
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’schatSdkChannel bridge routes Inkbox conversations into durable Eve sessions. Register the adapter in an Eve channel file, such as agent/channels/inkbox.ts:
agent/channels/inkbox.ts
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 shows the complete channel, including A2A task binding and approval prompts. The Chat SDK example shows a framework-neutral handler and subscription setup.
To give an Eve agent Inkbox tools instead of a conversation channel, see Vercel and Eve.

