🀄️

Vonage Voice & Messages API 基礎ハンズオン

高橋克己（□い芸人）

2024/07/23に公開

Vonage

cpaas

tech

 はじめにみなさん、こんにちは。KDDI ウェブコミュニケーションズで CPaaS のエバンジェリストをしている高橋です。

この記事は、Postman を使って Vonage Messages API / Voice API の基礎を学ぶハンズオンとなっています。

 本記事の対象となる読者Vonage Voice API や Messages API を基礎から学習したい方
通話を用いたシステムを開発しようとしている方
SMS を用いたシステムを開発しようとしている方
Postman を使った API のデバッグに興味のある方

 事前準備本記事の内容を実装するためには、あらかじめ以下の準備が必要になります。
Vonage アカウントを保有していること
Vonage で電話番号を購入していること
Vonage クーポンコード（トライアルアカウントで電話番号を購入する際に必要です）
Postman がセットアップされていること
アカウントを持っていない方は、以下の記事を参考にアカウントを開設してください。
電話番号を持っていない方は、以下の記事を参考に電話番号を購入してください。
!テストに使用する電話番号は日本のものでなくとも大丈夫です。米国の番号でもテストできます。ただしその場合、発信者番号が海外番号になったり、非通知になったりすることがありますのでご注意ください。
Postman のセットアップがまだの方は、以下のサイトからセットアップをお願いします。
!Postman には有償版と無料版がありますが、今回は無料版を使います。

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

もともとは VoIP（Voice over IP）企業としてスタートしましたが、いくつかの企業買収を行うことで、コミュニケーションサービス全般をサポートすることができる企業に発展しました。現在はスウェーデンの大手通信機器会社エリクソンの傘下に入っています。
2024年2月14日より、株式会社KDDIウェブコミュニケーションズ（以後、KWC）が Vonage の再販事業を開始することとなりました。

KWC経由でアカウントを開設する場合、Vonageで直接開設したアカウントとは一部仕様が異なります。（※提供する機能面において違いはありません）
!KWC経由でのアカウント作成は、法人もしくは個人事業主であることが条件となります。個人でのアカウント開設をされる方はVonage本家からアカウントを作成してください。

 Postman とはPostman は、API を使ったサービスの開発にとても役立つツールです。

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

 用語の整理

用語
説明


API
Application Programming Interface の略で、サービスを外部から利用してもらうためのインターフェース

Rest API
API を呼び出す際に利用され、HTTP の GET/POST/PUT/DELETE を利用する

認証・認可
API を呼び出す際に 呼び出し元を確認する仕組みで、Basic 認証や JWT を使った Bearer 認証などがある

Webhook
API サーバー側から HTTP GET/POST を使って、指定したサーバーに各種情報を発信する仕組み

NCCO
Vonage サーバーに対してどのような動作をさせるかを、JSON 形式で記述する


 Vonage Messages API を使ってみようVonage Messages API は、SMSだけでなく、WhatsApp や Facebook Messenger などのSNSに対しても、API を通じてメッセージの送信が可能です。
!VonageでSMSを送信する手段としてはVonage SMS APIも用意されていますが、こちらは文字コードを指定しないと日本語を送れないため、今回は新しい API である Vonage Messages API を利用します。
今回のシナリオでは、Postman の API コレクションを使って、実際にSMSを送信してみたいと思います。

トライアルアカウントでは、アカウント作成時に利用した携帯電話か、検証済み電話番号にしか SMS が送信できません。

 Messages API の仕様を確認するAPI コールをするためには、まずは API の仕様を調べる必要があります。

Vonage Messages API のリファレンスは、以下のページにあります。
API を調べるポイントは、大きく以下の3つです。
エンドポイントとメソッド
認証・認可方法
Body、もしくはQueryString
今回のエンドポイントは、以下のとおりです。

認証は以下のとおりです。

この API は2種類の認証（JWT認証とBasic認証）をサポートしています。

JWTの方が認証としては強固なのですが、一方でPKIの準備と時間情報（トークンの有効期限など）を必要とするため少々面倒です。

後ほど実施するVoice API では JWT のみがサポートされるため、JWT の生成についてはそちらに任せるとして、ここでは API Key と API Secret を使ったBasic認証で進めます。
SMS を送信する際の Body は以下のとおりです（今回利用するもののみ抜粋）。


