🀄️

Vonage SIP Trunking と PSIP(Programmable SIP)の基本的な使い方（後半）

若林徹

2024/10/31に公開

sip

Vonage

tech

 はじめにこんにちは。KDDI ウェブコミュニケーションズの若林です。
Vonage（ボネージ）の SIP Trunking と Programmable SIP を使うことで、既存または新規の IP 電話システムや端末を短時間かつ低コストで Vonage に収容・連携することができます。この記事では、 Vonage で実現できる SIP に関連した機能について簡単にご紹介していきます。

 本記事の対象となる読者
Vonage のアカウントを持っている方

Vonage 開発スタートガイドを確認済みの方
インターネット通信や IP ネットワークの基礎的な理解のある方
Vonage の SIP 接続を使って色々試してみたい方
自社の IP-PBX などと Vonage を繋いでみたい方

 事前準備本記事では IP-PBX の用意は不要です。Vonage 環境さえあれば読み進めていくことができます。
SIP の接続検証・動作確認を行う場合はご自身でグローバル IPアドレスが割り当ててある IP-PBX に相当する設備を準備する必要があるため、必要に応じてご用意ください（この記事では紹介しません）。

 Vonage とは
Vonage は、米国ニュージャージー州に本社を置くCPaaS（Communication Platform as a Service）企業です。

もともとは VoIP（Voice over IP）企業としてスタートしましたが、いくつかの企業買収を行うことで、コミュニケーションサービス全般をサポートできる企業に発展しました。現在はスウェーデンの大手通信機器会社エリクソンの傘下に入っています。

 SIP とはSIP (Session Initiation Protocol) の略で、RFC 3261 で標準化されている通信プロトコルになります。
主に IP 電話の通信制御（通話の開始や切断など）の標準プロトコルとして、ソフトウェアベースの電話アプリ、ハードウェアベースの IP 電話機、 IP-PBX や電話機能を持った IoT 機器で広く一般的に使用されています。

 この記事のシナリオ前半の記事では Vonage SIP Trunking について作成していきました。後半となる今回の記事では、前回作成した SIP Trunk に Vonage PSIP で作成した IP-PBX の代用環境を繋いでいきます。以下に前半・後半の本記事の流れをまとめています。
前回の内容（前半）
Vonage SIP の利用構成
Vonage SIP の仕様
Vonage SIP Trunking の作成と認証設定
Vonage SIP Trunking の発信と着信の設定
Vonage SIP Trunking への電話番号の関連付け
今回の内容（後半）
Vonage アプリケショーンの作成と設定
IP-PBX 代用環境のための PSIP 作成と設定
IP-PBX 代用環境と SIP Trunk の動作確認
PSIP の設定と動作について
BYOC の設定と動作について

 Vonage アプリケーションの設定さて、以降の内容で必要となる IP-PBX の代用環境や PSIP/BYOC の解説で必要となる Vonage アプリケーションを作成していきます。下図のように、 Vonage アプリケーションは PSIP に割り当てて利用しますので、赤枠の箇所を作成・設定していきます。

 PSIP のイメージ図

 アプリケーションメニューの選択Vonage ダッシュボード画面にて、左メニューの「機能と管理」の中の「 アプリケーション 」を選択します。

 新しいアプリケーションを作成する続いて、アプリケーションの一覧画面が表示されます。アプリケーションが存在しない場合は何も表示されませんので、そのまま「＋新しいアプリケーションを作成する」ボタンを押してください。

 アプリケーション名と公開鍵の設定下図の通り、任意のアプリケーション名を記入し、「公開鍵と秘密鍵を生成」ボタンを押してください。

 公開鍵の確認と秘密鍵の保存公開鍵と秘密鍵が自動生成され、秘密鍵は自動的にダウンロードされるため、大切に保管してください。公開鍵は下図の通り、画面上でいつでも確認することができます。

 音声機能の有効化続いて、「音声」機能を有効化します。「音声」トグルをオンにすると、「回答 URL 」「イベント URL 」「フォールバック URL 」「地域」を指定できるようになるので指定していきます。特に「回答 URL 」と「イベント URL 」は上述の図の「Application Server」へのリクエスト先になりますので、ご利用環境に合わせて指定してください。「フォールバック URL 」は今回使いませんが、必要に応じて設定してください。
