Zenn
KWCPLUSPublicationへの投稿
🔰

Vonage の開発スタートガイド

小原聖健
2024/03/06に公開
Vonage
tech

こんにちは。KDDI ウェブコミュニケーションズ（KWC）の小原です。

この記事では、KWC が再販する Vonage を使ってはじめて開発する際に役立つ情報をまとめました。

Vonage と KWC の違い

Vonage と直接契約する方法と、KWC を経由して契約する方法の 2 種類があります。

提供する機能はどちらも同じですが、KWC は別途下記サービスを提供します。

  • 日本語サポート
  • 日本円による請求
  • 請求書払い
  • メンテナンスや仕様変更などの重要な情報を翻訳して日本語で提供

KWC 経由での契約については、こちらをご参照ください。

なお管理コンソールの URL は、KWC 経由の契約と Vonage 直接契約とでそれぞれ異なります。

KWC 経由のログイン先は下記になります。

https://kwc.dashboard.vonage.com/

電話番号について

電話番号の取得

電話番号の取得はこちらをご参照ください。

SMS の送信には英数字を利用した Alphanumeric Sender ID を利用するため、電話番号の取得は不要です。

電話番号の形式

電話番号は E.164 もしくは MSISDN と呼ばれる形式で記述する必要があります。

国番号を先頭に置き、電話番号の先頭の 0 を外した形式になります。日本の国番号は 81 のため下記になります。

080-XXXX-YYYY
↓
8180XXXXYYYY

E.164 には頭に + を追加した +8180XXXXYYYY 形式もありますが、 Vonage では + は不要です。

参考資料

SDK

Vonage は REST API のため curl/HTTPie でも利用できますが、Python や Node.js、Java など主要言語の SDK も提供しています。

  • SDKs and Tools
    • Changelogs
    • Deprecation ... 正式リリース（GA）された API の廃止は、その一年前から告知し、定期的に警告メールを送信します。KWC は日本語で案内します

SDK は GitHub でも公開されています。Repositories 検索に「ruby sdk」のように言語名と sdk を入力することで見つけられます。

GitHub Search

ドキュメントとサンプルコード

開発ドキュメントの目次は下記になります。

https://developer.vonage.com/ja/documentation

Messages API や Voice API などの各ドキュメントは共通の構造を持ち、左メニューの「コードスニペット」や「チュートリアル」にサンプルコードがあります。

詳細なパラメータは「API リファレンス」から知ることができます。

BUILD YOUR SOLUTION

トライアルの制限

€2.00 のクレジットが提供されます。

SMS は 2FA で検証した 5 つの電話番号（この「テスト番号」はトライアル中にしか見えません）に送信できます。トライアル中は本文に自動で [FREE SMS DEMO, TEST MESSAGE] が追加されます。

トライアル中は電話番号を取得できないため、電話の発着信もできません。

トライアル用に提供されたクレジット残高は、アップグレード後に持ち越されません。

下記 FAQ には「電話発信が可能」という記述がありますが、実際は特別なクーポンが必要になります。KWC はハッカソンなどを開催しており、参加者にクーポンを提供することがあります。

参考資料

ネットワーク要件

Vonage へのアクセス

API の Endpoint である rest.nexmo.com や api.nexmo.com は CDN を利用しており、静的 IP アドレスを持ちません。

Firewall がある場合はドメインで許可してください。

参考資料

Vonage からのアクセス

Vonage からの通信は下記 IP アドレスの範囲を利用します。Firewall で受信可能に設定してください。

  • 216.147.0.0/18
  • 168.100.64.0/18
種別 ポート
HTTP Callbacks (Webhooks) TCP port 80, TCP port 443
WebSockets TCP port 443

SIP を利用する場合

