Zenn
KWCPLUSPublicationへの投稿
🀄️

Postmanを使って、Vonage Voice API を理解しよう

高橋克己（□い芸人）
2024/05/10に公開
Vonage
cpaas
tech

はじめに

みなさん、こんにちは。KDDI ウェブコミュニケーションズで CPaaS のエバンジェリストをしている高橋です。
この記事では、Postman を使って Vonage Voice API の仕組みを理解していきます。

本記事の対象となる読者

  • Vonage Voice API を基礎から学習したい方
  • 通話を用いたシステムを開発しようとしている方
  • Postman を使った API のデバッグに興味のある方

事前準備

本記事の内容を実装するためには、あらかじめ以下の準備が必要になります。

  • Vonage アカウントを保有していること
  • Vonage で電話番号を購入していること
  • Postman がセットアップされていること

アカウントを持っていない方は、以下の記事を参考にアカウントを開設してください。

電話番号を持っていない方は、以下の記事を参考に電話番号を購入してください。

Postman のセットアップがまだの方は、以下のサイトからセットアップをお願いします。

Vonage とは

Vonage_logo

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

2024年2月14日より、株式会社KDDIウェブコミュニケーションズ（以後、KWC）が Vonage の再販事業を開始することとなりました。
KWC経由でアカウントを開設する場合、Vonageで直接開設したアカウントとは一部仕様が異なります。（※提供する機能面において違いはありません）

なお、本記事ではKWC経由でのアカウントを使って説明を行います。

Postman とは

Postman は、API を使ったサービスの開発にとても役立つツールです。
単純に API のテストを行うだけでなく、API コールを連続して実行する「フロー」や、API サーバーを模倣するための「モックサーバー」など、いくつもの便利な機能を持っています。

用語の整理

用語 説明
API Application Programming Interface の略で、サービスを外部から利用してもらうためのインターフェース
Rest API API を呼び出す際に利用され、HTTP の GET/PUT/UPDATE/DELETE を利用する
認可・認証 API を呼び出す際に 呼び出し元を確認する仕組みで、Basic 認証や JWT トークンを使った Bearer 認証などがある
Webhook API サーバー側から HTTP GET/POST を使って、指定したサーバーに各種情報を発信する仕組み
NCCO Vonage サーバーに対してどのような動作をさせるかを、JSON 形式で記述する

Vonage Voice API を使ってみよう

Vonage Voice API は、世界中の人々との電話を通じたコミュニケーションを実装できる API です。
単純な通話だけにとどまらず、50以上の言語に対応した機械音声の利用や、AI を組み合わせた自動応答システムを構築することができます。

今回はこの Vonage Voice API を使って実際に電話を架けながら、Vonage Voice API の仕組みを基礎から理解していきましょう。

今回のシナリオは、Vonage Voice API を使って電話を架けて、音声メッセージを相手に聞かせるというものです。

まずはフローをご覧ください。

Outbound Call Flow

今回のシナリオでは、以下のような流れとなります。

  1. ユーザー側のサーバーから、Vonage に対して架電APIをコールします。パラメータなどに間違いがなければ、Vonage から 200 応答が戻ります。
  2. Vonage は、指定された相手先のキャリアに対してシグナリング（呼び出しの依頼）を開始します。
  3. Vonage は、シグナリングを開始したことを、Event Webhook を使ってユーザー側サーバーに知らせます。このときのステータスはstartedです。
  4. キャリア側のサーバーは、相手先の電話番号の状態を確認し、呼び出しが可能な場合には呼び出しを開始します。と同時に、Vonage に対して呼び出しを開始したことを通知します。
  5. 呼び出しの開始通知を受けた Vonage は、再び Event Webhook を使ってユーザー側サーバーに知らせます。このときのステータスはringingです。
  6. 相手先の電話が応答すると、キャリア経由で Vonage に対して通知が届きます。
  7. Vonage はユーザー側サーバーの Answer URL で指定されたエンドポイントに NCCO を Webhook として要求します。
  8. ユーザー側サーバーは、相手先に聞かせたいメッセージを NCCO として Vonage に返却します。
  9. Vonage は指定された NCCO を解析し、音声メッセージをキャリア経由で相手の電話機に流します。
  10. 7と同じタイミングで、Vonage はユーザー側サーバーに対して、Event Webhook を送ります。このときのステータスはansweredです。
  11. Vonage は NCCO で指定されたメッセージを流し終わると、キャリア経由で電話の切断を指示します。その結果、通話が終了します。
  12. と同時に、Vonage は Event Webhook を使ってユーザー側サーバーに通話の終了を伝えます。このときのステータスはcompletedです。

アプリケーションの作成

まずは Vonage Voice アプリケーションを作成します。
Vonage では、アプリケーション単位に、購入した電話番号をリンクして利用します。

  • Vonage ダッシュボードにログインします。Vonage 本家でアカウントを作成した方は、こちらからログインしてください。
    Create Application

  • 左側のメニューからアプリケーションを選択します。

  • 右上の新しいアプリケーションを作成するをクリックします。