また、 Vonage には VCR(Vonage Cloud Runtime) という独自のアプリケーションサーバー機能がありますので、新たにサーバーを準備することが難しい場合は、VCR を使ったブラウザ発着信の実装に VCR の使い方が紹介されていますので参考にしてください。

 アプリケーションの生成完了音声機能の有効化が完了したら、画面右下の「新しいアプリケーションの生成」ボタンを押してアプリケーション作成を確定します。

 IP-PBX 代用環境のための PSIP の設定ここまでで Vonage アプリケーションの設定が完了しました。 今回は IP-PBX の代わりに Vonage PSIP を代用していきます。

 SIP Trunking イメージと IP-PBX を PSIP で代用した場合のイメージ図

SIP Trunking 通常の利用イメージ



IP-PBX を Vonage PSIP で代用する場合

 IP-PBX 用に PSIP を追加それでは早速、 IP-PBX のための PSIP を作成していきます。以下の「 SIP Trunks 」画面から、「＋ Create New 」ボタンを押してもう一つ SIP 設定を追加していきます。


 IP-PBX 用の PSIP 設定下記画面が表示されますので、画面に従って「 Domain name 」に IP-PBX 用の SIP ドメインを記入して「 Create 」ボタンを押します。

 IP-PBX 用の PSIP の確認入力した SIP ドメインに重複がなければ正常に作成ができて下記画面が表示されます。 早速、設定を変更していきますので「 Edit trunk 」ボタンを押して設定を変更していきます。

 アプリケーションタイプへの変更下図のような画面に遷移したら、「 Type 」に「 Application 」を指定します。すると Vonage Application を指定できるようになるので、前段で作成したアプリケーションを選択して「 Save 」ボタンを押します。

 IP-PBX 用 PSIP の有効化準備IP-PBX 用の PSIP の準備が一旦整いました。続いて、 SIP Trunk からの着信を受け付けられるように PSIP の ACL を設定していきます。

 PSIP API による詳細情報の確認早速、 IP-PBX 用 PSIP ドメインの内容を API で確認します。PSIP ドメインの詳細取得 API ドキュメントを参考に cURL や HTTPie のようなツールで API リクエスト実施してみてください。以下のような情報が取得できるはずです。
cURL 実行例curl -u <APIKEY>:<APISECRET> https://api.nexmo.com/v1/psip/kwc-hoge-ippbx 
cURL 実行結果{
	"name": "kwc-hoge-ippbx",
	"domain_type": "app",
	"application_id": "********-****-****-****-************",
	"tls": "optional",
	"srtp": "optional",
	"acl": [
		"0.0.0.0/0"
	],
	"owner": "********",
	"digest_auth": true,
	"description": ""
}

 PSIP API による ACL の追加続いて、 SIP Trunk から着信を受ける設定を追加していきます。具体的には、 Vonage が使用する IP アドレスレンジを ACL に追加して Digest 認証を無効化します。
cURL 実行例curl -u <APIKEY>:<APISECRET> -X PUT https://api.nexmo.com/v1/psip/kwc-hoge-ippbx -H "Content-Type: application/json" -d '{"application_id": "********-****-****-****-************", "digest_auth": false, "domain_type": "app", "name": "kwc-hoge-ippbx", "owner": "********", "acl": ["216.147.0.0/18", "168.100.64.0/18"]}'
cURL 実行結果{
	"name": "kwc-hoge-ippbx",
	"domain_type": "app",
	"application_id": "********-****-****-****-************",
	"tls": "optional",
	"srtp": "optional",
	"acl": [
		"168.100.64.0/18",
		"216.147.0.0/18"
	],
	"owner": "********",
	"digest_auth": false
}
!digest_authを今回のようにfalseにした場合、 GUI 側のダッシュボードで ACL や 認証情報の設定を更新すると、 Vonage 側のセキュリティ上の配慮のためかtrueに戻ってしまうことがあります。運用の過程で突然繋がらなくなったということを防ぐために、digest_auth=falseにした場合は、設定変更する際には必ず API で確認・更新するようにしてください。

 IP-PBX 用 PSIP の 動作確認ACL および認証設定が更新できたら、いよいよ SIP Trunk の動作確認ができます。 SIP Trunk に関連付けした電話番号にかけると、 SIP Trunk 経由で IP-PBX 用の PSIP へ着信が届きます。 下図の通り最終的に PSIP に割り当ててあるアプリケーションの回答 URL にリクエストが届きます。このリクエストに対して何も応答しないと着信通話に失敗してしまいますので、回答 URL のリクエスト先に Vonage NCCO を参考にしながら後述する応答例を返却するプログラムを簡単で構いませんので設置してください。

 （参考）構成図

 回答 URL の応答例と SIP Trunk （ IP-PBX ）への着信動作確認ここまでに SIP Trunk へ関連付けた電話番号へ電話をかけて問題なく成功すると、「これは IP-PBX のテストです。」という音声を聞くことができます。