SIP を利用する場合は下記範囲ですが、将来的に拡張される可能性があるため 216.147.0.0/18 の設定を推奨します。

  • 216.147.0.1
  • 216.147.0.2
  • 216.147.1.1
  • 216.147.1.2
  • 216.147.2.1
  • 216.147.2.2
  • 216.147.3.1
  • 216.147.3.2
  • 216.147.4.1
  • 216.147.4.2
  • 216.147.5.1
  • 216.147.5.2
種別 ポート
SIP UDP on port 5060
TCP on port 5060
TLS on port 5061
RTP/Media UDP ports 10000 -50000

参考資料

Webhook

Webhook は指定 URL へリアルタイムにステータスを送る仕組みです。

電話発信であれば発信開始、相手が応答、通話中、着信拒否、通話終了といった情報が送られます。SMS であれば着信、配達失敗などが分かります。

Webhook はログとして役立つため取得することを推奨します。

Webhook 先はユーザが用意する必要があります。AWS やレンタルサーバなど、Vonage がアクセスできるサーバであればどこでも構いません。

参考資料

失敗と再試行

Webhook 先は 3 秒以内に Vonage へ応答を返す必要があります。

HTTP セッションが確立した場合は 15 秒間応答を待ち、200 OK の応答がない場合は接続を切断して 60 秒後に再試行します。この再試行は仕様となり、オフできません。また回数や秒数の制限もできません。

参考資料

ログ

Voice や SMS のログを Web（KWC API Dashboard）上で確認できる期間は 30 日間です。それより前のログを取得するには有料の Reports API が必要になります。

ログが長期間必要な場合は Webhook を利用してユーザ側で保存してください。

参考資料

ログの秘匿化

Redact API をご利用いただくことで、ログ（CDR: Call Detail Records）に含まれる個人情報（PII）の電話番号や SMS 本文を、「REDACTED」の文字列に置き換えたり暗号化したりできます。

Redact には対象プロダクトや利用方法の異なる 3 種類のサービスがあります。

Redact API Auto-redact Standard Auto-redact Advanced
使用法 ログを個別指定 自動実行 自動実行
対象ログ CDR CDR CDR, サーバログ
対象プロダクト SMS, Number Insight, Messages API, Voice, Verify SMS, Number Insight, Messages API, Voice, Verify SMS, Number Insight
タイミング 即時不可。ログ生成後の数分後に指定可能 即時、もしくは 7, 15, 30, 60, 90 日後 即時
秘匿化 REDACTED REDACTED REDACTED、暗号化
価格 無料 有料 有料

Redact のご利用については KWC までお問い合わせください。

参考資料

音声ログで電話のログが見えない場合

音声ログのデフォルトは「Type：アプリ内通話（WebRTC）」になっています。そのため「電話（PSTN/SIP）」を選ばないと電話のログが見えません。

また「時間範囲」が「過去1時間」のため「過去12時間」や「今週 - UTC」を選択してください。

失敗した通話は「許否」タブにしか表示されないため、「許否」タブもご確認ください。

音声ログ

Voice Inspector

Voice Inspector は MOS といった音声品質や NCCO など音声ログより詳細を見ることができます。

左下の「デベロッパーツール」→「Voice Inspector」からアクセスできます。

Chrome であれば、オムニバー（アドレスバー）に Voice Inspector の URL の一部である too と入力すると、 URL が補完されるため素早くアクセスできます。なおオムニバーには、Chrome にフォーカスがあれば Ctrl-l で素早く移動できます。

https://tools.vonage.com/voice/inspector/

Chrome にフォーカスがあれば Ctrl-l でオムニバーに移動するので too と入力できます。

参考資料

環境の分離

以下のような環境を分けるために Subaccounts と Applications があります。

  • 開発環境と本番環境を分けたい
  • 外部会社と環境を分けたい
  • Vonage を利用したサービスを提供しておりエンドユーザ単位で請求を分けたい

Subaccounts

請求は API Key 単位になります。

Subaccounts は 500 個まで作成でき、それぞれに新しい API Key が発行されます。Subaccounts は新規サインアップした環境に似ています。Subaccounts 間の電話番号移動はお問い合わせベースになります。

