Wipple CPaaS 開発者ガイド

Wipple CPaaS は、Miraicom Inc. が提供するプログラマブル音声プラットフォームです。シンプルな JSON 命令を使ってお客様自身の Web アプリケーションから電話の通話を制御し、REST API を通じてバックエンドから通話を管理できます。

このドキュメントは、Wipple CPaaS 上で音声アプリケーションを構築する開発者向けに書かれています。次の 3 つの領域を扱います。

セクション	内容
Functions	通話に対してプラットフォームが何をすべきかを指示する JSON 命令 (「Function」) です。音声の再生、ダイヤル入力や音声の収集、別の相手への発信、AI 音声エージェントの実行などを行います。
REST API	発信通話の作成、進行中の通話の更新や終了、会議やキューの参照を行うための HTTP エンドポイントです。
Webhook	通話の着信時、SIP クライアントの登録時、AI エージェントがクライアントツールを呼び出した時に、Wipple CPaaS からお客様のアプリケーションへ送信される HTTP リクエストです。

Wipple CPaaS の仕組み

アカウント上の電話番号 (または SIP ユーザー) を アプリケーション に割り当てます。
通話が着信すると、Wipple CPaaS はそのアプリケーションに設定された URL へ Webhook を送信します (または WebSocket 接続を開きます)。
お客様のアプリケーションは Function の JSON 配列で応答します。Wipple CPaaS はそれらを順番に実行します。
多くの Function は、その結果を アクションフック を通じてお客様のアプリケーションに報告します。そのフックへの応答にさらに Function を含めることができるため、必要なだけ対話を継続できます。
お客様自身のシステムから発信するには、通話の作成 REST エンドポイントを呼び出します。着信側が応答した後の流れは、着信通話とまったく同じです。

すべての JSON ペイロードは、HTTP 経由で配信される場合も WebSocket 経由で配信される場合も同じ構造を持ちます。HTTP リクエストを処理できる言語やフレームワークであれば、どれを使ってもアプリケーションを構築できます。

主要な概念

アカウント プラットフォーム上のお客様のテナントです。すべての REST リクエストはアカウント識別子 (AccountSid) によってスコープされ、すべての Webhook には通話が属するアカウントの account_sid が含まれます。

API キー REST API リクエストの認証に使用するベアラートークンです。アカウント上の通話を完全に制御できるため、秘密に保管してください。

アプリケーション 通話とお客様のコードを結び付ける名前付きの設定です。コールフック URL (新規通話が通知される先)、コールステータスフック URL (通話ステータスの変化が報告される先)、およびデフォルトの音声設定 (音声合成・音声認識のベンダー、言語、音声) を保持します。

電話番号 アカウントにプロビジョニングされ、アプリケーションにルーティングされる電話番号です。このドキュメントのサンプル番号は架空の範囲 +81 50 9999 XXXX を使用しており、実在する番号ではありません。

キャリア Wipple CPaaS を公衆電話網または他の SIP プラットフォームに接続する SIP トランクです。電話番号への発信通話は、お客様のキャリアのいずれかを経由して送信されます。

SIP ユーザー アカウントの SIP レルムに直接登録する SIP または WebRTC クライアントです。登録済みユーザーには、dial Function の user ターゲットタイプを使って発信できます。

Call SID すべての通話レグに割り当てられる一意の識別子です。すべての Webhook に含まれており、REST API で通話を更新または終了する際のキーとして使用します。

Function お客様のアプリケーションが返す JSON 配列内の 1 つの命令です。互換性のため、Function 名を指定するプロパティは JSON ペイロード内では verb と呼ばれます (例: {"verb": "say", "text": "Hello"})。

アプリケーションの最初の例

次の応答は、通話に応答し、発信者に挨拶し、1 桁の数字を収集して、その結果をお客様のサーバーの /menu に POST します。

[
  {
    "verb": "gather",
    "actionHook": "/menu",
    "input": ["digits"],
    "numDigits": 1,
    "say": {
      "text": "Thank you for calling Miraicom. For sales press 1. For support press 2."
    }
  }
]

発信者がキーを押すと、Wipple CPaaS は収集した数字を含む POST リクエストを /menu に送信します。それに対する応答では、たとえば営業担当者に dial で発信できます。

[
  {
    "verb": "dial",
    "callerId": "+815099990001",
    "target": [
      { "type": "phone", "number": "+815099990002" }
    ]
  }
]

このドキュメントの表記規則

{API_ENDPOINT} は、お客様に割り当てられた Wipple CPaaS API エンドポイントのホスト名を表します。サービス情報で提供された値に置き換えてください。
{yourserver} は、お客様自身のアプリケーションの公開ホスト名を表します。
+815099990001 のような電話番号や「Miraicom Taro」のような名前は架空のサンプルです。
一部の例では、生の JSON ではなく、メソッドチェーン形式の JavaScript スタイル (session.say({...}).send()) で Function を示しています。どちらの記法も同じ JSON ペイロードを生成します。JavaScript スタイルは、Node.js クライアントライブラリでの表現方法にすぎません。

次に読むページ

はじめにでは、最初の通話の受信と最初の発信通話の実行を順を追って説明します。
Functions 概要では、JSON メッセージの構造と、Function のネストや順序付けの方法を説明します。
REST API についてでは、認証とレスポンスの規則を説明します。