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

Also install a state adapter — @chat-adapter/state-memory for development, @chat-adapter/state-redis for production:

Quick start

In your webhook route handler, forward the request to chat.webhooks.telnyx:
Point your messaging profile’s webhook URL at https://<your-domain>/api/webhooks/telnyx.

Configuration

Environment variables

TelnyxAdapterConfig


Create a dedicated Messaging Profile for each bot and pass its ID as messagingProfileId. 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 publicKey belongs 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 MessagingSecurity, 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.
Incoming webhooks are validated against the 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 is telnyx:<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:
  1. User-Agent header on every outbound API call: @telnyx/chat-sdk-adapter/<version> (vercel-chat-sdk).
  2. tags on every outbound message: ["vercel-chat-sdk", "vercel-chat-sdk:<version>"], merged with any user-supplied tags.
These tags appear in Telnyx webhook event payloads (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.

Resources