大項目
説明


text
送信する本文を指定します（日本語利用可）。文字コードGSM-7（半角英数）だけの場合で160文字、UCS-2（全角）を含む場合は全体で70文字で1セグメントとしてカウントされます。それ以上の文字を送信すると、セグメントが分割されます。最大送信文字数は、GSM-7のみの場合で3,800文字、UCS-2が含まれる場合は最大660文字となります。

to
送信先の電話番号をMSISDN形式で指定します（例：819012345678）

from
日本宛のSMSは、電話番号形式は利用できないため、英数字で指定をします（例：VONAGE）最大11文字

channel
'sms'と指定します。

client_ref
Webhookを受け取る際に、送信したSMSを識別するために100文字以内の文字列を指定できます

ttl
SMS送信を行う際の許容する遅延時間を秒で指定します（300以上、デフォルトは90000）

webhook_url
webhookの送信先URLを指定します

message_type
'text'と指定します


 Messages API の Webhook についてWebhook を使うことで、SMSを送信した際の送信状況を取得できます。

Message Status に関する Webhook の仕様は以下に記載されています。
Webhook で渡されるパラメータは以下のとおりです（主要なものを抜粋）。


パラメータ名
値の説明


message_uuid
メッセージのユニークID

to
送信先の電話番号（MSISDN形式）

from
送信元番号、もしくは文字列

timestamp
送信日時（ISO8601形式）

status
配信ステータス（submitted/delivered/rejected/undeliverable）

error
エラーが発生した場合の詳細

client_ref
送信時に指定したclient_ref


usage
利用料（EURのみ）


 配信ステータスについてSMS の受信確認の仕組みは次のようになっています（Vonage サイトより抜粋）。
この図の中のDelivery ReceiptをDLR（受信確認）と呼んでいます。

受信確認 (DLR) は次のいずれかのタイミングで返信されます。
通信会社 - サービスプロバイダーがメッセージを受信したとき
携帯電話 - ユーザーの携帯電話にメッセージが到達したとき
!DLRを受け取ることによって、SMSの配信が100%成功したわけではないことに注意が必要です。

通信会社に届いた時点でDLRが返却されることもあれば、途中の配信事業者がフェイクDLRを返却する可能性もあるためです。

そのため、Vonage では DLR の正確性を 100% 保証していません。
では、Webhook で返されるステータスの詳細を確認しましょう。

上記の表にあるとおり、Messages API で戻って来るステータスは以下の4つの中のいずれかです。


ステータス
説明


submitted
SMSの配信を受け付けました

delivered
先方からDLRを受信しました

rejected
送信処理が拒否されました

undeliverable
送信処理が失敗しました

submittedは、Vonage がAPIを受け付けたことを表します。その後、先方のキャリア経由でDLRが戻ってきたらdeliveredが返ります。

後者の2つについては、エラーの詳細を確認できます。

エラーの詳細はこちらに記載があります。

ちなみに、携帯電話の電源が切れていたり、圏外にいる場合はrejectedが戻ります。
!SMS は通常、文字コードGSM-7（半角英数）だけの場合で160文字、UCS-2（全角）を含む場合は全体で70文字で1セグメントとしてカウントされます。それ以上の文字を送信すると、セグメントが分割されます。

Messages API を利用してメッセージが複数セグメントに分かれてしまった場合、Webhookは最初のセグメントに対してしか発行されません。

 配送方式の違いによる差分Vonage Messages API では、国際ルート（国際SMS）による配送と国内直収接続による配送（国内直収SMS）の2種類があります。

 国際ルート（国際SMS）海外キャリアを経由して国内キャリアに届く、Vonageの標準的な配送方法となります。国内直収SMSに比べると到達率は悪くなります。

国際ルートを使った場合、日本国内へのSMS送信時に、電話番号を表示させることができません。代わりに文字列（Alphanumeric Sender ID）を指定できます。
国際ルートを使った場合に、ユーザーが電源を切っていた場合や圏外の場合は、キャリアからrejectedが戻りますので、必要に応じて再送の仕組みを実装する必要があります。

 国内ルート（国内直収SMS）国内直収SMSの場合は、到達率は99%となります（電話番号間違いなどの配信エラーは除く）。

