ダイアルインナンバーを使ってみよう


概要

ダイアルインナンバーとは?

ダイアルインナンバー(Dial in number、以降DINと書きます)は、 XOXZOのテレフォニーAPIで電話の着信を制御する機能です。ユーザーは、電話番号を契約し、 その電話に着信があった場合、転送やメッセージを再生するシステムを APIを使って構築することができます。

利用するまでの大まかな流れは以下のようになります。

  1. 空き電話番号を検索する
  2. その中から、希望の電話番号を選び契約する
  3. アクションサーバーを作る
  4. アクションサーバーのURLを設定する

アクションサーバーと電話着信時の動作

契約した電話番号に着信があったとき、XOXZOクラウドシステムはAPIで指定されたWebサーバ(以降、アクションサーバと呼びます)のアクションURLに対して、HTTPリクエストを発行します。 DINを使うユーザは、XOXZOクラウドからのHTTPリクエストに応答する、アクションサーバを設置しなければいけません。

着信時の動作の図

アクションは、着信した電話をどのように処理するかをXOXZOクラウドシステムに対して指示するもので、次の3つの種類があります。

playback
指定されたMP3ファイルを再生
transfer
指定された電話番号へ転送する
say
指定されたテキストを読み上げる

それでは、以下順を追って、DINシステムをどのように構築していくか、解説します。

空き電話番号を検索する

DINで利用可能な電話番号はXOXZOクラウドシステムがプールしていて、ユーザーはこの中から自分の好きな電話番号を 選ぶことができます。利用可能な電話番号の一覧を得るには次のAPIを使います。

DIN検索API

このAPIでは、電話番号に1対1で対応するdin_uid(DINに対応する、ユニークな識別子)が返されます。 以下に列挙するAPIでは、この din_uid が重要なパラメータとして使われますので、しっかり覚えておきましょう。

着信用電話番号を契約する

使いたい電話番号が決まったら、その番号を契約します。 契約にするには

DIN契約API

を使います。URLには検索APIで取得した din_uid を指定しましょう。

契約が成功したら

DIN契約確認API

を使って、正しく契約されているかを確認しましょう。

アクションサーバーをつくる

電話着信時にアクションサーバへ発行されるHTTPリクエストのメソッドはGETで2つのパラメータが付いています。 これらのパラメータを使えば、誰から電話がかかってきたか? 何番へ電話がかかってきたか? がわかります。 これらの情報をつかうことによって、より細かいアクションの制御が可能となります。

caller
電話の発信者番号
recipient
着信したDINの電話番号

応答のアクションは1行のプレーンテキストで返します。 アクションの詳細についてはこちらを参照してください

こちらには Djangoフレームワークを使って作成した アクションサーバーのサンプルが置いてありあます。

アクションURLを設定する

アクションサーバーの設置が完了したならば、そのサーバーをXOXZOクラウドシステムが呼び出せるように、 アクションサーバーのURLをXOXZOクラウドに教えてあげる必要があります。 このURLの設定には以下のAPIを使います。

アクションURL設定API

電話番号を解約する

DINの解約をするには次のAPIを使います。

DIN解約API

各言語用ライブリラリ

XOXZO APIを利用するために便利な Python, Ruby, PHP ライブラリが用意されています。これらはMITライセンスのオープンソースで、ユーザーは自由に利用することができます。

トラブルシュート

DINがうまく動かないときは次の点をチェックしてみましょう

  • アクションURLは設定されているか?
  • アクションURLは正しく、アクションサーバを指しているか?
  • アクションサーバーは、アクセス可能な状態か?
  • 再生するサウンドのmp3ファイルは、アクセス可能な状態か?
  • アクションの応答テキストに間違いはないか? コマンドのスペル、引数の数、引数の内容は正しいか?
  • クレジットは十分にあるか?