🔰

Vonage NCCOについて

2024/07/24に公開

はじめに

こんにちは。KDDI ウェブコミュニケーションズの西嵜(にしざき)です。

この記事では、Vonage での通話制御を実現するための仕組みである、NCCO についてご紹介いたします。

本記事の対象となる読者

  • Vonage に興味のある方
  • Vonage の NCCO について学びたい方

NCCO とは

NCCO (Nexmo Call Control Object) とは、Vonage において「テキストから自動的に音声を生成して読み上げる」「通話を転送する」といった、通話制御を実現するための仕組みです。

NCCO は JSON (JavaScript Object Notation) で表記することが可能で、多くのプログラミング言語で手軽に扱えます。

NCCO の例

以下の例をご覧ください。これが一つの NCCO です。

[
  {
    "action": "talk",
    "text": "こんにちは。通話を接続します。",
    "language": "ja-JP"
  },
  {
    "action": "connect",
    "endpoint": [
      {
        "type": "phone",
        "number": "8190XXXXXXXX"
      }
    ]
  }
]

一つの NCCO は、JSON の配列として表現され、その一つひとつの要素は、JSON のオブジェクトとなっています。これらのオブジェクトは action と呼ばれ、一つの action は、NCCO における一つの通話制御を表現しています。

NCCO action の種類

NCCO action には、以下の7種類があります。

Record

record action は、その名のとおり、通話内容を録音し、Vonage 側で保存するための action です。

[
  {
    "action": "record"
  }
]

Conversation

conversation action は、複数人数(最大 50 名)が参加可能な通話に接続します。通常の電話(発信側と着信側の 2 名が参加する)の制約を越えて、多人数での電話会議に利用することが可能です。

以下の例では、通話の相手方を sample-comversation という名前の電話会議に入室させます。

[
  {
    "action": "conversation",
    "name": "sample-comversation"
  }
]

Connect

connect action は、現在の通話を、別のエンドポイント(通常の電話や、Vonage での通話が可能なアプリケーション等)に対して接続します。これにより、いわゆる通話転送を実現できます。

以下の例では、通話を電話番号 090XXXXXXXX に転送します。電話番号は、MSISDN 形式(先頭の 0 を削除し、国番号を付加する。日本の電話番号の場合は 81)で指定します。

[
  {
    "action": "connect",
    "endpoint": [
      {
        "type": "phone",
        "number": "8190XXXXXXXX"
      }
    ]
  }
]

Talk

talk action は、Vonage が自動生成した音声を再生します。もちろん日本語の文言も再生可能です。

以下の例では、「こんにちは。こちらは日本です。」という日本語の文言を自動生成し、通話の相手方に対して再生します。

[
  {
    "action": "talk",
    "text": "こんにちは。こちらは日本です。",
    "language": "ja-JP"
  }
]

Stream

stream action は、あらかじめ準備された音声ファイル(MP3 もしくは WAV)を流します。

以下の例では、指定された URL の MP3 ファイルの内容を、通話の相手方に対して再生します。

[
  {
    "action": "stream",
    "streamUrl": [
      "https://www.example.com/stream.mp3"
    ]
  }
]

Input

input action を利用すると、通話の相手方から、DTMF (Dual-Tone Multi-Frequency/プッシュ回線における、数字キーによるプッシュ信号の入力)や、音声による入力を受け付け、取得することができます。

以下の例では、通話の相手方から DTMF を取得します。

[
  {
    "action": "input",
    "type": ["dtmf"]
  }
]

Notify

notify action は、任意のウェブアプリケーションに対して HTTP リクエストを実行します。これによりさまざまなリアルタイムでの通知を実現できます。そのほか、このウェブアプリケーションがNCCOをレスポンスとして返す場合は、そのNCCOが引き続き実行されます。これを利用することで、通話の制御を途中から変更できるようになります。

以下の例では、指定された URL に対して HTTP リクエストを実行します。その際、payload プロパティの内容をリクエストのボディとします。

[
  {
    "action": "notify",
    "payload": {
      "name": "alice"
    },
    "eventUrl": [
      "https://www.example.com/vonage-webhooks/event"
    ]
  }
]

NCCO のドキュメント

NCCO のドキュメントについては、以下をご参照ください(英語となります)。

https://developer.vonage.com/en/voice/voice-api/ncco-reference

まとめ

  • NCCO は、Vonage での通話制御を定義する仕組みです。
  • NCCO の実体は JSON で、多くのプログラミング言語で手軽に扱えます。

参考記事

KWCPLUS

Discussion