また、国際ルートと異なり、ユーザーが電源を切っていた場合や圏外の場合はキャリアが再送を行います。その反面、DLRが戻るのが遅くなります。
!国内直収SMSを利用するためには事前に審査と設定作業が必要となりますので、ご希望の方はこちらからお問い合わせください。

 Messages API を使って、SMSを送信してみるではここから、実際にSMSを送信してみたいと思います。送信には、Postmanを利用します。

また、Webhookの受け先として、同じくPostmanのモックサーバーを利用したいと思います。
APIをコールする際に必要となる、Vonage の API Key と API Secret は事前に確認しておいてください。

 Postmanでワークスペースを作成まずは、Postmanの設定を行います。作業用のワークスペースを作成し、Webhook を受け付けるためのモックサーバーを作成します。

その後、コレクションを作成して実際のAPIコールを行います。
Postmanを起動します。
!Postmanを日本語化するには、画面上部の歯車アイコンを選択し、設定 > 一般 の中のアプリケーションで言語の設定をしてください。



また、その下にある自動保存も有効にしておくと、今後の手順で保存作業をしなくても自動保存されるようになるので便利です。
トップにあるワークスペースプルダウンからワークスペースを作成ボタンを押します。
「空のワークスペース」が選択されているのを確認し、次に進むボタンを押します。

名前フィールドに「Vonage Handson」と入力し、作成ボタンを押します。
これで作業用のワークスペースが完成しました。
このあと利用する機能が非表示になっているので有効にします。
左側のサイドバーの設定アイコンを押します。

モックサーバーとフローをONにします。

 モックサーバーを作成次に、Webhookの受け先としてモックサーバーを設定します。
!モックサーバーを使うことで、Webhook を簡易的に受け付けるサーバーを用意できます。

Webhook の URL だけでなく、ヘッダーやボディのパターンによって、返却する値を変えることもできるので、Webhook のテストなどにとても重宝します。
サイドメニューのモックサーバーを選択します。

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

リクエストメソッドのプルダウンから「POST」を選択します。

リクエストURLに、「webhook/status」と入力します。

レスポンスボディに、「OK」と入力します。

次に進むボタンを押します。

モックサーバーの名前欄に「Webhook」と入力します。

モックサーバーを作成ボタンを押します。
モックサーバーができたら、生成されたモックサーバーのURLをメモしておきましょう。

 環境変数を作成次に、APIキーなどの変数を環境変数に登録しておきましょう。
!環境変数を利用することで、秘匿すべきデータを守るだけでなく、API リクエストに直接変数を書く必要がなくなります。

また、環境変数に名前をつけてグルーピングすることができるので、開発用と本番用の変数を別に登録しておくといったことが可能です。
左側の環境アイコンを選択して、環境を作成をクリックします。
環境変数名を「2024-07-26」に変更します。
変数を登録していきます。登録する変数は以下の通りです。


変数
タイプ
初期値
現在値


API Key
デフォルト
YOUR_API_KEY
ご自分の Vonage API Key を指定してください

API Secret
デフォルト
YOUR_API_SECRET
ご自分の Vonage Secret Key を指定してください

Mock URL
デフォルト
YOUR_MOCK_URL
先ほど作成したモックサーバーの URL を指定してください

最後に保存ボタンを押して変数を保存します。

 コレクションの作成ではいよいよここから Messages API を呼び出していきます。そのために、まずはコレクションを作成します。

API のリクエストをグループ化して管理するのがコレクションになります。
!コレクションに対して認証・認可を設定しておくことで、その配下のリクエストにコレクションの設定を継承させることができます。

これによって、リクエストごとの個別の設定が不要になるため便利です。
左側のコレクションアイコンを選択し、さらにプラスアイコンを押して新しいコレクションを作成します。
コレクション名に「Vonage Messages API」と入力します。
左上の環境プルダウンから、先ほど作成した環境変数「2024-07-26」を選択します。

認可タブに移動します。

Auth Typeプルダウンから「Basic認証」を選択します。

ユーザー名欄で、{{API Key}}と入力します（波括弧を入力すると変数名がリストされるのでそれを選択します）。

