telnyx

Telnyx TypeScript API ライブラリ

このライブラリを使用すると、サーバーサイドの TypeScript または JavaScript から Telnyx REST API に簡単にアクセスできます。

このライブラリの API 全体については、api.md をご覧ください。

Stainless を使用して生成されています。

MCP サーバー

Telnyx MCP サーバーを使用すると、AI アシスタントがこの API を操作できるようになります。エンドポイントの確認、テストリクエストの実行、ドキュメントの利用によって、アプリケーションへのこの SDK の統合を支援できます。

注：MCP クライアントで環境変数を設定する必要がある場合があります。

インストール

npm install telnyx

使用方法

このライブラリの API 全体については、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);

例

実行可能な例は次のとおりです。

• 利用可能な電話番号の検索
• メッセージの送信
• メッセージ受信 Webhook
• Webhook 署名の検証
• Call Control
• AI、住所、接続

電話番号を検索して注文する

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 }],
});

SMS を送信する

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

Call Control の通話を開始する

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

受信 Webhook を検証する

Telnyx の公開鍵を使用してクライアントを設定し、unwrap に変更していないリクエスト本文を渡してください。検証前に本文を解析したり再シリアライズしたりすると、署名が無効になります。

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

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

生の本文の処理とエラーレスポンスについては、Express Webhook 検証の完全な例をご覧ください。

リトライを設定する

接続エラーとリトライ可能な HTTP レスポンスは、デフォルトで 2 回リトライされます。クライアントに maxRetries を設定するか、個々のリクエストで上書きしてください。

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

詳細については、エラーの処理とリトライをご覧ください。

リクエストとレスポンスの型

このライブラリには、すべてのリクエストパラメーターとレスポンスフィールドの TypeScript 定義が含まれています。次のようにインポートして使用できます。

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

各メソッド、リクエストパラメーター、レスポンスフィールドのドキュメントは docstring に記載されており、ほとんどの最新エディターでホバーすると表示されます。

ファイルのアップロード

ファイルのアップロードに対応するリクエストパラメーターには、さまざまな形式を渡せます。

• File（または同じ構造のオブジェクト）
• fetch の Response（または同じ構造のオブジェクト）
• fs.ReadStream
• toFile ヘルパーの戻り値

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'),
});

エラーの処理

ライブラリが API に接続できない場合、 または API が成功以外のステータスコード（4xx または 5xx のレスポンス）を返した場合、 APIError のサブクラスがスローされます。

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

エラーコードは次のとおりです。

ステータスコード	エラーの種類
400	BadRequestError
401	AuthenticationError
403	PermissionDeniedError
404	NotFoundError
422	UnprocessableEntityError
429	RateLimitError
>=500	InternalServerError
N/A	APIConnectionError

再試行

特定のエラーは、デフォルトで短い指数バックオフを伴って 2 回自動的に再試行されます。 接続エラー（たとえば、ネットワーク接続の問題によるエラー）、408 Request Timeout、409 Conflict、 429 Rate Limit、>=500 の内部エラーはすべて、デフォルトで再試行されます。

maxRetries オプションを使用して、再試行回数を設定または無効化できます。

// 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,
});

タイムアウト

リクエストはデフォルトで 1 分後にタイムアウトします。timeout オプションで設定できます。

// 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,
});

タイムアウトすると、APIConnectionTimeoutError がスローされます。

タイムアウトしたリクエストはデフォルトで 2 回再試行されます。

自動ページネーション

Telnyx API のリストメソッドはページネーションされています。 for await … of 構文を使うと、すべてのページにわたって項目を反復処理できます。

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

または、一度に 1 ページずつリクエストできます。

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();
  // ...
}

高度な使い方

生の Response データ（ヘッダーなど）へのアクセス

fetch() が返す「生の」Response は、すべてのメソッドが返す APIPromise 型の .asResponse() メソッドからアクセスできます。 このメソッドは成功レスポンスのヘッダーを受信するとすぐに返り、レスポンスボディを消費しないため、独自の解析やストリーミングロジックを自由に実装できます。

.withResponse() メソッドを使って、解析済みデータとともに生の Response を取得することもできます。 .asResponse() とは異なり、このメソッドはボディを消費し、解析が完了すると返ります。

const client = new Telnyx();

const response = await client.numberOrders
  .create({ phone_numbers: [{ phone_number: '+15558675309' }] })
  .asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // access the underlying Response object

const { data: numberOrder, response: raw } = await client.numberOrders
  .create({ phone_numbers: [{ phone_number: '+15558675309' }] })
  .withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(numberOrder.data);

ロギング

重要

すべてのログメッセージはデバッグ専用です。ログメッセージの形式と内容は、 リリースによって変更される場合があります。

ログレベル

ログレベルは、次の 2 つの方法で設定できます。

1. TELNYX_LOG 環境変数を使用する
2. クライアントオプションの logLevel を使用する（設定されている場合は環境変数より優先されます）

import Telnyx from 'telnyx';

const client = new Telnyx({
  logLevel: 'debug', // Show all log messages
});

ログレベルは、詳細度の高い順に次のとおりです。

• 'debug' - デバッグメッセージ、情報、警告、エラーを表示します
• 'info' - 情報、警告、エラーを表示します
• 'warn' - 警告とエラーを表示します（デフォルト）
• 'error' - エラーのみを表示します
• 'off' - ロギングをすべて無効にします

