@telnyx/chat-sdk-adapter is the official Telnyx adapter for the Vercel Chat SDK — Vercel’s TypeScript framework for building chatbots that work across Slack, Microsoft Teams, Discord, Telegram, WhatsApp, email, and now SMS/MMS through Telnyx. Write bot logic once and route messages through any supported channel.
The adapter is maintained by Telnyx at team-telnyx/telnyx-chat-sdk-adapter and listed as a vendor-official adapter on chat-sdk.dev/adapters.
When to use this adapter: building an AI- or rules-driven SMS bot inside a Next.js app and wanting the same handler API you already use for other chat platforms. For general-purpose, high-volume messaging outside a Chat SDK app, use the Telnyx Messaging API directly.
Prerequisites
- A Telnyx account with a messaging-enabled phone number (E.164 format)
- A Messaging Profile with a webhook URL configured
- Your Telnyx v2 API key
- The Ed25519 Public Key from the messaging profile (for webhook signature verification)
- Node.js
>=18
Install
@chat-adapter/state-memory for development, @chat-adapter/state-redis for production:
Quick start
chat.webhooks.telnyx:
https://<your-domain>/api/webhooks/telnyx.
Configuration
Environment variables
TelnyxAdapterConfig
Recommended: Dedicated messaging profile
Create a dedicated Messaging Profile for each bot and pass its ID asmessagingProfileId. We recommend prefixing the profile name with [Chat SDK] (for example, [Chat SDK] support-bot-prod) so it’s easy to find in Mission Control and in usage reports.
A dedicated profile gives you:
- Per-profile usage analytics, so bot traffic is separated from the rest of your account
- Per-profile spend limits, which cap bot spend without affecting other workloads
- An isolated webhook URL and failover URL
- An isolated Ed25519 public key — the one you pass as
publicKeybelongs to the profile, not the account
Webhook setup
1
Open your messaging profile
In the Telnyx Mission Control portal, open the messaging profile you created for the bot.
2
Set the webhook URL
Under Inbound Settings, set the Webhook URL to your server’s endpoint (for example,
https://bot.example.com/api/webhooks/telnyx). Set Webhook API version to 2.3
Copy the Public Key
Under Messaging → Security, copy the Public Key for the profile. Pass it as
publicKey (or set TELNYX_PUBLIC_KEY). Telnyx shows this key in base64; the adapter accepts it as-is.4
Assign a phone number
Assign one or more phone numbers to the profile. The number you set as
TELNYX_FROM_NUMBER must belong to this profile.telnyx-signature-ed25519 and telnyx-timestamp headers. Requests with a timestamp older than 300 seconds, or with an invalid signature, are rejected with 401.
Capabilities
Thread model
A thread is a pair of E.164 phone numbers. The thread ID format istelnyx:<bot-number>:<user-number>, for example telnyx:+15551234567:+15559876543. openDM(phoneNumber) returns the thread ID for a given recipient so you can post proactively.
Attribution
Outbound messages carry two ecosystem-observability signals:User-Agentheader on every outbound API call:@telnyx/chat-sdk-adapter/<version> (vercel-chat-sdk).tagson every outbound message:["vercel-chat-sdk", "vercel-chat-sdk:<version>"], merged with any user-supplied tags.
message.sent, message.finalized, message.received) in the data.payload.tags field. User-supplied extraTags are merged after the attribution tags. Set disableAttributionTags: true to opt out; extraTags is unaffected.
Pair with the Telnyx AI SDK provider
Use this adapter alongside@telnyx/ai-sdk-provider — the Telnyx provider for the Vercel AI SDK — to build a full AI-powered SMS agent on Telnyx inference. The Chat SDK handles message I/O; the AI SDK handles LLM, embeddings, and speech. One account, one API key, two packages.