telnyx-api

Telnyx API - 包括的なコミュニケーションプラットフォーム

v2.0 の拡張：このスキルには、Telnyx の公式ドキュメント、Twilio-Aldea で本番環境向けにテストされたパターン（tweetnacl を使った Ed25519 署名検証、プロバイダーに依存しない Webhook ハンドラー、データベースによる冪等性など）、SMS/MMS メッセージングの包括的な TypeScript の例が含まれるようになりました。

このスキルを使用する場面

次のような Telnyx のコミュニケーション API を使った作業で、このスキルを使用します。

• SMS/MMS メッセージング - プログラムでテキストメッセージを送受信する
• 音声通信 - Call Control API を使って音声通話アプリケーションを構築する
• 電話番号の管理 - 電話番号を検索、購入、設定する
• メッセージングプロファイル - メッセージング設定と Webhook を構成する
• Webhook の統合 - リアルタイムイベントと配信通知を処理する
• 双方向 SMS の会話 - 対話型の SMS エクスペリエンスを構築する
• SMS の一括送信 - レート制限を設けて複数の宛先にメッセージを送信する
• メッセージのスケジュール設定 - 将来の配信に向けてメッセージを予約する
• 本番環境へのデプロイ - エラー処理と監視を備えたメッセージング機能をデプロイする
• 10DLC の登録 - 米国の A2P メッセージング規制に準拠するため、ブランドとキャンペーンを登録する

このスキルは、アプリケーションのコミュニケーション機能の構築、SMS 通知システムの設定、音声 IVR システムの作成、テレフォニー機能の統合に適用できます。

クイックリファレンス

1. シンプルな SMS の送信

const axios = require('axios');