パスワード欄で、{{API Secret}}と入力します。
右上のハンバーガーメニューから「保存」を選択して、認証設定を保存します。
左側のコレクションリスト「Vonage Messages API」の中に記載されているリクエストを追加をクリックして、リクエストを作成します。
リクエストの名前を「Send a message」に変更します。
メソッドを「POST」に変更します。
リクエストURL欄にhttps://api.nexmo.com/v1/messagesと入力します。

ボディタブを選択します。
ボディのタイプを「Raw」に変更し、形式を「JSON」とします。
以下のJSONをコピペして貼り付けます。
{
    "text": "Messages APIのテスト",
    "to": "8190XXXXXXXX",
    "from": "HANDSON",
    "channel": "sms",
    "webhook_url": "{{Mock URL}}/webhook/status",
    "client_ref": "test phone",
    "message_type": "text"
}
toの部分は、ご自分の携帯電話の電話番号をMSISDN形式で指定してください。

例：08012345678 → 818012345678
最後に、保存ボタンを押して保存します。

 リクエストを発行ではさっそくリクエストを発行してSMSが届くことを確認しましょう。

送信ボタンを押します。
SMSが届き、202 Acceptedが表示されることを確認します。
!もし401エラーが出た場合は、コレクションの認証・認可設定が保存されていないか、環境変数が正しく選択されていない可能性があります。

 Webhook を確認左側のモックサーバーアイコンを選択します。
先ほど作成した「Webhook」を選択します。
送信が成功した場合は、Webhook が2つ届いていることが確認できます。最初の Webhook のステータスは、submittedで、2つ目のステータスはdeliveredになっていることを確認します。
!もしログが表示されない場合は、ログを更新をクリックしてください。ログが反映されるまでに少しタイムラグがあります。
もし余裕があれば、電話番号を架空の番号にしたり、スマホの電源を切った状態で送信するなどして、レスポンスがどのようになるかを確認することもできますので、ぜひやってみてください。

 料金についてSMSの送信料は、キャリアによって異なります。KWC経由のアカウントでは、国内キャリア宛の国際SMSの送信料は、1通（セグメント）11円（税込み）です。

料金については、Vonage からの Webhook の中にも載っていますが、こちらは EUR での金額になります。

 大量送信についてMessages API を使って送信できる速度（MPS）は、API キー単位で1秒間に30通です。

それ以上の送信を行おうとすると、API コールがエラーになります。
また、同一番号宛に大量の SMS を送信することで、Vonage 側で不正アクセスと判断されることがあります。その場合は、DLR エラーコードに99が戻ります。

万が一そのような状況になった場合は、サポート経由で不正判定を解除する必要があります（ホワイトリストへの登録）。

 不正アクセス対策SMS を狙った不正アクセスが非常に増えてきています。

Vonage には、海外向けに大量の SMS を送信されてしまわないように、不正行為を防止する機能が用意されています。

あらかじめ送信する国が決まっている場合は、これらの機能を活用して不正対策を行っておくことをおすすめします。

なお、この機能は SMS だけでなく Voice にも適用できます。

 Vonage Voice API を使ってみようVonage Voice API は、世界中の人々との電話を通じたコミュニケーションを実装できる API です。

単純な通話だけにとどまらず、50以上の言語に対応した機械音声の利用や、AI を組み合わせた自動応答システムを構築することができます。
今回はこの Vonage Voice API を使って実際に電話をかけながら、Vonage Voice API の仕組みを基礎から理解していきましょう。
今回のシナリオは、Vonage Voice API を使って電話をかけて、音声メッセージを相手に聞かせるというものです。

 アプリケーションの作成まずは Vonage Voice アプリケーションを作成します。

Vonage では、アプリケーション単位に、購入した電話番号をリンクして利用します。
Vonage ダッシュボードにログインします。Vonage 本家でアカウントを作成した方は、こちらからログインしてください。

左側のメニューからアプリケーションを選択します。
右上の新しいアプリケーションを作成するをクリックします。

名前欄には、「Postman」と入力します（名前は何でも構いません）。

機能の中の音声のトグルスイッチをONにします。

地域のプルダウンリストから「Singapore(api-ap-3.vonage.com)」を選択します。
!本来は、回答URLとイベントURLを指定する必要がありますが、今回は発信 API をコールする際にそれぞれを指定するので、ここでは空欄のままにしておきます。