Voice Apps Settings

  • 名前欄には、「Postman」と入力します（名前は何でも構いません）。
  • 機能の中の音声のトグルスイッチをONにします。
  • 地域のプルダウンリストから「Singapore(api-ap-3.vonage.com)」を選択します。

Create Secret Key

  • 公開鍵と秘密鍵を生成ボタンをクリックします。
  • private.key という名前で秘密鍵がダウンロードされますので、private.pemという名前に変更して、なくさないように保管してください。
  • 右下の新しいアプリケーションの生成ボタンを押して、設定を保存します。
  • 作成したアプリケーションIDは後ほど利用するので、メモしておきましょう。

電話番号のリンク

作成したアプリケーションに対して、すでに Vonage で購入してある電話番号を紐づけます。

Link a number

  • すでに購入済みの電話番号から、今回のアプリケーションに紐づける番号を選択し、右側のリンクボタンを押します。
  • リンクボタンがリンク解除ボタンに変わります。
  • 設定した電話番号は後ほど使うのでメモしておいてください。

Postman の起動

ではここから、実際に Postman を使いながら上記のシナリオが正しく動作しているかを検証していきましょう。
今回 Postman が担うのは、先ほどのフローの一番左、Serverと書かれた部分になります。

まずは、Postman の準備をしていきます。

  • Postman を起動します。

モックサーバーを設定する

モックサーバーを使うことで、外部のサーバーから発行される Webhook を Postman が受け付けて、レスポンスを返すことができます。

  • 左側のメニューからモックサーバーを選択します。

Mock server

  • モックサーバーを作成をクリックします。

Mock server settings

  • 新しいコレクションを作成が選択されていることを確認します。
  • リクエストメソッドをPOSTに変更し、リクエスト URL を{{url}}/ event に変更します。
  • 同様にもう一行、POSTメソッドで、{{url}}/ answerという行も作成します。
  • 次に進むボタンを押します。

Mock server settings

  • モックサーバーの名前欄に、「Vonage Voice API Webhook」と入力します。
  • モックサーバーを作成ボタンを押します。

Mock server url

  • モックサーバーの URL が払い出されるので、コピーしておきます。

モックサーバーのレスポンスを設定

Event webhook

  • 左側のメニューから、コレクションを選択します。
  • 「Vonage Voice API Webhook」というコレクションができているので、それを展開します。
  • さらに「event」を展開して、「デフォルト」を選択します。
  • 画面下部（レスポンス）のボディに、「OK」と記載します。
  • 画面上部の保存アイコンをクリックします。

Answer webhook

  • 同様に、左側のコレクションから「answer」を展開し、「デフォルト」を選択します。
  • 画面下部（レスポンス）のボディで、「JSON」をプルダウンから選択します。
  • 以下の JSON をボディ部に記入します。
NCCO
[
    {
        "action": "talk",
        "text": "こんにちは。今日はとても良い天気ですね。",
        "language": "ja-JP",
        "style": 3,
        "premium": true
    }
]

この JSON は、日本語で「こんにちは。今日はとても良い天気ですね。」と音声を流す NCCO になります。
NCCO について詳しく知りたい方は、こちらをご覧ください。

  • 画面上部の保存アイコンをクリックします。

Webhook をテストする

  • 保存ボタンの下にある試すボタンをクリックします。
  • 以下の画面のように、200 OKとともに、指定した JSON が戻ってくることを確認します。

Webhook test

Postman を使って、発信 API をコールする

では最後に、発信 API を Postman を使って送信してみましょう。

API コールの前に、今回利用する API の情報を調べる必要があります。
具体的には、API のエンドポイント（URL）、メソッド、認証方法、パラメータを調べます。

今回は、Vonage Voice API の発信（Create an outbound call）を行う API を利用しますので、API リファレンスを調べてみましょう。

今回の API は、以下のように定義されています（今回利用するパラメータのみ抜粋）。

エンドポイント: https://api.nexmo.com/v1/calls
メソッド: POST
認証: JWT
パラメータ: answer_url、answer_method、to、from、event_url、event_method

認証とパラメータについては、もう少し補足をしておきましょう。

パラメータ

先ほどのリファレンスを見ると、必須のパラメータはanswer_urlとto、random_from_numberもしくはfromのいずれかです（今回はfromを使います）。
API の動作を確認するために、今回はオプションのevent_urlも利用します。また、answer_urlとevent_urlのメソッドを指定するanswer_methodとevent_methodも利用します。

answer_urlとevent_urlには、先ほど設定した Postman のモックサーバーを利用します。

認証

Vonage の API は、API の種類によって認証方法が変わります。詳しくは、こちらのページをご覧ください。
Voice API は、JWT を使うことが記載されています。

JWT（JSON Web Token）というのは、その名の通り、JSON 形式で記述するトークンで、トークンの中に有効期限や独自のパラメータを埋め込むことができます（ペイロード）。
Voice API の JWT 認証で使うペイロードは以下のように規定されています。

ペイロード
{
    "application_id": Vonage アプリケーションの ID,
    "iat": トークン生成時刻（UNIX時刻）,
    "jti": JWT をユニークに識別する文字列,
    "exp": トークン有効期限（UNIX時刻）
}

