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

概要

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

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

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

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

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

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

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

playback

指定されたMP3ファイルを再生

transfer

指定された電話番号へ転送する

say

指定されたテキストを読み上げる

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

空き電話番号を検索する

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

DIN検索API

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

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

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

DIN契約API

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

契約が成功したら

DIN契約確認API

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

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

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

caller

電話の発信者番号

recipient

着信したDINの電話番号

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

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

アクションURLを設定する

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

アクションURL設定API

電話番号を解約する

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

DIN解約API

各言語用ライブリラリ

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

• Python
• Ruby
• PHP

トラブルシュート

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

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