着信のテストをする場合は、これらのフィールドは指定しておく必要があります。

公開鍵と秘密鍵を生成ボタンをクリックします。

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

 電話番号のリンク作成したアプリケーションに対して、すでに Vonage で購入してある電話番号を紐づけます。
すでに購入済みの電話番号から、今回のアプリケーションに紐づける番号を選択し、右側のリンクボタンを押します。

リンクボタンがリンク解除ボタンに変わります。
設定した電話番号は後ほど使うのでメモしておいてください。

 Postman の起動ではここから、実際に Postman を使いながら上記のシナリオが正しく動作しているかを検証していきましょう。
まずは、Postman の準備をしていきます。
Postman を起動します。

 環境変数を設定する左側のサイドメニューから環境をクリックし、先ほど作成した「2024-07-26」を選択します。
以下の内容で環境変数を設定していきます。


変数
タイプ
初期値
現在値


Private Key
デフォルト
YOUR_PRIVATE_KEY
さきほど保存したprivate.keyをエディタなどで開き、すべてを貼り付けます。

Application ID
デフォルト
YOUR_APPLICATION_ID
先ほどメモをしておいたアプリケーションIDを貼り付けます。

From
デフォルト
VONAGE_NUMBER
購入した電話番号を貼り付けます。番号はMSISDN形式で登録してください。

iat
デフォルト
CURRENT_UNIX_TIME
「0」を登録しておきます。この値は API コールをする際に、現在の日付に更新します。

To
デフォルト
YOUR_NUMBER
ご自分の携帯電話の番号をMSISDN形式で登録します。


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

ここでは先ほど作成したモックサーバーのコレクションに新たにリクエストを作成していきます。
サイドメニューからコレクションを選択します。
先ほど作成したモックサーバー用のコレクション「Webhook」の中のwebhook/statusの右側にあるハンバーガーメニューから複製を選択します。
リクエスト名を「webhook/answer」にします。
リクエスト URL を「{{url}}/webhook/answer」 に変更します。

保存ボタンを押して設定を保存します。
左側の「webhook/answer」を展開し、「デフォルト」を選択します。
POST する URL を/webhook/answerに変更します。
画面下部のボディで、「JSON」をプルダウンから選択します。
以下の JSON をボディ部に記入します。
NCCO
[
    {
        "action": "talk",
        "text": "こんにちは。今日はとても良い天気ですね。",
        "language": "ja-JP",
        "style": 3,
        "premium": true
    }
]
この JSON は、日本語で「こんにちは。今日はとても良い天気ですね。」と音声を流す NCCO になります。

NCCO について詳しく知りたい方は、こちらをご覧ください。
画面上部の保存アイコンをクリックします。
保存ボタンの下にある試すボタンをクリックします。
以下の画面のように、200 OKとともに、指定した JSON が戻ってくることを確認します。

 発信 API をコールするでは、発信 API を Postman を使って送信してみましょう。

まずは、今回利用する API の情報を調べます。
今回は、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
!この API には、NCCO を直接記述する方法も用意されていますが、今回はそちらは使わず、Answer URL を利用する API を使います。
認証とパラメータについては、もう少し補足をしておきましょう。

 パラメータ先ほどのリファレンスを見ると、必須のパラメータはanswer_urlとto、random_from_numberもしくはfromのいずれかです（今回はfromを使います）。

API の動作を確認するために、今回はオプションのevent_urlも利用します。また、answer_urlとevent_urlのメソッドを指定するanswer_methodとevent_methodも利用します。
answer_urlとevent_urlには、先ほど設定した Postman のモックサーバーを利用します。

 answer_url と event_urlevent_url は、発信状況を確認するために利用される Webhook になります。　　

電話の世界では、発信すれば必ず相手が応答するとは限りません。例えば話し中だったり、相手が応答しなかったり、さらには相手側が着信拒否をすることもあります。

このように、さまざまなステータスが存在するので、それを通知してくれる Webhook がevent_urlになります。
一方、answer_urlは、発信動作中に相手が応答したときの動作を指示するために使用される Webhook です。

