Telnyx TypeScript API Library

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.

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);

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:

... View full README on GitHub