音声API

通話用APIを利用すると、簡潔なHTTPエンドポイントに電話でつなげることができます。

警告

  • 音声APIを利用するための料金にかかわらず、アカウントにあるクレジットが最低残高でないといけない場合があります。詳細については ヘルプ・センター をご確認ください。

音声プレーバックAPI

電話を発信し、相手が電話を取った時にオーディオファイルを再生するには、エンドポイントに POST リクエストを行ってください。

https://api.xoxzo.com/voice/simple/playback/

下記のパラメーターを併記してください。

名称 詳細 必須 データタイプ
caller 発信者番号 数字 +8190123456789
recipient 通話の受信者 E.164 +8190123456789
recording_url mp3 オーディオファイルの場所を示すURL URL http://www.mysite.com/123.mp3
callbackurl コールバックURL × URL http://example.com

注釈

recipient パラメーターに関する注意点

  • 特定の電話番号を指定する場合、Xoxzo は E.164 を番号のフォーマットに指定しています。
  • E.164 フォーマットは、電話番号の先頭に + プレフィックスをつけた後ロカールの 0 除く携帯の電話番号がくるという順番を定められています。
  • 有効な受信者記載例として、 +818011234567 と挙げられます。 81 は日本の国番号で、 8011234567 は携帯電話番号となります。

注釈

caller パラメーターに関する注意点

  • 特定の電話番号を指定する場合、Xoxzo は E.164 を番号のフォーマットに指定しています。
  • E.164 フォーマットは、電話番号の先頭に + プレフィックスをつけた後ロカールの 0 除く携帯の電話番号がくるという順番を定められています。

警告

  • caller は、最良の方法で発信されますが、それでも、受信者側にそのまま表示される保証はありません。任意の caller に置き換えられることもあります。これは、各キャリアや、ネットワークまたは政府が定めた規定によるもので、リクエストを受け取らない場合もあるからです。

注釈

recording_url パラメーターに関する注意点

  • URLで指定するmp3ファイルは、だれでもアクセス可能であることが 必要不可欠です。
  • 音声ファイルのURLには、ASCII 文字と数字以外、アンダースコアとスラッシュ(記号) のみ としてください。

注釈

recording_url パラメーターに使えるURLのサンプルは以下のとおり

注釈

callbackurl パラメーターに関する注意点

  • このパラメータ(省略可能)が指定された場合は、通話が終了したときに、XOXZOクラウドシステムが指定されたURLを呼び出します。
  • XOXZOクラウドシステムはこのURLを呼び出すとき、httpのPOSTメソッドを使います。コールバックのパラメーターは「プレーバック発信ステータス確認」とほぼ同じです。 プレーバック発信ステータス確認 を参照して下さい。
  • コールバックURLは http のステータス 200 で応答する必要があります。この応答をうけとるまで、最大10回まで呼び出しを繰り返します。

JP向けのオプション・パラメーター

下記の追加パラメーターは日本国内での利用・受信専用です。

名称 詳細 必須 データタイプ
jp_din_caller ローカル発信者番号 × true の文字列 true

詳細は ローカル発信者番号 にてご確認ください。

注釈

jp_din_caller パラメーターに関する注意点

cURLを使ったリクエストの例は下記のとおりです。

curl -u <SID>:<AUTH_TOKEN> \
  --data-urlencode 'caller=<caller>' \
  --data-urlencode 'recipient=<recipient>' \
  --data-urlencode 'recording_url=<recording_url>' \
  https://api.xoxzo.com/voice/simple/playback/

レスポンス

レスポンスは、JSON構造となり、ステータスコード HTTP 201 CREATED にて返されます。

HTTP/1.0 201 CREATED
Content-Type: application/json

[
    {
        "callid": "<callid>"
    }
]

間違ったバラメーターが与えられた場合には、ステータスコード HTTP 400 BAD REQUEST が返されます。例えば、もし recording_url パラメーターがなかった場合、HTTPからの返答はこのようになります。

HTTP/1.0 400 BAD REQUEST
Content-Type: application/json

{
    "caller": [
        "This field is required."
    ]
}

レスポンスデータ

名称 詳細
callid この通話固有のIDです。

ちなみに

実際にテストコードでAPIを叩いたほうが早く動作確認できます。 無料登録 は無料ですぐできます。

音声プレーバックAPIでテキスト読み上げ機能を使う

追加機能:追加料金で、あらかじめ用意した音声ファイルのかわりに、テキスト読み上げ機能を音声プレーバックAPIで使うことが可能です。この機能を使うには テキスト読み上げ機能 を参照してください。

プレーバック発信ステータス確認

通話状態を調べるには、エンドポイントに <callid> をつけた、GETリクエストを行ってください。curlを用いた例は次のようになります。

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/simple/playback/<callid>/

発信を行うたびに、 <callid> を含むレスポンスが得られますので、この <callid> を通話状態の確認にご利用ください。

