Telnyx

Official TypeScript library for the Telnyx API

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "telnyx-2": {
      "command": "npx",
      "args": [
        "-y",
        "telnyx-2"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Telnyx TypeScript API Library

npm bundle size

This library provides convenient access to the Telnyx REST API from server-side TypeScript or JavaScript.

The full API of this library can be found in api.md.

It is generated with Stainless.

MCP Server

Use the Telnyx MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.

Note: You may need to set environment variables in your MCP client.

Installation

Terminal

npm install telnyx

Usage

The full API of this library can be found in api.md.

server.ts

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.calls.dial({
  connection_id: 'conn12345',
  from: '+15557654321',
  to: '+15551234567',
  webhook_url: 'https://your-webhook.url/events',
});

console.log(response.data);

Examples

Runnable examples are available for:

Search for and order a phone number

server.ts

const { data: availableNumbers } = await client.availablePhoneNumbers.list({
  filter: {
    country_code: 'US',
    national_destination_code: '312',
    limit: 1,
  },
});

const phoneNumber = availableNumbers?.[0]?.phone_number;
if (!phoneNumber) throw new Error('No phone numbers found');

const { data: order } = await client.numberOrders.create({
  phone_numbers: [{ phone_number: phoneNumber }],
});

Send an SMS

server.ts

const { data: message } = await client.messages.send({
  from: '+15551234567',
  to: '+15557654321',
  text: 'Hello from Telnyx!',
});

Start a Call Control call

server.ts

const { data: call } = await client.calls.dial({
  connection_id: 'your-connection-id',
  from: '+15551234567',
  to: '+15557654321',
  webhook_url: 'https://example.com/webhooks',
});

Verify an inbound webhook

Configure the client with your Telnyx public key and pass the exact raw request body to unwrap. Parsing or re-serializing the body before verification invalidates the signature.

server.ts

const webhookClient = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
  publicKey: process.env['TELNYX_PUBLIC_KEY'],
});

const event = webhookClient.webhooks.unwrap(rawBody, {
  headers: requestHeaders,
});

See the complete Express webhook verification example for raw-body handling and error responses.

Configure retries

Connection failures and retryable HTTP responses are retried twice by default. Set maxRetries for the client or override it for an individual request:

server.ts

const retryingClient = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
  maxRetries: 4,
});

await retryingClient.messages.send(
  {
    from: '+15551234567',
    to: '+15557654321',
    text: 'Hello from Telnyx!',
  },
  { maxRetries: 0 },
);

See Handling errors and Retries for details.

Request & Response types

This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:

server.ts

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const params: Telnyx.NumberOrderCreateParams = {
  phone_numbers: [{ phone_number: '+15558675309' }],
};
const numberOrder: Telnyx.NumberOrderCreateResponse = await client.numberOrders.create(params);

Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.

File uploads

Request parameters that correspond to file uploads can be passed in many different forms:

File (or an object with the same structure)
a fetch Response (or an object with the same structure)
an fs.ReadStream
the return value of our toFile helper

server.ts

import fs from 'fs';
import Telnyx, { toFile } from 'telnyx';

const client = new Telnyx();

// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: fs.createReadStream('/path/to/file'),
});

// Or if you have the web `File` API you can pass a `File` instance:
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: new File(['my bytes'], 'file'),
});

// You can also pass a `fetch` `Response`:
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: await fetch('https://somesite/file'),
});

// Finally, if none of the above are convenient, you can use our `toFile` helper:
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: await toFile(Buffer.from('my bytes'), 'file'),
});
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: await toFile(new Uint8Array([0, 1, 2]), 'file'),
});

Handling errors

When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of APIError will be thrown:

server.ts

