Getting started

A US SMS number for your Vercel project

The Telnyx integration gives your Vercel project a US phone number for sending and receiving SMS. It creates a Telnyx account for your Vercel team, assigns a number after a one-time identity check, and adds the number and an API key to your project as environment variables. You pay with prepaid credit that you buy in Vercel.

Want a working app first? Deploy the Telnyx SMS template. It adds Telnyx to a new project and comes with a send form and a signed inbound route.

Prefer to let a coding agent set it up? Use a coding agent.

Before you start

1Add Telnyx

1. In Vercel, open Integrations, find Telnyx in the Marketplace and select Install. Or select Deploy on the template, which installs Telnyx for you.
2. Choose SMS Phone Number (US) and the Pay as you go plan, and add at least $10 of credit. You can turn on auto-recharge here too.
3. Optionally enter a US area code, like 415. Leave it blank to get any available US number. You can also set your own inbound webhook URL and a failover URL. Most people leave these blank and let the integration set the webhook when they connect a project.
4. Accept the Telnyx terms and create the resource.

Your card is charged for the credit straight away. The phone number comes after the identity check.

2Verify your identity

On the Telnyx integration page in Vercel, select Open in Telnyx. The Telnyx dashboard opens and you're signed in with your Vercel account. A Vercel team admin selects Start identity check, takes a photo of a government ID (passport, driver's license or ID card), then takes a selfie. It takes about 3 minutes. Onfido runs the check for Telnyx.

Most checks finish within a few minutes. A manual review can take up to 24 hours. When the check passes, Telnyx assigns your number automatically, usually in under a minute, and adds TELNYX_PHONE_NUMBER to the resource in Vercel. If the check isn't accepted, you can try again with a clearer photo of a valid ID, or contact support.

3Connect a project and redeploy

In Vercel, open the phone number resource and select Connect Project. Pick the project and the environments that should get the variables. If you didn't set a webhook URL yourself, the integration points incoming texts at https://<your production domain>/api/telnyx/inbound and tells you in Vercel.

Then redeploy. Environment variables added or changed after a deployment only take effect on the next one. If you connected the project before the identity check passed, redeploy again once the number is assigned.

Environment variables

The integration adds these to every project you connect:

Send a text

Send with POST https://api.telnyx.com/v2/messages. No SDK is needed. Put this behind your own authentication: anyone who can call it can spend your balance.

// app/api/send/route.ts
export async function POST(req: Request) {
  // Add your own auth first: every text is paid from your prepaid balance.
  const { to, text } = await req.json();
  const res = await fetch("https://api.telnyx.com/v2/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      from: process.env.TELNYX_PHONE_NUMBER,
      to, // a US number in E.164 format, like +14155550123
      text,
    }),
  });
  return Response.json(await res.json(), { status: res.status });
}

Or from a terminal, with the variables pulled by vercel env pull:

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"from\":\"$TELNYX_PHONE_NUMBER\",\"to\":\"+14155550123\",\"text\":\"Hello from Vercel\"}"

Until your 10DLC campaign is approved, texts to US mobile phones are blocked by the carriers. Texts to other US Telnyx numbers work straight away.

Receive texts

Telnyx sends incoming texts and delivery receipts to TELNYX_MESSAGING_WEBHOOK_URL, signed with Ed25519. This route checks the signature, rejects anything older than five minutes and logs the text:

// app/api/telnyx/inbound/route.ts
import crypto from "node:crypto";

// DER header for a raw Ed25519 public key
const SPKI = Buffer.from("302a300506032b6570032100", "hex");

function verify(raw: string, sig: string | null, ts: string | null) {
  const key = process.env.TELNYX_PUBLIC_KEY;
  if (!key || !sig || !ts) return false;
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  try {
    const pub = crypto.createPublicKey({
      key: Buffer.concat([SPKI, Buffer.from(key, "base64")]),
      format: "der",
      type: "spki",
    });
    return crypto.verify(null, Buffer.from(`${ts}|${raw}`), pub, Buffer.from(sig, "base64"));
  } catch {
    return false;
  }
}

export async function POST(req: Request) {
  const raw = await req.text();
  const ok = verify(
    raw,
    req.headers.get("telnyx-signature-ed25519"),
    req.headers.get("telnyx-timestamp"),
  );
  if (!ok) return new Response("invalid signature", { status: 401 });

  const { data } = JSON.parse(raw);
  if (data.event_type === "message.received") {
    console.log("text from", data.payload.from.phone_number, data.payload.text);
  }
  // message.sent and message.finalized are delivery receipts for your sends.
  return Response.json({ ok: true });
}