具体的には、この Webhook 先で、NCCO を返却することで、たとえば相手に特定の音声を聞かせたり、音声ファイルを再生したりできます。
このように、発信時には2つの Webhook を使い分ける必要があります。

 認証Vonage の API は、API の種類によって認証方法が変わります。

詳しくは、こちらのページをご覧ください。

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

Voice API の JWT 認証で使うペイロードは以下のように規定されています（必須項目のみ）。
ペイロード
{
    "application_id": Vonage アプリケーションの ID,
    "iat": トークン生成時刻（UNIX時刻）,
    "jti": JWT をユニークに識別する文字列
}
application_idは、先ほど作成したVonageのアプリケーションIDです。

iatは UNIX時刻で指定する必要があります。トークンの有効期限はexpパラメータで指定することもできますが、デフォルトの有効期限はトークン作成から15分です。

jtiにはユニーク値を指定する必要がありますが、今回はapplication_idと同じ値を利用することにします。
!UNIX時刻とは、1970年1月1日0時0分0秒を0とした経過秒数の値です（1秒に1ずつ増えます）。
JWT ではトークン自体の改ざんを防止するために、証明書（秘密鍵）を使って署名を行います。
このような仕様から、JWT は通常、サーバーサイドで API をコールする直前に動的に生成するのが一般的です。ですが、テストするためにいちいち JWT を作成するプログラムを用意するのは大変です。

Postman には、JWT を作成する機能が用意されているので、今回はそちらを使っていきましょう。

 API の生成新しいコレクションを作成するので、画面上部の＋アイコンをクリックします。
コレクション名を「Vonage Voice API」とします。

認可タブを開きます。

Auth Typeプルダウンリストから「JWT Bearer」を選択します。

アルゴリズムは、「RS256」を選択します。

秘密鍵は環境変数から値を参照するので、{{Private Key}}と指定します。

ペイロードには、以下のような JSON を指定します。
Payload
{
    "application_id": "{{Application ID}}",
    "iat": {{iat}},
    "jti": "{{Application ID}}"
}
右側にあるハンバーガーメニューから、保存を選択してコレクションの設定を保存します。
作成したコレクションの下に表示されているリクエストを追加をクリックします。
リクエスト名は「Create a call」とします。
リクエストメソッドは、「POST」を選択します。
URL欄にhttps://api.nexmo.com/v1/callsと入力します。
次に、ボディを作成していきましょう。

ボディタブを選択します。
形式は「Raw」と「JSON」を選択します。
以下のような JSON を指定します。
ボディ例
{
    "answer_url": [
        "{{Mock URL}}/webhook/answer"
    ],
    "answer_method": "POST",
    "event_url": [
        "{{Mock URL}}/webhook/status"
    ],
    "event_method": "POST",
    "to": [
        {
            "type": "phone",
            "number": "{{To}}"
        }
   ],
   "from": {
        "type": "phone",
        "number": "{{From}}"
    }
}

保存ボタンを押して、設定を保存します。

 API をテストするでは、今作成した API コールを使って、実際に電話がかかるかをテストしてみましょう。
テストする前に、JWT のペイロードで必要となるiatの値（現在のUNIX時刻）を更新しておく必要があります。

現在のUNIX時刻を計算するには、こちらのサイトを利用するとよいでしょう。
左側のサイドメニューから環境を選択します。
「2024-07-26」を選択します。
掲載した現在のUNIX時刻をiatの現在値に指定します。

保存ボタンを押します。
左側のサイドメニューからコレクションを選択します。
「Vonage Voice API」の中の「Create a call」を選択します。

送信ボタンを押します。
以下のように、ボディが戻ってきて電話がかかってくることも確認しましょう。
!もし401エラーが出た場合は、以下の内容を確認してみてください。

iatの値が15分以上前ではないか（有効期限は15分です）
コレクションの環境変数名が間違っていないか（Application ID/iat/Private Key）
環境変数が正しく設定されているか
コレクションを保存してあるか（右上のハンバーガーメニューから保存をすること）

送信ボタンを押します。
画面下部のレスポンスボディにstatusがstartedに設定されている JSON が表示されれば成功です。

やがて指定した電話番号に電話がかかって、日本語でメッセージが流れます。

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

