Telnyx

Telnyx TypeScript API Library

))](https://npmjs.org/package/telnyx)

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

npm install telnyx

Usage

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

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:

• Searching available phone numbers
• Sending messages
• Receiving messaging webhooks
• Verifying webhook signatures
• Call Control
• AI, addresses, and connections

Search for and order a phone number

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

const { data: message } = await client.messages.send({

from: '+15551234567', to: '+15557654321', text: 'Hello from Telnyx!', });

Start a Call Control call

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.

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.

Mint a WebRTC login token locally

A WebRTC client logs in with a token for a telephony credential. Instead of asking the API for one per login (createToken), your backend can sign it itself from the credential's token_material, with no request to Telnyx per token:

// Once, when the user is set up: create the credential and ask for the signing material.

const { data: credential } = await client.telephonyCredentials.create({ connection_id: '1234567890', include: 'token_material', }); // Store these with the user, server side: the token is built from all of them. await db.save(userId, { id: credential.id, user_id: credential.user_id, sip_username: credential.sip_username, expires_at: credential.expires_at, token_material: credential.token_material, });

// On every login, with no request to Telnyx: const loginToken = await client.telephonyCredentials.toJwt(credential, { ttl: 3600 }); // or later, from the stored values: const loginTokenFromStore = await client.telephonyCredentials.toJwt(await db.load(userId), { ttl: 3600 });

The API returns token_material only when include: 'token_material' is passed. For a credential created without it, or retrieved later, toJwt fetches the material once with retrieveTokenMaterial. token_material is as sensitive as the SIP password: keep it on the server. See the WebRTC login token example.

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:

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:

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

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:

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:

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:

// 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:

// 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:

async function fetchAllAccessIPAddressResponses(params) {

const allAccessIPAddressResponses = []; // Automatically fetches more pages as needed. for await (const accessIPAddressResponse of client.accessIPAddress.list({ 'page[number]': 1, 'page[size]': 50, })) { allAccessIPAddressResponses.push(accessIPAddressResponse); } return allAccessIPAddressResponses; }

Alternatively, you can request a single page at a time:

let page = await client.accessIPAddress.list({ 'page[number]': 1, 'page[size]': 50 });

for (const accessIPAddressResponse of page.data) { console.log(accessIPAddressResponse); }

// Convenience methods are provided for manually paginating: while (page.hasNextPage()) { page = await page.getNextPage(); // ... }

Advanced U