[
  {
    "action": "talk",
    "language": "ja-JP",
    "style": "3",
    "premium": "true",
    "text": "これは IP-PBX のテストです。"
  }
]

 着信音声ログの確認通話に成功したので Vonage にどのように記録されているかを「音声ログ」をみて確認してみましょう。今回の通話に該当するログは、下図のように 3 行のログになります。ログタイプは「電話（ PSTN / SIP ）」を選択してください。
外線電話（ PSTN ）から Vonage SIP Trunk への着信ログ
Vonage SIP Trunk から IP-PBX 用 PSIP への発信ログ
IP-PBX 用 PSIP への着信ログ


音声ログ



構成図

 SIP Trunk （ IP-PBX ）からの発信動作確認続いて、発信の動作確認を行います。しかし、以下の理由により SIP Trunk 側の設定を変更をする必要があります。
Vonage SIP は現状、発信時において Digest 認証（ INVITE 認証）ができない
Vonage SIP Trunk はここまでの設定で Digest 認証が有効になっている
ではどうするかというと、 SIP Trunk の Digest 認証を無効化します。
SIP Trunk 設定の確認それでは改めて SIP Trunk の設定を確認しましょう。
curl -u <APIKEY>:<APISECRET> https://api.nexmo.com/v1/psip/kwc-hogehoge
{
    "acl": [
        "***.***.***.***/32"
    ],
    "description": "",
    "digest_auth": true,
    "domain_type": "trunk",
    "name": "kwc-hogehoge",
    "owner": "********",
    "srtp": "optional",
    "tls": "optional"
}
Digest 認証の無効化と ACL の追加設定が確認できましたので、以下の設定を追加・変更します。
SIP Trunk が IP-PBX 用の PSIP からの着信を許可するために、 Vonage の IP アドレスレンジを追加
Digest 認証の無効化
curl -u <APIKEY>:<APISECRET> -X PUT https://api.nexmo.com/v1/psip/kwc-hoge-ippbx -H "Content-Type: application/json" -d '{"digest_auth": false, "domain_type": "trunk", "name": "kwc-hogehoge", "owner": "********", "acl": ["216.147.0.0/18", "168.100.64.0/18"]}'
{
    "acl": [
        "168.100.64.0/18",
        "216.147.0.0/18",
        "***.***.***.***/32"
    ],
    "digest_auth": false,
    "domain_type": "trunk",
    "name": "kwc-hogehoge",
    "owner": "********",
    "srtp": "optional",
    "tls": "optional"
}
IP-PBX 用 PSIP の応答内容の修正前段の着信動作確認では音声合成による音声応答のみでしたが、 SIP Trunk からの発信が確認できるように以下のような応答を返すようにアプリケーションを修正してください。fromは SIP Trunk に関連付けている電話番号である必要があります。
着信に成功すると「お繋ぎしますのでそのまま暫くお待ちください。」という音声ガイダンスを訊くことができます。その後、発信先に指定した電話へ着信がかかり、応答して発信した電話と通話ができれば成功です！
[
  {
    "premium": "true",
    "action": "talk",
    "language": "ja-JP",
    "style": "3",
    "text": "お繋ぎしますのでそのまま暫くお待ちください。"
  },
  {
    "endpoint": [
      {
        "type": "sip",
        "uri": "sip:8190********@kwc-hogehoge.sip-ap.vonage.com"
      }
    ],
    "eventUrl": [
      "https://*****"
    ],
    "eventMethod": "GET",
    "action": "connect",
    "from": "8150********",
    "timeout": "30"
  }
]

 発信音声ログの確認発信通話に成功したので Vonage にどのように記録されているかを「音声ログ」をみて確認してみましょう。今回の通話に該当するログは、下図のように 5 行のログになります。ログタイプは着信確認の時と同様に「電話（ PSTN / SIP ）」を選択してください。