Select Subaccounts

Subaccounts は現在 API からしか作成できず、削除できません。

Subaccounts の識別に設定できる name は、現段階では日本語だと文字化けするため、英数字で設定してください。

※KWC でアップグレードいただいたアカウントは申請不要で Subaccounts API をご利用いただけます。2024/04/25 以前に作成およびアップグレードされたアカウントで、Subaccounts API のご利用を希望される場合は KWC までお問い合わせください。

参考資料

Application

Applications は親 Accounts（マスター）と Subaccounts に複数作成できます。

Applications は API Key を使わず、発行された Application ID と鍵認証で API を利用します。

Applications は電話番号を紐づけることができます。開発環境と本番環境で Applications を分けることで誤って別 Applications から電話番号が利用されることを防ぎます。

Vonage を使って複数のツールやサービス、アプリを作成するのであれば Applications で分けることをおすすめします。

参考資料

セキュリティ

Vonage を安全に利用するために KWC API Dashboard のログインに 2FA を必ず設定してください。

オプションとして SAML を利用した SSO や、ダッシュボードにログインした IP アドレスを記録する Audit API があります。こちらについては KWC までお問い合わせください。

以下は Vonage と直接関係ない一般的な内容ですが、毎年被害が発生しているためご案内します。

  • Laravel はデプロイ時に必ず Debug mode (APP_DEBUG) を false にしてください。true の場合は第三者から変数が見えるため、API Secret などのクレデンシャルが奪われ、SMS の不正利用などに使われるケースが多発しています
  • コードにクレデンシャルを直接書かず、direnv などを利用して環境変数をご利用ください。コードが流出してもクレデンシャルが奪われません。攻撃者は公開リポジトリが commit されたタイミングで自動的にクレデンシャルのパターンに一致する文字列を探して悪用します
  • GitHub/GitLab をご利用になる場合はリポジトリが公開か非公開か再確認ください

参考資料

ホワイトペーパー

セキュリティのチェックシートにお役立てください。

障害とメンテナンス情報

Vonage 公式の障害情報は下記になります。

https://vonageapi.statuspage.io/

ページをスクロールするとメンテナンス情報や過去の障害情報も掲載されています。

ただ、そのほとんどが外国の SMS 情報になり、「日本の情報」や「ご利用のサービス」などで絞り込みができません。

KWC は当社のアカウントをご利用のお客様に影響のある重大な障害情報やメンテナンス情報を下記で公開します。また KWC 契約者には別途メールでご案内します。

https://kwcplus.kddi-web.com/

サービスの注意点

日本未提供サービス

  • 日本の電話番号の Number API。アメリカの電話番号などの外国の電話番号は利用可能
  • SMS API、Messages API の日本番号からの着信
    • 日本向けの From は Alphanumeric Sender ID になります。そのため電話番号は不要です
  • VBC (Vonage Business Communications) / Unified Communications
  • VCC (Vonage Contact Center)

申請が必要なサービス

KWC までお問い合わせください。

  • Audit API
  • Redact API
  • Social Commerce（旧Jumper.ai）
  • SSO
  • 電話番号の取得、移動
  • 国内直収 SMS、専用番号、双方向 SMS

その他の注意点

  • SMS の送信には SMS API ではなく Messages API を強く推奨します
    • Messages API は将来的に LINE や RCS の拡張が予想されます。SMS API と Messages API はコードの互換がないため、Messages API での開発をおすすめします
    • Messages API を利用するにはAPI 設定の「デフォルトのSMS設定」から「Messages API」を選択してください
  • Video は Vonage Video API Unified をご利用ください。Video API (TokBox Portal) は Voice や SMS をご利用できない別契約になります
  • Answering Machine Detection は英語に最適化されており、日本語は調整中

コミュニティ

KWCPLUS
KWCPLUSPublication

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

Discussion