レスポンスは、JSON構造となり、ステータスコード HTTP 200 OK にて返されます。

HTTP/1.0 200 OK
Content-Type: application/json

{
    "callid": "<callid>",
    "cost": 10,
    "duration": 11,
    "start_time": "2015-09-08 12:50:05",
    "end_time": "2015-09-08 12:50:16",
    "status": "ANSWERED",
    "caller": "<caller>",
    "recipient": "<recipient>",
    "url": "https://api.xoxzo.com/voice/simple/playback/<callid>/"
}

レスポンスデータ

名称 詳細
callid この通話固有のIDです。
cost この通話にかかった料金をクレジット数で表示しています。
duration この通話の時間を表示します。
start_time 通話が開始された時間が、UTC(協定世界時)にて表示されます。
end_time 通話が終了した時間が、UTC(協定世界時)にて表示されます。
caller 発信元番号
recipient 着信番号

よくある通話のステータス

status データ内にある、ステータスのリストです。

通話状態 詳細
ANSWERED 通話は受信者が応答したか、留守番電話へとつながりました。
FAILED この発信は、受信者へつながりませんでした。
通話中 現在通話中
NO ANSWER 受信者はこの発信に応答しませんでした。

電話会議API

電話会議APIを使うと、各参加者に電話をかけ、応答があると自動的に電話会議に参加させることができます。同時に複数の参加者のあいだで通話することが可能です。

電話会議を開始するにには次のAPIを使います。POST リクエストをこのエンドポイントに行ってください。

https://api.xoxzo.com/voice/simple/conferences/

下記のパラメーターを併記してください。

名称 詳細 必須 データタイプ
caller 発信者番号 数字 +8190123456789
participants 電話会議参加者 E.164 +8190123456789
lang ガイドの言語 × ISO 639-1 en

注釈

participants パラメーターに関する注意点

  • 特定の電話番号を指定する場合、Xoxzo は E.164 を番号のフォーマットに指定しています。
  • 参加者の数は最低2名、最高3名です。参加者はコンマ(,)で区切ります。
  • E.164 フォーマットは、電話番号の先頭に + プレフィックスをつけた後ロカールの 0 除く携帯の電話番号がくるという順番を定められています。
  • 有効な参加者の例は +818011234567 です。 81 は日本の国番号で、 8011234567 は携帯電話番号となります。

注釈

lang パラメーターに関する注意点

  • このパラメータは電話会議開始時のガイドの言語を指定します。
  • ISO 639-1 形式の2文字の言語コード https://en.wikipedia.org/wiki/ISO_639-1
  • このパラメータは省略可能です。デフォルトは ja です。
  • 現在使えるのは enja です。

注釈

caller パラメーターに関する注意点

レスポンス

レスポンスは、JSON構造となり、ステータスコード HTTP 201 CREATED にて返されます。

HTTP/1.0 201 CREATED
Content-Type: application/json

{
   "conferenceid": "<conferenceid>",
   "participants": [
       {
           "callid": "<callid1>",
           "participant": "<participant1>"
       },
       {
           "callid": "<callid2>",
           "participant": "<participant2>"
       }
   ]
}

レスポンスデータ

名称 詳細
conferenceid この電話会議固有のIDです。
participants 各参加者に関する情報のリストです。
callid この参加者の通話固有のID
participant この参加者の着信番号

電話会議ステータス確認

通話状態を調べるには、エンドポイントに <callid> をつけた、GETリクエストを行ってください。curlを用いた例は次のようになります。

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/simple/conferences/<conferenceid>/

電話会議を行うたびに、 <conferenceid> を含むレスポンスが得られますので、この <conferenceid> を電話会議状態の確認にご利用ください。

レスポンスは、JSON構造となり、ステータスコード HTTP 200 OK にて返されます。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "cost": 65,
    "participants": [
        {
            "status": "ANSWERED",
            "recipient": "<recipent1>",
            "cost": 50,
            "caller": "<caller>",
            "callid": "<callid1>",
            "start_time": "2017-10-31 01:17:50",
            "url": "https://api.xoxzo.com/voice/calls/<callid1>/",
            "end_time": "2017-10-31 01:18:00",
            "duration": 1
        },
        {
            "status": "ANSWERED",
            "recipient": "<recipent2>",
            "cost": 15,
            "caller": "<caller>",
            "callid": "<callid2>",
            "start_time": "2017-10-31 01:17:50",
            "url": "https://api.xoxzo.com/voice/calls/<callid2>/",
            "end_time": "2017-10-31 01:18:09",
            "duration": 2
        }
    ],
    "conferenceid": "<conferenceid>",
    "start_time": "2017-10-31 01:17:50",
    "end_time": "2017-10-31 01:18:09",
    "duration": 2
}

詳細は レスポンスデータ を参照してください。