外線電話（ PSTN ）から Vonage SIP Trunk への着信ログ
Vonage SIP Trunk から IP-PBX 用 PSIP への発信ログ
IP-PBX 用 PSIP への着信ログ
IP-PBX 用 PSIP からの発信ログ
Vonage SIP Trunk から外線電話（ PSTN ）への発信ログ


音声ログ



構成図

 PSIP の設定PSIP の設定は、紙面の節約も兼ねてこれまでに作成した SIP Trunk 設定を流用して実施していきたいと思います。「 Edit trunk 」を選択して、SIP Trunk の「 Type 」を「 Application 」へ変更します。変更すると関連付けるアプリケーションを選択できるようになるため、Vonage アプリケーションの設定で作成したアプリケーションを下図のように関連付けます。


SIP Trunk の編集


SIP Trunk のタイプの変更

 PSIP の動作確認PSIP へのアプリケーション関連付けが完了すると PSIP として利用可能です。ここまでに関連付けている電話番号へかけると、直接アプリケーションサーバーへリクエストが送信されます。アプリケーションが NCCO を返却すれば、その通りに Vonage が動作しますので、色々試してみてください。 PSIP は SIP 側からのリクエストにももちろん反応します。
サンプルとして、外部の SIP エンドポイントに接続したい場合は下記のような NCCO を Vonage へ渡すことで実現できますし、 SIP Trunk の動作と同じように外線の電話番号にも繋ぐことができます（外線接続の場合、 from には関連付けした Vonage 電話番号を指定する必要があります。接続先によって「 endpoint 」の記載方法が異なりますので、詳細は公式ドキュメントをご確認ください。
[
  {
    "action": "talk",
    "language": "ja-JP",
    "text": "お繋ぎしますので、そのまましばらくお待ちください。"
  },
  {
    "action": "connect",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "03xxxxyyyy",
    "endpoint": [
      {
        "type": "sip",
        "uri": "sip:fuga@example.net",
        "headers": { "location": "Tokyo" }
      }
    ]
  }
]

 BYOC の設定PSIP の説明が終わりましたので、最後に BYOC について紹介します。繰り返しになりますが、Vonage の中身としては BYOC は PSIP と同じ内容なので、 PSIP までの内容で基礎部分は網羅したことになります。 BYOC の特徴として、接続先となる電話番号提供サービスとは SIP による 1 対 1 の接続になるため、 SIP エンドポイントへの発信接続と SIP エンドポイントからの受信時の処理が重要になってきます。 下図の BYOC の利用イメージを確認しながら読み進めていただければと思います。

 SIP 受信と拡張ヘッダーの取得BYOC に限った内容ではありませんが、 SIP 通信を行う場合には様々な理由から拡張ヘッダーを用いて情報をやりとりするケースがあります。 SIP 通信の相手側が拡張ヘッダーを設定してきた場合に、それらを取得し、アプリケーション側で値を保存したりチェックしたりする場合がありますので紹介していきたいと思います。
電話番号提供サービス側から着信をを受けた際に、アプリケーション設定で指定した「回答 URL 」に以下のようなリクエストが付与されてきます。特に、SipHeader_X-AuthenticationとSipHeader_X-Inbound-VPSIPが拡張ヘッダーに該当しますが、SipHeader_X-Inbound-VPSIPは Vonage がデフォルトで付与しているものなので無視してください。つまり、以下の例ではSipHeader_X-Authenticationがリクエスト元の SIP エンドポイントが個別に付与してきた拡張ヘッダーに該当しますので、アプリケーションのプログラム側で当該拡張ヘッダーの検証を行って Vonage へ応答として返却する NCCO の内容に反映させることで着信処理を継続して別の宛先に繋いだり、切断したりといったことが可能です。
{'query_params':
  {
    'SipHeader_X-Authentication': '****************',
    'SipHeader_X-Inbound-VPSIP': 'true',
    'conversation_uuid': 'CON-********-****-****-****-************',
    'from': '090********',
    'region_url': 'https://api-ap-3.vonage.com',
    'to': '050********',
    'uuid': 'f*************************'
  }
  ... 省略
}

 SIP 送信と拡張ヘッダーの送信電話番号提供サービス側との取り決めで拡張ヘッダーを送信したい場合は、以下のような NCCO をアプリケーション側で生成して Vonage へ応答します。さらに、 UUI(User-to-User Information) ヘッダーを付与したい場合はこちらのドキュメントのstandardHeadersパラメータを付与して送信してください。