ログを更新ボタンを押して、最新のログを表示させます。
正常に動作していれば、モックサーバーにはログが5つ表示されます。

statusへの Webhook では、それぞれステータスは4つの順番（started → ringing → answered → completed）で届いていることが確認できます。
!電話の仕組み上、本来はstartedが発生してから相手側キャリアにシグナリングを送り、相手側のringingを受けてからユーザー側サーバーにringingを戻すはずなのですが、Vonage ではstartedを返したとほぼ同時にringingが戻ってきます。

よって、startedとringingの順番が変わることがあるだけでなく、実際には呼び出しがされていないケース（電源が切れている場合など）でもringingが戻りますので注意が必要です。
今回の架電の詳細は以下のフローを参考にしてください。
この図のServerと書かれた部分が Postman になります。

 イベントWebhookVonage から送信されるイベント Webhook には、以下のようなステータスがあります。

これらを判断することで、たとえば相手が応答しなかったときや話中だったときの判定を行うことができます。

 エラーパターンAPI コールがエラーになる原因はさまざまです。ここでは代表的なエラーについて解説します。

 認証エラー秘密鍵が異なる場合や、JWT の有効期限が切れている場合など、認証でエラーになった場合には、以下のような JSON が戻ります。
認証でエラー
{
    "type": "UNAUTHORIZED",
    "error_title": "Unauthorized"
}
JWT の設定で指定をした各種情報を再度見直してください。
!以下のサイトを利用すると JWT の内容を確認することができるので便利です。

 パラメータエラーAPI コールに必要なパラメータが指定されていない場合や、パラメータ値が間違っているような場合は、以下のような JSON が戻ります。
パラメータエラー
{
    "type": 400,
    "title": "Bad Request",
    "invalid_parameters": [
        {
            "reason": "cannot be empty or NULL",
            "name": "to"
        }
    ]
}
上記のエラーは、必須パラメータであるtoにエラーがあることを示しています。

 相手先電話番号間違い相手先の電話番号が存在しない場合は、レスポンスではエラーにはならず、Event Webhook でエラーが通知されます。
この例では、相手先電話番号に819000000000という存在しない番号を指定しています。

そのため、Event Webhook で、detailにunavailable（利用不可）が戻ってきています。
このように、実際に API を使ったサービスを開発する際に、エラーを擬似的に発生させることで、どのような値が戻ってくるのかを検証するうえでも Postman は有効です。

 Postman Flows を使って iat を自動生成先ほどの API コールでは、毎回iatを手動で設定しなくてはいけません。

そのため、iatを自動で生成するために、Postman Flows を使ってみたいと思います。
!Postman Flows とは、ブロックと呼ばれる部品をつなぎ合わせることで、複数の API リクエストを連続して実行したり、結果や変数を計算することができるノーコード・ローコードツールです。

計算だけでなく、分岐やロギングといった機能も持っています。
左側のサイドメニューからフローを選択します。
＋アイコンをクリックし、「Create new Flow」を選択します。
フローの名前は「Create a call」とします。

Startの右側のコネクタにマウスを当ててドラッグし、適当な場所で離します。
ブロックリストが表示されるので、「Send Request」を選択します。
リクエストの選択から、「Create a call」を選択します。
このリクエストで利用する環境を「2024-07-26」にします。
右下のBlockボタンを押して、「Evaluate」ブロックを選択します。
Evaluate ブロックに、現在の UNIX時刻を計算する次の式を記載します。

$floor($millis($now())/1000)

Resultのコネクタを、「Send Request」ブロックのiatにつなげます。
再びBlockボタンを押して、「Log」ブロックを選択します。
Evaluate ブロックのResultコネクタと、今追加した Log ブロックをつなぎます。
同様に、もう一つ Log ブロックを追加し、「Send request」ブロックのSuccessとFailコネクタとつなぎます。
ではいよいよフローを実行していきます。
画面下部にあるコンソールをクリックして、コンソールウィンドウを開きます。
画面下部のRunボタンを押して、フローを実行します。
以下のように、UNIX時刻と API コールの結果がコンソール上に表示されれば成功です。

電話がかかってくることも確認しておいてください。
以上で発信に関する API はすべて終了です。

 着信の動作について今回は発信の仕組みについて学習をしましたが、着信の動作についても解説をします。