application_idは、先ほど作成したVonageのアプリケーションIDです。
iatとexpは UNIX時刻で指定する必要があります。

今回は、iatに現在時刻を指定し、expにはiatに3600を加算したもの（1時間後）を指定しますので、この時点で計算をしておいてください。
また、jtiにはユニーク値を指定する必要がありますが、今回はapplication_idと同じ値を利用することにします。

JWT ではトークン自体の改ざんを防止するために、証明書（秘密鍵）を使って署名を行います。

このような仕様から、JWT は通常、サーバーサイドで API をコールする直前に動的に生成するのが一般的です。ですが、テストするためにいちいち JWT を作成するプログラムを用意するのは大変です。
Postman には、JWT を作成する機能が用意されているので、今回はそちらを使っていきましょう。

API の生成

New Correction

  • 新しい API タブ（画面上部の＋アイコン）を作成します。
  • メソッドのリストから「POST」を選択します。
  • URL欄にhttps://api.nexmo.com/v1/callsと入力します。

Authentication settings

  • 認証タブを選択します。
  • Auth Typeのプルダウンリストから「JWT bearer」を選択します。
  • アルゴリズムのプルダウンリストから「RS256」を選択します。
  • ファイルを選択ボタンを押して、先程private.pemという名前で保存した秘密鍵を選択します。

Payload setting

  • ペイロードに、先程計算しておいた値を設定します。たとえば以下のようになります。
ペイロード例
{
    "application_id": "53ede750-092b-40e9-8788-9f1ceb40893d",
    "iat": 1715127546,
    "jti": "53ede750-092b-40e9-8788-9f1ceb40893d",
    "exp": 1715131146 
}

では最後に、ボディを作成していきましょう。

Body settings

  • ボディタブを選択します。
  • 形式は「Raw」と「JSON」を選択します。
  • 以下のような JSON を指定します。
ボディ例
{
    "answer_url": [
        "https://XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.mock.pstmn.io/answer"
    ],
    "answer_method": "POST",
    "event_url": [
        "https://XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.mock.pstmn.io/event"
    ],
    "event_method": "POST",
    "to": [
        {
            "type": "phone",
            "number": "81XXXXXXXXXX"
        }
   ],
   "from": {
        "type": "phone",
        "number": "8150XXXXXXXX"
    }
}
  • answer_urlとevent_urlは、先ほど設定したモックサーバーのアドレスに変更してください。
  • toのnumberには、発信先の電話番号を指定します。
  • fromのnumberには、Vonage で購入してアプリケーションにリンクした電話番号を指定します。

API をテストする

では、今作成した API コールを使って、実際に電話が架かるかをテストしてみましょう。

API test

  • 送信ボタンを押します。

画面下部のレスポンスボディにstatusがstartedに設定されている JSON が表示されれば成功です。
やがて指定した電話番号に電話が架かって、日本語でメッセージが流れます。

モックサーバーの確認

Check the mock server logs

  • 左側のメニューからモックサーバーを選択します。
  • ログを更新ボタンを押して、最新のログを表示させます。

正常に動作していれば、モックサーバーにはログが5つ表示されます。
eventへの Webhook では、それぞれステータスが先ほどのフローの通りに4つの順番（started → ringing → answered → completed）で届いていることが確認できます。

エラーパターン

API コールがエラーになる原因は様々です。ここでは代表的なエラーについて解説します。

認証エラー

秘密鍵が異なる場合や、JWT の有効期限が切れている場合など、認証でエラーになった場合には、以下のような JSON が戻ります。

認証でエラー
{
    "type": "UNAUTHORIZED",
    "error_title": "Unauthorized"
}

JWT の設定で指定をした各種情報を再度見直してください。

パラメータエラー

API コールに必要なパラメータが指定されていない場合や、パラメータ値が間違っているような場合は、以下のような JSON が戻ります。

パラメータエラー
{
    "type": 400,
    "title": "Bad Request",
    "invalid_parameters": [
        {
            "reason": "cannot be empty or NULL",
            "name": "to"
        }
    ]
}

上記のエラーは、必須パラメータであるtoにエラーがあることを示しています。

相手先電話番号間違い

相手先の電話番号が存在しない場合は、レスポンスではエラーにはならず、Event Webhook でエラーが通知されます。

Wrong phone number

この例では、相手先電話番号に819000000000という存在しない番号を指定しています。
そのため、Event Webhook で、detailにunavailable（利用不可）が戻ってきています。

このように、実際に API を使ったサービスを開発する際に、エラーを擬似的に発生させることで、どのような値が戻ってくるのかを検証するうえでも Postman は有効です。

まとめ

今回は、API 開発ツールである Postman を使って、Vonage Voice API の仕組みやエラー対応などを検証してみました。
本来であれば、VCR（Vonage Cloud Runtime）などを使って、サーバー環境を別途用意する必要がありますが、今回のように Postman を利用することで、比較的簡単に API のテストや動作の確認ができます。

ぜひ Postman を活用してみてください。

KWCPLUS
KWCPLUSPublication

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

Discussion