SIP の発信先と暗号化接続したい場合は、uriの末尾にsip:090********@sip.example.com;transport=tls;media=srtpといったようにtransport=tls;media=srtp指定を追記してください。
[
  ... 省略
  {
    "premium": "true",
    "action": "talk",
    "language": "ja-JP",
    "style": "3",
    "text": "お繋ぎしますのでそのまま暫くお待ちください。"
  },
  {
    "endpoint": [
      {
        "headers": {
          "Authentication": "****************"
        },
        "standardHeaders": {
          "User-to-User": "342342ef34;encoding=hex"
        },
        "type": "sip",
        "uri": "sip:080XXXXYYYY@*****"
      }
    ],
    "eventUrl": [
      "https://********"
    ],
    "eventMethod": "GET",
    "action": "connect",
    "from": "050XXXXYYYY",
    "timeout": "30"
  }
]

 おわりに冒頭でも少し触れていますが、 Vonage の SIP Trunking や PSIP はコンタクトセンターシステム、音声合成や AI による音声サービス、オフィスの電話システム、 IoT に連動した音声サービスとの連携といったように、 SIP に対応した既成の製品サービスや独自に開発した音声アプリケーションやシステムと SIP 経由であれば接続することができます。特に Vonage が既に保有している機能を Vonage に任せてしまうといった機能分担をすることで、高度なサービスをスピーディに構築することができます。

 参考Vonage NCCOについて
Vonage 開発スタートガイド
Vonageで電話番号を取得する方法
VCR を使ったブラウザ発着信の実装
NCCO Connect
NCCO SIP Connect 固有のパラメーター
SIP Dashboard
Programmable SIP
Programmable SIP API
Vonage が使用する IP アドレスレンジ
Voice API
Wireshark 

Vonage SIP Trunking
Asterisk Configuration
FreePBX
GenesysCloud

KWCPLUSPublication

株式会社KDDIウェブコミュニケーションズ Tech Blog

はじめに

本記事の対象となる読者

事前準備

Vonage とは

SIP とは

この記事のシナリオ

Vonage アプリケーションの設定

PSIP のイメージ図

アプリケーションメニューの選択

新しいアプリケーションを作成する

アプリケーション名と公開鍵の設定

公開鍵の確認と秘密鍵の保存

音声機能の有効化

アプリケーションの生成完了

IP-PBX 代用環境のための PSIP の設定

SIP Trunking イメージと IP-PBX を PSIP で代用した場合のイメージ図

IP-PBX 用に PSIP を追加

IP-PBX 用の PSIP 設定

IP-PBX 用の PSIP の確認

アプリケーションタイプへの変更

IP-PBX 用 PSIP の有効化準備

PSIP API による詳細情報の確認

cURL 実行例

cURL 実行結果

PSIP API による ACL の追加

cURL 実行例

cURL 実行結果

IP-PBX 用 PSIP の 動作確認

（参考）構成図

回答 URL の応答例と SIP Trunk （ IP-PBX ）への着信動作確認

着信音声ログの確認

SIP Trunk （ IP-PBX ）からの発信動作確認

SIP Trunk 設定の確認

Digest 認証の無効化と ACL の追加

IP-PBX 用 PSIP の応答内容の修正

発信音声ログの確認

PSIP の設定

PSIP の動作確認

BYOC の設定

SIP 受信と拡張ヘッダーの取得

SIP 送信と拡張ヘッダーの送信

おわりに

参考

Discussion

IP-PBX 用 PSIP の動作確認