アプリケーションに紐づけられた電話番号に着信が発生すると、アプリケーションの音声設定の中にある回答URLに対して、Vonage から Webhook が発行されます。

Webhook 先では、NCCO を使ってコールフローを返却する必要があります。

たとえば、以下の NCCO は転送ガイダンスを流したあと、別の番号に電話を転送することを意味します。
NCCO
[
  {
    "action": "talk",
    "text": "電話を転送します。",
    "language": "ja-JP",
    "style": 3,
    "premium": true
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "timeout": "45",
    "from": "8150XXXXXXXX",
    "endpoint": [
      {
        "type": "phone",
        "number": "8180XXXXXXXX"
      }
    ]
  }
]
また、より複雑な着信動作を設定したい場合は、Vonage AI Studio を利用することもできます。

AI Studio をより詳しく知りたい方は、以下のハンズオンの記事を参考にしてみてください。

 まとめ今回は、API 開発ツールである Postman を使って、Vonage Messages API や Voice API の仕組みやエラー対応などを検証してみました。

本来であれば、VCR（Vonage Cloud Runtime）などを使って、サーバー環境を別途用意する必要がありますが、今回のように Postman を利用することで、比較的簡単に API のテストや動作の確認ができます。

 後片付けこのままの状態で放置すると、電話番号の利用料が毎月発生します。

料金を発生しないようにするためには、購入した電話番号をリリースしておきましょう。
Vonage ダッシュボードにログインします。

番号メニューを展開し、あなたの番号を選択します。

リリースしたい番号の右側にあるゴミ箱アイコンをクリックすることで番号を削除できます。

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

大項目	説明
text	送信する本文を指定します（日本語利用可）。文字コードGSM-7（半角英数）だけの場合で160文字、UCS-2（全角）を含む場合は全体で70文字で1セグメントとしてカウントされます。それ以上の文字を送信すると、セグメントが分割されます。最大送信文字数は、GSM-7のみの場合で3,800文字、UCS-2が含まれる場合は最大660文字となります。
to	送信先の電話番号をMSISDN形式で指定します（例：819012345678）
from	日本宛のSMSは、電話番号形式は利用できないため、英数字で指定をします（例：VONAGE）最大11文字
channel	'sms'と指定します。
client_ref	Webhookを受け取る際に、送信したSMSを識別するために100文字以内の文字列を指定できます
ttl	SMS送信を行う際の許容する遅延時間を秒で指定します（300以上、デフォルトは90000）
webhook_url	webhookの送信先URLを指定します
message_type	'text'と指定します

パラメータ名	値の説明
message_uuid	メッセージのユニークID
to	送信先の電話番号（MSISDN形式）
from	送信元番号、もしくは文字列
timestamp	送信日時（ISO8601形式）
status	配信ステータス（`submitted`/`delivered`/`rejected`/`undeliverable`）
error	エラーが発生した場合の詳細
client_ref	送信時に指定した`client_ref`
usage	利用料（EURのみ）

ステータス	説明
submitted	SMSの配信を受け付けました
delivered	先方からDLRを受信しました
rejected	送信処理が拒否されました
undeliverable	送信処理が失敗しました

変数	タイプ	初期値	現在値
API Key	デフォルト	YOUR_API_KEY	ご自分の Vonage API Key を指定してください
API Secret	デフォルト	YOUR_API_SECRET	ご自分の Vonage Secret Key を指定してください
Mock URL	デフォルト	YOUR_MOCK_URL	先ほど作成したモックサーバーの URL を指定してください

変数	タイプ	初期値	現在値
Private Key	デフォルト	YOUR_PRIVATE_KEY	さきほど保存した`private.key`をエディタなどで開き、すべてを貼り付けます。
Application ID	デフォルト	YOUR_APPLICATION_ID	先ほどメモをしておいたアプリケーションIDを貼り付けます。
From	デフォルト	VONAGE_NUMBER	購入した電話番号を貼り付けます。番号はMSISDN形式で登録してください。
iat	デフォルト	CURRENT_UNIX_TIME	「0」を登録しておきます。この値は API コールをする際に、現在の日付に更新します。
To	デフォルト	YOUR_NUMBER	ご自分の携帯電話の番号をMSISDN形式で登録します。