Skip to main content
@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

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:
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

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 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:
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 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

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 that points at your public endpoint. The adapter exports INKBOX_CHAT_EVENTS, the full list of events it handles:
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 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:
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:
agent/channels/inkbox.ts
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 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.