@getdial/chat-sdk-adapter

Wire a real phone number into your Chat SDK bot. The same onNewMention handler that answers Slack, Teams, or Discord now answers SMS, MMS, iMessage, and inbound voice calls too — with replies sent back over the phone through Dial.

npm install @getdial/chat-sdk-adapter chat

import { Chat } from "chat";
import { createDialAdapter } from "@getdial/chat-sdk-adapter";

const chat = new Chat({
  adapter: createDialAdapter(),  // reads DIAL_* env vars; overridable — see Options
  onNewMention: async ({ message, reply }) => {
    await reply(`heard you: ${message.text}`);
  },
});

// Bind to whatever HTTP framework you use:
app.post("/webhook/dial", (req) => chat.webhooks.dial(req));

Get a Dial API key and a phone number ID from https://getdial.ai. Point that number's webhook subscription at the endpoint above.

What the adapter carries

| Direction | Channel | Text | Media | |-----------|--------------|------|-------| | Inbound | SMS | ✅ | — | | Inbound | MMS | ✅ | ✅ (image / video / audio / file) | | Inbound | iMessage | ✅ | ✅ | | Inbound | Voice call | ✅ (as transcript) | — | | Outbound | SMS / MMS / iMessage | ✅ | ✅ (via attachment URLs) |

Configuration

createDialAdapter(config?) reads the environment when a field is omitted. Explicit values always win.

| Field | Env var | Required | What it is | |-----------------|------------------------|:--------:|------------| | apiKey | DIAL_API_KEY | ✅ | Dial API key (sk_live_…) minted from the dashboard. | | fromNumberId | DIAL_FROM_NUMBER_ID | ✅ | Dial's ID of the phone number the bot should send from. | | webhookSecret | DIAL_WEBHOOK_SECRET | ✅ in prod | Signing secret Dial issued when the webhook subscription was created. When set, incoming requests are verified against X-Dial-Signature; when unset, verification is skipped (dev only). | | apiBaseUrl | DIAL_API_URL | | Overrides the Dial API host. Defaults to https://api.getdial.ai. | | botName | BOT_USERNAME | | Display name Chat SDK uses for the bot. Defaults to "bot". | | logger | — | | Chat SDK Logger instance. Defaults to ConsoleLogger("info").child("dial"). |

Webhook events

Point the Dial webhook subscription at the endpoint you handed to chat.webhooks.dial. Four event types are recognized (envelope shape mirrors Dial's own emitter):

| Event | Response | |----------------------|----------| | message.received | Forwarded to the bot as a chat message. Media items become Chat SDK attachments (image / video / audio / file, keyed off contentType). | | call.ended (inbound) | Swallowed — 200 OK, not forwarded. Bots only see voice as the transcript delivered by the subsequent call.transcribed; a "call ended" placeholder here would hold the Chat SDK per-thread lock and starve the real transcript event. Very short calls that never get a transcript therefore don't surface to the bot at all. | | call.ended (outbound) | Dropped — 200 OK, not forwarded. Adapter surface is inbound-only. | | call.transcribed | Fetches the call via @getdial/sdk.getCall(). Forwarded as a voice message only when direction === "inbound". | | webhook.ping | 200 OK. Not forwarded — this is Dial's dashboard "test delivery" button. |

Anything else is answered 200 OK and ignored, so a future Dial event type doesn't break integrations before they upgrade.

Signature verification

When webhookSecret is set, every request must carry:

X-Dial-Signature: t=<unix_seconds>,v1=<hex-hmac-sha256(secret, `${t}.${rawBody}`)>

Rejection cases (all 401):

| Verdict | When | |-------------|------| | missing | No X-Dial-Signature header on the request. | | malformed | Header lacks t= or v1=, or t= is not a number. | | stale | abs(now - t) exceeds 5 minutes. Replay protection. | | mismatch | Recomputed HMAC doesn't equal v1, or lengths differ. Constant-time compare. |

Structurally invalid JSON, or an envelope with no type, returns 400.

Threads

A thread here is a pair of phone numbers — your Dial-owned number and the peer's:

dial:{yourDialNumber}:{peerNumber}

Every distinct pair is a distinct thread. Chat SDK's per-thread state (conversation history, context) is scoped per-pair, so simultaneous conversations don't leak into each other.

Design notes

• @getdial/sdk under the hood. Outbound sends and transcript fetches go through the official Node SDK; no hand-rolled HTTP.
• Node's crypto for signing. createHmac + timingSafeEqual, matching the exact primitive Dial's server signs with.
• Package is ESM-only, TypeScript-first. Requires Node 18+.
• No business logic in the adapter. It's a transport shim — your bot logic lives entirely in the Chat SDK handlers.

Links

• Dial: getdial.ai · docs
• Chat SDK: chat-sdk.dev