Function 概要

Wipple CPaaS で通話を制御するために使用するすべての Function のリファレンスです。dial や gather から transcribe、listen まで、構文、パラメータ、使用例を確認できます。

Function は Wipple CPaaS アプリケーションの基本的な構成要素であり、プラットフォームに通話の処理方法を指示します。

注意

JSON ペイロードでは、各 Function は verb という名前のプロパティ(例: "verb": "say")で識別されます。このプロパティ名は API 互換性のために維持されています。本ドキュメント全体を通して、この命令自体は Function と呼びます。

Function の各ページにある一部の例は、session.say({ text: "hello" }).send() のようなメソッドチェーン形式の JavaScript で記述されています。これは Node.js クライアントライブラリの記法であり、ここに示す生の JSON 形式とまったく同じ JSON を生成します。

連携の仕組み

Wipple CPaaS は、Webhook または WebSocket 接続のいずれかで交換される JSON ペイロードを使用して通話を制御します。
アカウント宛ての着信通話を受信すると、Wipple CPaaS は実行したいアプリケーションに設定されている URL を取得します。
URL が 'http(s)://' で始まる場合、Wipple CPaaS はその URL に HTTP リクエストを送信し、URL が 'ws(s)://' で始まる場合は、その URL への WebSocket 接続を確立します。次に Wipple CPaaS は着信通話を説明する最初のメッセージを送信し、Web アプリケーションは通話の処理方法を示す JSON ペイロードを返す責任を負います。

いずれの場合(HTTP または WebSocket)でも、JSON ペイロードの詳細は同じです。

アカウント宛ての着信通話を受信すると、Wipple CPaaS は設定した URL に HTTP リクエストを送信し、Web アプリケーションは通話の処理方法を示す JSON ボディを含むレスポンスを返します。

発信通話を生成したい場合も同様に動作します。REST API を使用して HTTP リクエストを送信し、その中で通話が応答された時点で呼び出される URL またはアプリケーション識別子を指定します。この場合も、その HTTP リクエストに対するレスポンスには、通話の処理方法を示す JSON ボディが含まれます。

基本的な JSON メッセージ構造

HTTP リクエストへのレスポンスとして提供する JSON ペイロードは配列でなければならず、各要素はプラットフォームが実行するタスクを記述します。これらのタスクは配列に現れる順に逐次実行されます。各タスクは verb プロパティ内の Function 名(例: "dial"、"gather"、"hangup" など)で識別され、アクションの実行方法を設定するための関連する詳細が付随します。

通話のアプリケーション実行中に発信者が切断した場合、現在のタスクは完了まで実行され、アプリケーション内の残りのタスクは無視されます。

[
  {
    "verb": "say",
    "text": "Hi there!  Please leave a message at the tone.",
    "synthesizer": {
      "vendor": "Google",
      "language": "en-US",
      "gender": "FEMALE"
    }
  },
  {
    /* ..next Function */
  }
]

一部の Function では、他の Function をネストできます。たとえば "gather" では、プロンプトを再生して応答を収集するという処理を 1 つのコマンドで行うために、"say" コマンドをネストできます。

{
  "verb": "gather",
  "actionHook": "/gatherCardNumber",
  "input": ["speech", "dtmf"],
  "timeout": 16,
  "numDigits": 6,
  "recognizer": {
    "vendor": "Google",
    "language": "en-US"
  },
  "say": {
    "text": "Please say or enter your six digit card number now",
    "synthesizer": {
      "vendor": "Google",
      "language": "en-US",
      "gender": "FEMALE"
    }
  }
}

これらをまとめると、シンプルなボイスメールアプリケーションは次のようになります。

[
  {
    "verb": "say",
    "text": "Hi there!  Please leave a message at the tone and we will get back to you shortly."
  },
  {
    "verb": "listen",
    "actionHook": "http://example.com/voicemail",
    "url": "wss://example.com/my-recorder",
    "finishOnKey": "#",
    "metadata": {
      "topic": "voicemail"
    },
    "playBeep": true,
    "timeout": 20
  },
  {
    "verb": "say",
    "text": "Thanks for your message.  We'll get back to you"
  }
]