const numberOrder = await client.numberOrders
  .create({ phone_numbers: [{ phone_number: '+15558675309' }] })
  .catch(async (err) => {
    if (err instanceof Telnyx.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });

Error codes are as follows:

Status Code	Error Type
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`
N/A	`APIConnectionError`

Retries

Certain errors will be automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default.

You can use the maxRetries option to configure or disable this:

server.ts

// Configure the default for all requests:
const client = new Telnyx({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await client.numberOrders.create({ phone_numbers: [{ phone_number: '+15558675309' }] }, {
  maxRetries: 5,
});

Timeouts

Requests time out after 1 minute by default. You can configure this with a timeout option:

server.ts

// Configure the default for all requests:
const client = new Telnyx({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.numberOrders.create({ phone_numbers: [{ phone_number: '+15558675309' }] }, {
  timeout: 5 * 1000,
});

On timeout, an APIConnectionTimeoutError is thrown.

Note that requests which time out will be retried twice by default.

Auto-pagination

List methods in the Telnyx API are paginated. You can use the for await … of syntax to iterate through items across all pages:

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Telnyx

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "telnyx": { "command": "npx", "args": ["-y", "telnyx"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/telnyx-2?style=directory)](https://allmcps.com/mcp/telnyx-2)

HTML Embed

<a href="https://allmcps.com/mcp/telnyx-2"><img src="https://allmcps.com/api/badge/telnyx-2?style=directory" alt="Telnyx on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

25Quality signal: Emerging · 25/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools10/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Telnyx →Install in Claude Desktop Install in Cursor Install in VS Code

Telnyx

Official TypeScript library for the Telnyx API

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "telnyx-2": {
      "command": "npx",
      "args": [
        "-y",
        "telnyx-2"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Telnyx TypeScript API Library

npm bundle size

This library provides convenient access to the Telnyx REST API from server-side TypeScript or JavaScript.

The full API of this library can be found in api.md.

It is generated with Stainless.

MCP Server

Note: You may need to set environment variables in your MCP client.

Installation

Terminal

npm install telnyx

Usage

The full API of this library can be found in api.md.

server.ts

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.calls.dial({
  connection_id: 'conn12345',
  from: '+15557654321',
  to: '+15551234567',
  webhook_url: 'https://your-webhook.url/events',
});

console.log(response.data);

Examples

Runnable examples are available for:

Search for and order a phone number

server.ts

const { data: availableNumbers } = await client.availablePhoneNumbers.list({
  filter: {
    country_code: 'US',
    national_destination_code: '312',
    limit: 1,
  },
});

const phoneNumber = availableNumbers?.[0]?.phone_number;
if (!phoneNumber) throw new Error('No phone numbers found');

const { data: order } = await client.numberOrders.create({
  phone_numbers: [{ phone_number: phoneNumber }],
});

Send an SMS

server.ts

const { data: message } = await client.messages.send({
  from: '+15551234567',
  to: '+15557654321',
  text: 'Hello from Telnyx!',
});

Start a Call Control call

server.ts

const { data: call } = await client.calls.dial({
  connection_id: 'your-connection-id',
  from: '+15551234567',
  to: '+15557654321',
  webhook_url: 'https://example.com/webhooks',
});

Verify an inbound webhook

Configure the client with your Telnyx public key and pass the exact raw request body to unwrap. Parsing or re-serializing the body before verification invalidates the signature.

server.ts

const webhookClient = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
  publicKey: process.env['TELNYX_PUBLIC_KEY'],
});

const event = webhookClient.webhooks.unwrap(rawBody, {
  headers: requestHeaders,
});

See the complete Express webhook verification example for raw-body handling and error responses.

Configure retries

Connection failures and retryable HTTP responses are retried twice by default. Set maxRetries for the client or override it for an individual request:

server.ts

const retryingClient = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
  maxRetries: 4,
});

await retryingClient.messages.send(
  {
    from: '+15551234567',
    to: '+15557654321',
    text: 'Hello from Telnyx!',
  },
  { maxRetries: 0 },
);

See Handling errors and Retries for details.

Request & Response types

This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:

server.ts

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const params: Telnyx.NumberOrderCreateParams = {
  phone_numbers: [{ phone_number: '+15558675309' }],
};
const numberOrder: Telnyx.NumberOrderCreateResponse = await client.numberOrders.create(params);

Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.

File uploads

Request parameters that correspond to file uploads can be passed in many different forms:

File (or an object with the same structure)
a fetch Response (or an object with the same structure)
an fs.ReadStream
the return value of our toFile helper

server.ts

import fs from 'fs';
import Telnyx, { toFile } from 'telnyx';

const client = new Telnyx();

// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: fs.createReadStream('/path/to/file'),
});

// Or if you have the web `File` API you can pass a `File` instance:
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: new File(['my bytes'], 'file'),
});

// You can also pass a `fetch` `Response`:
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: await fetch('https://somesite/file'),
});

// Finally, if none of the above are convenient, you can use our `toFile` helper:
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: await toFile(Buffer.from('my bytes'), 'file'),
});
await client.ai.audio.transcribe({
  model: 'distil-whisper/distil-large-v2',
  file: await toFile(new Uint8Array([0, 1, 2]), 'file'),
});

Handling errors

When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of APIError will be thrown:

server.ts

const numberOrder = await client.numberOrders
  .create({ phone_numbers: [{ phone_number: '+15558675309' }] })
  .catch(async (err) => {
    if (err instanceof Telnyx.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });

Error codes are as follows:

Status Code	Error Type
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`
N/A	`APIConnectionError`

Retries

You can use the maxRetries option to configure or disable this:

server.ts

// Configure the default for all requests:
const client = new Telnyx({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await client.numberOrders.create({ phone_numbers: [{ phone_number: '+15558675309' }] }, {
  maxRetries: 5,
});

Timeouts

Requests time out after 1 minute by default. You can configure this with a timeout option:

server.ts

// Configure the default for all requests:
const client = new Telnyx({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.numberOrders.create({ phone_numbers: [{ phone_number: '+15558675309' }] }, {
  timeout: 5 * 1000,
});

On timeout, an APIConnectionTimeoutError is thrown.

Note that requests which time out will be retried twice by default.

Auto-pagination

List methods in the Telnyx API are paginated. You can use the for await … of syntax to iterate through items across all pages:

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Telnyx

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "telnyx": { "command": "npx", "args": ["-y", "telnyx"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/telnyx-2?style=directory)](https://allmcps.com/mcp/telnyx-2)

HTML Embed

<a href="https://allmcps.com/mcp/telnyx-2"><img src="https://allmcps.com/api/badge/telnyx-2?style=directory" alt="Telnyx on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

25Quality signal: Emerging · 25/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools10/30

Adoption & activity1/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Telnyx →Install in Claude Desktop Install in Cursor Install in VS Code