• Answer within 2 seconds. Otherwise Telnyx retries, and then tries the failover URL if you set one.
• The same event can arrive twice. Skip events whose data.id you have already handled.
• Text your number from any phone, in any country. The message reaches your route straight away, even before 10DLC registration.

Use a coding agent

The telnyx-vercel-sms agent skill tells a coding agent how to install Telnyx with the Vercel CLI, wire up sending and receiving, and handle 10DLC and common errors. Install it in your project:

npx skills add team-telnyx/telnyx-vercel-sms-template --skill telnyx-vercel-sms

Then give your agent this prompt:

Add a Telnyx US SMS number to this project using the Vercel CLI.

1. Use the telnyx-vercel-sms skill. If it isn't installed, run
   `npx skills add team-telnyx/telnyx-vercel-sms-template --skill telnyx-vercel-sms`
   or read https://github.com/team-telnyx/telnyx-vercel-sms-template/blob/main/skills/telnyx-vercel-sms/SKILL.md
2. Find the integration with `vercel integration discover telnyx` and check the
   plan and options with `vercel integration add telnyx/phone-number --help`.
3. Link this directory with `vercel link`, then run
   `vercel integration add telnyx/phone-number --billing-plan telnyx-prepaid`.
   If the CLI stops with a link to accept terms or add credit, give me the link,
   wait for me, then run the next command it suggests.
4. Ask me to complete the identity check (`vercel integration open telnyx`) and wait
   until TELNYX_PHONE_NUMBER is set.
5. Make sure the number is connected to this project, run `vercel env pull .env.local`,
   and read `vercel integration guide telnyx --framework nextjs`.
6. Add a send route protected by auth, and a signed inbound route at
   app/api/telnyx/inbound, as the skill describes. Deploy to production, then help me
   check that sending and receiving work.

The agent can't accept the terms, pay or do the identity check for you. It stops and asks when it's your turn.

Register to text US phones (10DLC)

US carriers only deliver texts from registered business numbers. The registration is called 10DLC. Open Telnyx from Vercel and go to Messaging.

1. Register your brand, the business that sends the messages: legal company name, EIN (US federal tax ID), address and website. It costs a one-time $4.50 and usually takes a few minutes.
2. Submit a campaign that describes your messages: the use case, sample messages, how people opt in, and your opt-out and help replies. The campaign fee is shown before you submit.
3. Telnyx reviews it, usually in 1 to 3 business days. This review is free.
4. The carriers review it, in about 3 business days. Telnyx charges the campaign fee to your balance when it sends the campaign to the carriers.
5. Once approved, your numbers are added to the campaign automatically and can text US phones within minutes. Numbers you add later are added too.

Most rejections are about the website and the opt-in wording, not the form. The Messaging page lists what carriers check, with text you can copy. Telnyx's 10DLC compliance guide has the details.

Costs, balance and refunds

• Phone number: $1.00 a month, charged when ordered and then monthly.
• SMS: from $0.004 per message part, plus US carrier fees.
• 10DLC: $4.50 once for the brand, plus a monthly campaign fee shown before you submit.

All prices are public Telnyx rates, paid from your prepaid balance. One balance covers all the numbers in an installation. Vercel shows the balance and your usage, updated hourly. Below $5 you get a warning in Vercel, and texts stop when the balance reaches $0. Add funds or turn on auto-recharge on the resource in Vercel.

Refunds of unused credit aren't automatic. Email support@telnyx.com to ask for one.

Rotate the API key

If TELNYX_API_KEY leaks, open the number in the Telnyx dashboard and select Rotate (Vercel team admins only). The new key goes to your connected projects; redeploy to use it. The old key keeps working for 24 hours so nothing breaks in the meantime.

Remove a number or uninstall

Deleting the phone number resource in Vercel releases the number and revokes its API key. You can't get the same number back.

Uninstalling Telnyx from your Vercel team releases every number, revokes the keys, deactivates your 10DLC campaign so its monthly fee stops, and closes the Telnyx account. Ask support about unused credit before you uninstall.

Support

Telnyx support is available 24 hours a day, 7 days a week. Select Support on the integration in Vercel, or open Telnyx and go to Support. Select Copy support details and paste them into an email to support@telnyx.com, so support can find your account straight away. For 10DLC questions, email 10dlcquestions@telnyx.com.

More on the Telnyx API: sending messages, receiving webhooks and 10DLC.