'debug' レベルでは、ヘッダーとボディを含むすべての HTTP リクエストとレスポンスがログに記録されます。 認証関連の一部のヘッダーはマスキングされますが、リクエストとレスポンスのボディに含まれる機密データは 表示される場合があります。

カスタムロガー

デフォルトでは、このライブラリは globalThis.console にログを出力します。カスタムロガーを指定することもできます。 pino、winston、bunyan、consola、signale、@std/log など、ほとんどのロギングライブラリに対応しています。ロガーが機能しない場合は、issue を作成してください。

カスタムロガーを指定した場合も、logLevel オプションによって出力されるメッセージが制御されます。設定されたレベルより低いメッセージは、ロガーに送信されません。

import Telnyx from 'telnyx';
import pino from 'pino';

const logger = pino();

const client = new Telnyx({
  logger: logger.child({ name: 'Telnyx' }),
  logLevel: 'debug', // Send all messages to pino, allowing it to filter
});

カスタム／未ドキュメントのリクエスト

このライブラリは、ドキュメント化された API に簡単にアクセスできるよう型付けされています。未ドキュメントのエンドポイント、 パラメーター、レスポンスプロパティにアクセスする必要がある場合でも、このライブラリを使用できます。

未ドキュメントのエンドポイント

未ドキュメントのエンドポイントにリクエストを送信するには、client.get、client.post などの HTTP メソッドを使用できます。 リトライなどのクライアントオプションは、これらのリクエストでも適用されます。

await client.post('/some/path', {
  body: { some_prop: 'foo' },
  query: { some_query_arg: 'bar' },
});

未ドキュメントのリクエストパラメーター

未ドキュメントのパラメーターを使用してリクエストを送信するには、該当するパラメーターに // @ts-expect-error を指定します。 このライブラリは、リクエストが実行時に型と一致するか検証しないため、追加で送信した値はそのまま送信されます。

client.calls.dial({
  // ...
  // @ts-expect-error baz is not yet public
  baz: 'undocumented option',
});

GET メソッドのリクエストでは、追加のパラメーターはすべてクエリに含まれます。それ以外のリクエストでは、 追加のパラメーターはすべてボディに含めて送信されます。

追加の引数を明示的に送信する場合は、リクエストオプションの query、body、headers を使用できます。

未ドキュメントのレスポンスプロパティ

未ドキュメントのレスポンスプロパティにアクセスするには、レスポンスオブジェクトに // @ts-expect-error を指定するか、 レスポンスオブジェクトを必要な型にキャストします。リクエストパラメーターと同様に、API からのレスポンスに含まれる追加のプロパティは 検証も削除も行いません。

fetch クライアントのカスタマイズ

デフォルトでは、このライブラリはグローバルな fetch 関数が定義されていることを前提としています。

別の fetch 関数を使用する場合は、グローバル関数をポリフィルするか、次のようにします。

import fetch from 'my-fetch';

globalThis.fetch = fetch;

または、クライアントに渡します。

import Telnyx from 'telnyx';
import fetch from 'my-fetch';

const client = new Telnyx({ fetch });

fetch オプション

fetch 関数を上書きせずにカスタムの fetch オプションを設定するには、クライアントのインスタンス化時またはリクエスト時に fetchOptions オブジェクトを指定します。（リクエスト固有のオプションはクライアントオプションより優先されます。）

import Telnyx from 'telnyx';

const client = new Telnyx({
  fetchOptions: {
    // `RequestInit` options
  },
});

プロキシの設定

プロキシの動作を変更するには、ランタイム固有のプロキシオプションをリクエストに追加するカスタムの fetchOptions を指定します。

Node ^{[ドキュメント]}

import Telnyx from 'telnyx';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new Telnyx({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});

Bun ^{[ドキュメント]}

import Telnyx from 'telnyx';

const client = new Telnyx({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});

Deno ^{[ドキュメント]}

import Telnyx from 'npm:telnyx';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new Telnyx({
  fetchOptions: {
    client: httpClient,
  },
});

よくある質問

セマンティックバージョニング

このパッケージは通常、SemVer の規約に従いますが、後方互換性のない変更をマイナーバージョンとしてリリースする場合があります。

1. 実行時の動作を破壊せず、静的型にのみ影響する変更。
2. 技術的には公開されているものの、外部での利用を意図しておらず、ドキュメントにも記載されていないライブラリ内部の変更。(こうした内部機能に依存している場合は、GitHub の issue を作成してお知らせください。)
3. 実際には大多数のユーザーに影響しないと考えられる変更。

後方互換性を重視し、スムーズにアップグレードできるよう努めています。

皆さまからのフィードバックをお待ちしています。ご質問、バグ、提案がある場合は、issue を作成してください。

要件

TypeScript >= 4.9 をサポートしています。

以下のランタイムをサポートしています。

• Web ブラウザー（最新バージョンの Chrome、Firefox、Safari、Edge など）
• Node.js 20 LTS 以降の (EOL ではない) バージョン。
• Deno v1.28.0 以降。
• Bun 1.0 以降。
• Cloudflare Workers。
• Vercel Edge Runtime。
• "node" 環境での Jest 28 以降（現時点では "jsdom" はサポートしていません）。
• Nitro v2.6 以降。

現時点では React Native はサポートしていません。

その他のランタイム環境に関心がある場合は、GitHub で issue を作成するか、既存の issue に賛成票を投じてください。

コントリビューション

コントリビューションに関するドキュメントをご覧ください。