ダイアルイン番号API

ダイアルイン番号APIを使うと、簡単なAPIで電話の着信とそれに対応する処理を設定することができます。チュートリアルは ここで読むことができます。

APIによるダイアルイン番号の見つけ方

このAPIを使うと、ダイアルイン番号(DIN)一覧の表示と契約をおこなうことができます。

空いているDINの一覧を得るには、以下の GET リクエストを発行します

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/dins/

応答はHTTPステータス 200 OK でJSON形式で返されます。

HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Connection: keep-alive
Content-Type: application/json

[
    {
        "country_code": "81",
        "din": "815012345678",
        "din_uid": "JPafr34rafic76tf",
        "minute_cost": 1,
        "monthly_cost": 650.0,
        "prefix": "50"
    },
    {
        "country_code": "81",
        "din": "81312345678",
        "din_uid": "JPascfdrwersdf12",
        "minute_cost": 10,
        "monthly_cost": 1900.0,
        "prefix": "3"
    }
]

応答データ

名称 説明
country_code DINの国コード。
din E.164形式のDIN。国コードを含む。
din_uid DINに対応する、ユニークな識別子。
minute_cost DINに着信したときの、一分間あたりの料金。
monthly_cost DINを契約したときの、一ヶ月あたりの料金。
prefix DINのプリフィックス。先頭の0を除いたもの。

国コードあるいはプリフィックスでフィルタリングすることもできます。

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/dins/?country=JP

または:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/dins/?prefix=813

国コードあるいはプリフィックスでフィルタリングをした場合、条件に一致したDINのみが表示されます。

APIによるダイアルイン番号の契約

ダイアルイン番号を契約するには、以下のような POST リクエストを発行します。

curl -u <SID>:<AUTH_TOKEN> -d'din_uid=<din_uid>' https://api.xoxzo.com/voice/dins/subscriptions/

<DIN_UID> は、以前の GET リクエストで返された値の中から、契約したい電話番号のUID識別子の値を指定します。

契約が成立すると、HTTPステータス 201 OK が返されます。

警告

  • POST リクエストが成功すると、直ちに月額使用料がクレジットから引き落とされます。

APIによるダイアルイン番号へのアクションの関連付け

それぞれのダイアルイン番号に対しては、電話を着信した時にどのような処理をおこなうかが結びつけられます。

curl -u <SID>:<AUTH_TOKEN> -d'action_url=<url>' https://api.xoxzo.com/voice/dins/subscriptions/<din_uid>/

契約しているダイアルイン番号に電話があったばあいには、 url で指定した action_url に対して GET リクエストが発行され、処理が行われます。

ちなみに

今すぐローカルの番号を取得して動作確認をしてみましょう! 無料登録 は無料ですぐできます。

APIによる契約中のダイアルイン番号の一覧取得

契約中のダイアルイン番号の一覧を得るには、下記のように GET リクエストを発行します。

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/dins/subscriptions/

APIによるダイアルイン番号の契約解除

契約解除のやりかた:

curl -XDELETE -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/dins/subscriptions/<din_uid>/

アクションとは何か?

アクションとは契約しているダイアルイン番号に電話が着信した時に行う動作のことです。アクションには、着信した通話の転送、音声ファイルの再生や読み上げ機能などがあります。

「使用可能なアクション」 には、使用可能なアクションの一覧があります。

指定したいアクションは、URLでアクセス可能な簡単なテキストファイルで定義します。このURLは action_url で契約したDINに設定します。

DINに対して着信があると、 action_url に対して GET リクエストが発行されます。このとき、以下の情報も付与されます。

GET /command/?caller=+8180123456789&recipient=+8150123456789

caller は電話をかけてきた人の電話番号です。recipient はあなたのDINです。

使用可能なアクション

使用可能はアクションは以下のとおりです。

アクション 説明
playback 着信に対してmp3ファイルを再生する。
transfer 着信した通話を、他の番号に転送する。
say テキストを音声で読み上げる(Text-to-Speech)。

あなたが指定した action_url は、つぎのようなプレーンテキスト形式で出力しなければいけません:

playback http://example.com/media.mp3

playback は再生したい mp3 のURLを指定します。

注釈

transfer は転送先の電話番号を含まなけれはいけません。

transfer +81807181881 --caller=+8190123456789

caller はオプションのパラメータで、転送相手に通知される発信者番号です。

警告

  • 発信者番号の caller は、相手へできるかぎりそのまま通知されるように処理されますが、保証されているわけではなく、別の値に置き換えられる可能性があります。これは、通信キャリア、経由するネットワークや政府の方針依存しており、必ずしも指定したとおりになるわけではありません。

テキストを読み上げるには say を使います:

say en "Hello, how are you?"

2つのパラメータを指定することが必要です。一つ目は言語の指定。詳しくは tts_lang を参照してください。

二つ目はテキストメッセージです。テキストは引用符 " で囲ってください。詳しくは tts_message を参照してください。