async function sendSMS(to, from, text) {
  const response = await axios.post(
    'https://api.telnyx.com/v2/messages',
    { from, to, text },
    {
      headers: {
        'Authorization': `Bearer ${process.env.TELNYX_API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

// Usage
await sendSMS('+14155552671', '+14155559999', 'Hello from Telnyx!');

2. 電話番号の検証（E.164 形式）

function validateE164(phoneNumber) {
  const e164Regex = /^\+[1-9]\d{1,14}$/;

  if (!e164Regex.test(phoneNumber)) {
    return {
      valid: false,
      error: 'Phone number must be in E.164 format (e.g., +14155552671)'
    };
  }

  return { valid: true };
}

// Normalize US phone numbers to E.164
function formatToE164(number) {
  let digits = number.replace(/\D/g, '');
  if (!digits.startsWith('1')) {
    digits = '1' + digits;
  }
  return '+' + digits;
}

3. 受信メッセージの処理（Webhook）

const express = require('express');
app.use(express.json());

app.post('/webhooks/telnyx', (req, res) => {
  const event = req.body.data;

  if (event.event_type === 'message.received') {
    const from = event.payload.from.phone_number;
    const text = event.payload.text;
    const to = event.payload.to[0].phone_number;

    console.log(`Received: "${text}" from ${from}`);

    // Auto-reply
    await sendSMS(from, to, 'Thanks for your message!');
  }

  res.status(200).send('OK');
});

4. Webhook 署名の検証（Ed25519）

const nacl = require('tweetnacl');

function verifyWebhook(rawBody, signature, timestamp, publicKey) {
  // Check timestamp freshness (prevent replay attacks)
  const timestampMs = parseInt(timestamp);
  const now = Date.now();
  if (Math.abs(now - timestampMs) > 5 * 60 * 1000) {
    return false; // Reject if older than 5 minutes
  }

  // Construct signed payload
  const signedPayload = `${timestamp}|${rawBody}`;

  // Decode signature and public key from hex
  const signatureBytes = Buffer.from(signature, 'hex');
  const publicKeyBytes = Buffer.from(publicKey, 'hex');

  // Verify Ed25519 signature
  return nacl.sign.detached.verify(
    Buffer.from(signedPayload, 'utf8'),
    signatureBytes,
    publicKeyBytes
  );
}

// Usage in Express
app.post('/webhooks/telnyx', (req, res) => {
  const signature = req.headers['telnyx-signature-ed25519'];
  const timestamp = req.headers['telnyx-timestamp'];
  const rawBody = JSON.stringify(req.body);

  if (!verifyWebhook(rawBody, signature, timestamp, process.env.TELNYX_PUBLIC_KEY)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
  res.status(200).send('OK');
});

5. エラー処理と再試行を伴う送信

async function sendWithRetry(to, from, text, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await sendSMS(to, from, text);
    } catch (error) {
      if (error.response?.status >= 500 && attempt < maxRetries) {
        // Server error - retry with exponential backoff
        const delayMs = Math.pow(2, attempt) * 1000;
        console.log(`Retry ${attempt} in ${delayMs}ms...`);
        await new Promise(resolve => setTimeout(resolve, delayMs));
      } else {
        throw error;
      }
    }
  }
}

6. レート制限を設けた一括送信

async function sendBulkSMS(recipients, from, text) {
  const delayMs = 100; // 10 messages/second
  const results = [];

  for (const recipient of recipients) {
    try {
      const result = await sendSMS(recipient, from, text);
      results.push({ success: true, to: recipient, id: result.data.id });
    } catch (error) {
      results.push({ success: false, to: recipient, error: error.message });
    }

    await new Promise(resolve => setTimeout(resolve, delayMs));
  }

  return results;
}

7. 冪等性を備えた Webhook 処理（データベース）

// Using PostgreSQL with unique constraint
async function processWebhookIdempotent(event, client) {
  try {
    await client.query('BEGIN');

    // Try to insert event (will fail if duplicate due to unique constraint)
    await client.query(
      'INSERT INTO processed_webhooks (event_id, processed_at) VALUES ($1, NOW())',
      [event.id]
    );

    // Process event
    await handleEvent(event, client);

    await client.query('COMMIT');
  } catch (error) {
    await client.query('ROLLBACK');

    // If duplicate key error, event was already processed
    if (error.code === '23505') {
      console.log('Event already processed, skipping');
      return;
    }

    throw error;
  }
}

8. 双方向会話のステートマシン

const conversations = new Map();

app.post('/webhooks/telnyx', async (req, res) => {
  const event = req.body.data;

  if (event.event_type === 'message.received') {
    const from = event.payload.from.phone_number;
    const to = event.payload.to[0].phone_number;
    const text = event.payload.text.toLowerCase();

    let state = conversations.get(from) || 'start';
    let reply;

    switch (state) {
      case 'start':
        reply = "Welcome! What's your name?";
        conversations.set(from, 'asked_name');
        break;

      case 'asked_name':
        reply = `Nice to meet you, ${text}! How can I help?`;
        conversations.set(from, 'helping');
        break;

      case 'helping':
        reply = 'Thanks! A human will respond shortly.';
        conversations.delete(from);
        break;
    }

    await sendSMS(from, to, reply);
  }

  res.status(200).send('OK');
});

9. 10DLC キャンペーンのステータス確認

#!/bin/bash
# Monitor campaign approval status

CAMPAIGN_ID="your-campaign-id"
API_KEY="your-api-key"

STATUS=$(curl -s "https://api.telnyx.com/v2/10dlc/campaign/${CAMPAIGN_ID}" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.campaignStatus')

echo "Campaign status: ${STATUS}"

# Status values:
# - TCR_ACCEPTED: Campaign Registry approved (not yet ready)
# - MNO_PENDING: Waiting for carrier approval
# - MNO_PROVISIONED: Fully approved and ready for production

10. よくあるエラーの処理

function handleTelnyxError(error) {
  if (!error.response) {
    return { type: 'NETWORK_ERROR', retriable: true };
  }

  const status = error.response.status;
  const errorData = error.response.data.errors?.[0];

  switch (status) {
    case 400:
    case 422:
      // Validation error - fix input
      return {
        type: 'VALIDATION_ERROR',
        message: errorData?.detail || 'Invalid request',
        retriable: false
      };

    case 401:
      // Check API key
      return { type: 'AUTH_ERROR', retriable: false };

    case 429:
      // Rate limit - wait and retry
      return {
        type: 'RATE_LIMIT',
        retriable: true,
        retryAfter: 60
      };

    case 500:
    case 502:
    case 503:
      // Server error - retry with backoff
      return { type: 'SERVER_ERROR', retriable: true };

    default:
      return { type: 'UNKNOWN_ERROR', retriable: false };
  }
}

主な概念

1. E.164 電話番号形式

国際電話番号の形式：+[国番号][番号]

• 米国の例：+14155552671
• 英国の例：+442071234567
• 必ず + を先頭に付けてください
• 最大 15 桁（+ を除く）

2. メッセージングプロファイル

電話番号をグループ化し、Webhook 設定を定義する構成用のコンテナーです。次のような利点があります。

• Webhook を一元管理
• 負荷分散用の電話番号プール
• 英数字の送信者 ID
• 電話番号を簡単に管理
• Webhook のフェイルオーバー URL

3. メッセージのエンコードと分割

• GSM-7：標準 ASCII で 1 セグメントあたり 160 文字（低コスト）
• UCS-2：絵文字や Unicode 文字で 1 セグメントあたり 70 文字（高コスト）
• 長いメッセージは複数のセグメントに分割されます（最大 10）
• 複数パートのメッセージ：GSM-7 は 1 セグメントあたり 153 文字、UCS-2 は 67 文字

4. Webhook イベント

メッセージのステータスに関するリアルタイム通知です。

• message.sent - 携帯電話会社に送信済み
• message.delivered - 宛先に配信済み
• message.failed - 配信失敗
• message.received - 受信メッセージを受信
• message.finalized - 最終状態に到達

5. 10DLC キャンペーンの承認段階

米国のメッセージングで重要なポイント：

1. TCR_ACCEPTED - Campaign Registry に承認済み（まだ送信できません）
2. MNO_PENDING - 携帯電話会社の承認待ち（1～3 日）
3. MNO_PROVISIONED - 承認済みで利用可能（電話番号を関連付けて送信できます）

6. 認証

すべての API リクエストには、Bearer トークン認証が必要です。

Authorization: Bearer YOUR_API_KEY

API キーは環境変数に保存し、ハードコードしないでください。

リファレンスファイル

references/ ディレクトリには、詳細なドキュメントが含まれています。

authentication.md

API キーの管理とセキュリティに関する包括的なガイドです。

• API キーの作成と管理
• 環境変数の設定（Node.js、Python、Docker、Kubernetes）
• キーのローテーションとセキュリティに関するベストプラクティス
• IP ホワイトリストの設定
• Webhook 署名の検証
• よくある認証エラーと解決方法

messaging-api.md

Messaging API の完全なリファレンス：

• エンドポイントの完全なドキュメント（/v2/messages）
• すべてのリクエスト／レスポンスパラメーター
• メッセージのステータス値とライフサイクル
• 文字エンコーディングの詳細（GSM-7 と UCS-2）
• メッセージの分割ルール
• MMS の制限とサポートされている形式
• ページネーションとフィルタリングのオプション

webhooks.md

包括的な Webhook リファレンス：

• ペイロードの例を含むすべての Webhook イベントタイプ
• Ed25519 署名の検証（セキュア）
• HMAC-SHA256 署名の検証（レガシー）
• Webhook の設定（グローバル、プロファイル、メッセージごと）
• ベストプラクティス（冪等性、非同期処理、再試行）
• ngrok を使ったローカルでの Webhook テスト
• Webhook ハンドラーの完全な実装例
• トラブルシューティングガイド

error-codes.md

エラーの完全なリファレンスと処理方法：

• すべての HTTP ステータスコードとその意味
• 一般的なエラーコードと解決策
• 検証エラー（10001-10007）
• レート制限エラー（429）
• サーバーエラー（500、502、503）
• Webhook 固有の配信エラー
• 包括的なエラーハンドラーの実装
• 指数バックオフを使用した再試行戦略

best-practices.md

本番環境へのデプロイパターン：

• 本番環境でのメッセージングプロファイルの使用
• 堅牢なエラー処理パターン
• 指数バックオフによる再試行ロジック
• 一括送信のレート制限
• メッセージの追跡とステータス監視
• 電話番号の検証と形式設定
• メッセージ内容の最適化
• 文字数制限への対応
• キューを使用した Webhook の非同期処理
• 冪等性の実装
• 構造化ログと監視
• コスト最適化の戦略
• テストパターン
• 本番環境へのデプロイチェックリスト

number-management.md

電話番号の操作：

• 利用可能な番号の検索
• 電話番号の購入
• 番号設定の構成
• 既存番号の移行
• 番号プールの管理

10dlc.md

10DLC（10 桁のロングコード）の登録とコンプライアンス：

• キャンペーンの承認段階（TCR_ACCEPTED → MNO_PENDING → MNO_PROVISIONED）
• ブランドとキャンペーンの登録プロセス
• ユースケースの選択（カスタマーケア、マーケティング、2FA など）
• TCPA および CTIA のコンプライアンス要件
• 必須のメッセージ要素（オプトイン、オプトアウト、HELP）
• API を使ったキャンペーンステータスの監視
• 電話番号の関連付け（ポータルのみ。API では不可）
• 料金体系と所要期間の目安（3-5 営業日）
• よくある問題とトラブルシューティング
• 本番環境用チェックリスト

Telnyx 公式ドキュメント（新規）

developers.telnyx.com から抽出した公式ドキュメント一式：

• references/official-docs/webhooks.md - 署名の検証、イベントタイプ、ベストプラクティスを網羅した Webhook ガイド
• references/official-docs/messaging.md - SMS／MMS エンドポイント、文字エンコーディング、分割を網羅した Messaging API リファレンス
• references/official-docs/authentication.md - API 認証、セキュリティ、ベストプラクティス
• references/official-docs/sdks.md - サーバーサイド SDK のドキュメント（Node.js（TypeScript／ESM 対応の v2）、Python、Ruby、PHP、Java、Go）

本番環境向けパターン（新規）

Twilio-Aldea の本番コードベースから得られた実環境でのパターン：

• references/production-patterns.md - 実環境で検証済みの 8 つのパターン。内容は次のとおりです。
  • パターン 1: tweetnacl による Ed25519 署名の検証（セキュアな Webhook 認証）
  • パターン 2: プロバイダーに依存しない Webhook ハンドラー（単一のエンドポイントで Twilio と Telnyx をサポート）
  • パターン 3: 署名検証のための Raw Body の解析（正確なバイト列を保持）
  • パターン 4: データベースの一意制約による冪等性の確保（重複処理を防止）
  • パターン 5: メッセージングプロファイルの設定（本番環境に適した構成）
  • パターン 6: 電話番号検出によるデバッガーモード（コストをかけずにテスト）
  • パターン 7: 分類機能を備えたデータベースへのエラーログ記録（永続的でクエリ可能な追跡）
  • パターン 8: E.164 電話番号の正規化（すべての形式に対応）

コード例（NEW）

本番環境ですぐに使える TypeScript の例：

• assets/examples/webhook-handler.ts - Ed25519 署名検証を備えた完全な Webhook ハンドラー
• assets/examples/send-sms.ts - エラー処理と再試行ロジックを含む SMS/MMS 送信例
• assets/examples/provider-implementation.ts - Twilio-Aldea の本番環境向けプロバイダークラス全体

GitHub リポジトリ（NEW）

references/github/README.md

GitHub にある Telnyx Node.js SDK の公式 README（team-telnyx/telnyx-node、スター 62 個）

references/github/issues.md

一般的な問題と解決策を示す GitHub の issue 16 件：

• Webhook 署名検証の問題
• TypeScript 型定義
• SDK 初期化エラー
• レート制限への対処
• 環境設定

references/github/CHANGELOG.md

破壊的変更と移行方法を含む SDK の完全なバージョン履歴

references/github/releases.md

SDK の詳細な変更履歴を含む GitHub リリース 81 件

references/github/file_structure.md

SDK のソースコード構成を示すリポジトリ構造（ファイル 2,129 件）

このスキルの使い方

初心者向け

ここから始めましょう：

1. クイックリファレンス例 #1（シンプルな SMS の送信）を使います
2. API キー用の環境変数を設定します
3. クイックリファレンス例 #2（電話番号の検証）を使います
4. 自分の電話番号宛てに送信してテストします
5. クイックリファレンス例 #3（受信メッセージの処理）を設定します
6. ngrok を使って双方向メッセージングをテストします

習得する主な概念：

• E.164 電話番号形式（必ず + から始まります）
• Bearer トークン認証
• Webhook の基本的な処理
• メッセージのエンコード方式（GSM-7 と UCS-2）

参考ファイル：

• 設定については authentication.md から始めます
• API の基本的な使い方については messaging-api.md を確認します
• エラーが発生した場合は error-codes.md を参照します
• メッセージの受信には webhooks.md を使います

初心者によくある間違い：

• 電話番号に + 接頭辞を付け忘れる
• E.164 形式を使わない（例：+14155552671 ではなく (415) 555-2671 を使う）
• 環境変数を使わずに API キーをハードコードする
• Webhook 署名を検証しない

中級者向け

重点項目：

1. クイックリファレンス例 #4（Ed25519 による Webhook 署名の検証）を実装します
2. クイックリファレンス例 #5（再試行を伴うエラー処理）を使います
3. クイックリファレンス例 #8（ステートマシン）を使って会話フローを構築します
4. メッセージングプロファイルを作成します（best-practices.md を参照）
5. クイックリファレンス例 #7（データベースの冪等性）を実装します

習得する主な概念：

• 本番環境向けのメッセージングプロファイル
• Ed25519 Webhook 署名検証（HMAC より安全）
• 再試行ロジックを用いたエラー処理パターン
• メッセージの分割とコストの最適化
• Webhook 処理における冪等性
• 一括送信のレート制限

参考ファイル：

• イベントの種類とセキュリティについては webhooks.md を学習します
• 本番環境向けのパターンについては best-practices.md を確認します
• 包括的なエラー処理には error-codes.md を使います
• 実環境での実装については production-patterns.md を確認します

本番環境での考慮事項：

• Webhook 署名は必ず検証します（HMAC-SHA256 ではなく Ed25519 を使います）
• 重複処理を防ぐために冪等性を実装します
• 再試行には指数バックオフを使います
• デバッグ用に、すべてのエラーをデータベースに記録します
• メッセージの配信率を監視します

上級ユーザー向け

高度なパターン：

1. best-practices.md の一括メッセージ送信をキューシステム（Bull/Redis）で実装する
2. プロバイダーに依存しないハンドラーを構築する（production-patterns.md のパターン 2）
3. 包括的なエラーロギングを設定する（production-patterns.md のパターン 7）
4. コストのかからないテスト用にデバッガーモードを実装する（パターン 6）
5. エンコーディング戦略でメッセージコストを最適化する
6. Call Control API で IVR システムを構築する
7. 大量メッセージ送信用に電話番号プールを設定する
8. 包括的なモニタリングとアラートを実装する

主要トピック：

• 非同期処理向けのメッセージキューシステム（Bull/Redis）
• 一意制約を使用したデータベースベースの冪等性
• 構造化ロギング（Winston）
• メトリクス収集（Prometheus）
• 本番環境へのデプロイパターン
• 統一インターフェースを備えたマルチプロバイダーアーキテクチャ
• 10DLC キャンペーンの登録とモニタリング
• Webhook のフェイルオーバーと再試行の仕組み

参照ファイル：

• 本番環境向けのすべてのパターンについて、best-practices.md を詳しく確認する
• 包括的なエラー処理について、error-codes.md を調べる
• 高度な Webhook パターンについて、webhooks.md を確認する
• 実戦で検証済みの実装について、production-patterns.md を分析する
• 米国の A2P メッセージングコンプライアンスについて、10dlc.md を確認する

アーキテクチャパターン：

• プロバイダーに依存しない設計（複数の SMS プロバイダーに対応）
• メッセージキューを使用したイベント駆動型アーキテクチャ
• 会話向けのデータベースベースのステートマシン
• 指数バックオフを使用した Webhook 再試行の仕組み
• デバッガーモードの検出によるコスト最適化
• フェイルオーバーを備えたマルチリージョンデプロイ

API の基本

ベース URL

https://api.telnyx.com/v2

認証ヘッダー

Authorization: Bearer YOUR_API_KEY

環境変数

# .env file
TELNYX_API_KEY=KEY019A080F468AAFD4AF4F6888D7795244_xxx
TELNYX_PUBLIC_KEY=your_public_key_for_webhook_validation
TELNYX_MESSAGING_PROFILE_ID=abc85f64-5717-4562-b3fc-2c9600000000

レート制限

• 標準アカウント：エンドポイントごとに毎秒 10 リクエスト
• 大量利用アカウント：上限の引き上げについて Telnyx にお問い合わせください
• 429 レスポンスに対して指数バックオフを実装する

一般的なレスポンス構造

{
  "data": {
    "id": "message-uuid",
    "type": "SMS",
    "from": { "phone_number": "+18445550001" },
    "to": [{ "phone_number": "+18665550001", "status": "queued" }],
    "text": "Hello!",
    "cost": { "amount": "0.0051", "currency": "USD" }
  }
}

クイックスタートチェックリスト

• https://telnyx.com/sign-up で Telnyx アカウントを登録する
• Mission Control Portal で API キーを生成する
• 環境変数を設定する（キーをハードコードしないでください）
• テスト用の電話番号を購入する
• 最初の SMS テストメッセージを送信する（クイックリファレンス #1）
• 電話番号を検証する（クイックリファレンス #2）
• Webhook エンドポイントを設定する（ローカル開発では ngrok を使用）
• Webhook ハンドラーを実装する（クイックリファレンス #3）
• Ed25519 Webhook 署名の検証を追加する（クイックリファレンス #4）
• 双方向メッセージングをテストする
• 再試行ロジックを含むエラー処理を追加する（クイックリファレンス #5）
• 本番環境用のメッセージングプロファイルを設定する
• （米国のみ）A2P メッセージを送信する場合は 10DLC に登録する

経験レベル別のナビゲーション

初心者（利用開始）

1. クイックリファレンスの例 #1（シンプルな SMS を送信）から始める
2. API の設定について references/authentication.md を確認する
3. メッセージ API の基本について references/messaging-api.md を調べる
4. クイックリファレンスの例 #2（電話番号を検証）を使用する
5. クイックリファレンスの例 #3 で Webhook を設定する
6. ngrok でローカルテストを行う

中級者（機能の構築）

1. Ed25519 署名の検証を実装する（クイックリファレンス #4）
2. 高度な Webhook パターンについて references/webhooks.md を調べる
3. メッセージングプロファイルを使用する（best-practices.md を参照）
4. 冪等性を実装する（クイックリファレンス #7）
5. 会話用ステートマシンを構築する（クイックリファレンス #8）
6. 完全な実装について assets/examples/webhook-handler.ts を確認する

上級者（本番環境へのデプロイ）

1. プロバイダーに依存しないハンドラーを構築する（production-patterns.md のパターン 2）
2. エラーロギングとモニタリングを実装する（production-patterns.md のパターン 7）
3. 統一インターフェースを備えたマルチプロバイダーアーキテクチャを設計する
4. production-patterns.md の 8 つすべてのパターンを適用して、本番環境向けに最適化する
5. SMS ベースの AI プラットフォームアーキテクチャについて、Twilio-Aldea のパターンを調べる
6. モニタリング、アラート、メトリクス収集を設定する

v2.0 での主な強化点

公式ドキュメントとの統合

• Webhooks Guide：Ed25519 署名検証、イベントタイプ、再試行ロジックを網羅
• Messaging API：エンドポイントの完全なリファレンス、文字エンコーディング（GSM-7 対 UCS-2）、セグメント化のルール
• Authentication：API キーの管理、セキュリティのベストプラクティス、環境変数の設定
• SDK Reference：7 言語に対応したサーバーサイド SDK のドキュメント

本番環境でのパターン

• Ed25519 署名検証：本番環境でテスト済みの tweetnacl 実装（セキュリティ検証の問題を解決）
• プロバイダーに依存しない設計：単一のエンドポイントから複数の SMS プロバイダーに対応
• 生のボディの保持：正確なバイト列を使った正しい署名検証
• データベースの冪等性：PostgreSQL の一意制約パターン（二重処理を防止）
• メッセージングプロファイル：Webhook を一元管理する本番環境へのデプロイ
• デバッガーモード：稼働中のプラットフォームで使われている無料のテストパターン
• エラーログ：分類機能を備えたデータベースベースのエラー追跡
• E.164 正規化：あらゆる形式の電話番号を正しく処理

コード例

• TypeScript の例：Webhook ハンドラー、SMS 送信、完全な型安全性を備えたプロバイダークラス
• 本番環境でのパターン：Twilio-Aldea SMS プラットフォームで使われている実際の実装
• セキュリティの例：Ed25519 検証、生のボディの解析、署名検証

データソース

• Telnyx 公式ドキュメント（Firecrawl 経由）
• Exa のコードコンテキスト（実際のリポジトリから取得した Telnyx のパターン、8000 以上のトークン）
• Twilio-Aldea の本番コードベース（Netlify にデプロイされた SMS ベースの AI セラピープラットフォーム）

バージョン履歴

• v2.1（2026-04-21）- Node SDK v2 に対応するよう更新（TypeScript を完全サポート、ESM モジュール）、予約メッセージ送信（send_at フィールド）が本番環境で利用可能な機能であることを記載
• v2.0（2025-11-01）- Telnyx 公式ドキュメント、Twilio-Aldea の本番環境でのパターン（Ed25519 検証、プロバイダーに依存しない Webhook、冪等性）、TypeScript の例、包括的な Messaging API ガイドを追加
• v1.0 - クイックリファレンス、エラーコード、基本的なメッセージングパターンを含む初期スキル作成

その他のリソース

• Telnyx Developer Portal：https://developers.telnyx.com/
• API Reference：https://developers.telnyx.com/api/
• Mission Control Portal：https://portal.telnyx.com/
• Status Page：https://status.telnyx.com/
• Support Portal：https://support.telnyx.com/
• 公式 SDK：Node.js（v2 — TypeScript、ESM）、Python、Ruby、PHP、Java、Go

よく使われるパターン

パターン：追跡情報付きメッセージ

const tracker = new Map();

async function sendTrackedMessage(to, from, text) {
  const response = await sendSMS(to, from, text);
  tracker.set(response.data.data.id, {
    to, from, text,
    status: 'queued',
    sentAt: new Date()
  });
  return response;
}

// In webhook handler
app.post('/webhooks/telnyx', (req, res) => {
  const event = req.body.data;
  if (event.event_type === 'message.delivered') {
    const msg = tracker.get(event.payload.id);
    if (msg) msg.status = 'delivered';
  }
  res.status(200).send('OK');
});

パターン：E.164 形式への変換

function formatToE164(number, defaultCountryCode = '1') {
  let digits = number.replace(/\D/g, '');
  if (!digits.startsWith(defaultCountryCode)) {
    digits = defaultCountryCode + digits;
  }
  return '+' + digits;
}

// Examples
formatToE164('415-555-2671');      // +14155552671
formatToE164('(415) 555-2671');    // +14155552671
formatToE164('+1 415-555-2671');   // +14155552671

パターン：メッセージ料金の最適化

// Prefer GSM-7 encoding (cheaper, longer)
function optimizeForGSM7(text) {
  // Replace unicode quotes with GSM-7 quotes
  return text
    .replace(/[""]/g, '"')
    .replace(/['']/g, "'")
    .replace(/[—–]/g, '-')
    .replace(/…/g, '...');
}

サポートとトラブルシューティング

ヘルプの利用

1. 特定のエラーメッセージについては error-codes.md を確認してください
2. よく使われるパターンについては best-practices.md を参照してください
3. サービスのステータスは https://status.telnyx.com/ で確認してください
4. Mission Control Portal からサポートにお問い合わせください
5. 米国向け A2P メッセージングで問題が発生した場合は 10dlc.md を確認してください

よくある問題

• 401 Unauthorized：API キーの形式（Bearer YOUR_API_KEY）を確認してください
• 10001 Invalid phone number：E.164 形式（+14155552671）になっていることを確認してください
• 429 Rate limit：レート制限を実装してください（クイックリファレンス #6）
• Webhook を受信できない：有効な SSL を使用し、URL にパブリックアクセスできることを確認してください
• 米国内でメッセージが配信されない：10DLC キャンペーンのステータスを確認してください（MNO_PROVISIONED である必要があります）

デバッグのヒント

// Enable request/response logging
axios.interceptors.request.use(request => {
  console.log('Request:', request.url, request.data);
  return request;
});

axios.interceptors.response.use(
  response => {
    console.log('Response:', response.status, response.data);
    return response;
  },
  error => {
    console.error('Error:', error.response?.data);
    return Promise.reject(error);
  }
);