音声API¶
通話用APIを利用すると、簡潔なHTTPエンドポイントに電話でつなげることができます。
警告
音声APIを利用するための料金にかかわらず、アカウントにあるクレジットが最低残高でないといけない場合があります。詳細については ヘルプ・センター をご確認ください。
ちなみに
このAPIがウェブではどう動くのか、hello.xoxzo.com で見てみよう
音声プレーバックAPI¶
電話を発信し、相手が電話を取った時にオーディオファイルを再生するには、エンドポイントに POST リクエストを行ってください。
https://api.xoxzo.com/voice/simple/playbacks/
下記のパラメーターを併記してください。
名称
詳細
必須
データタイプ
例
caller
発信者番号
○
数字
+8190123456789
recipient
通話の受信者
○
E.164
+8190123456789
recording_url
mp3 オーディオファイルの場所を示すURL
○
URL
callbackurl
コールバックURL
×
URL
tags
タグ
×
UTF-8
tag1,tag2
注釈
recipient パラメーターに関する注意点
注釈
caller パラメーターに関する注意点
警告
caller は、最良の方法で発信されますが、それでも、受信者側にそのまま表示される保証はありません。任意の caller に置き換えられることもあります。これは、各キャリアや、ネットワークまたは政府が定めた規定によるもので、リクエストを受け取らない場合もあるからです。
注釈
recording_url パラメーターに関する注意点
URLで指定するmp3ファイルは、だれでもアクセス可能であることが 必要不可欠です。
音声ファイルのURLには、ASCII 文字と数字以外、アンダースコアとスラッシュ（記号） のみ としてください。
現在 https はサポートされていません。
注釈
callbackurl パラメーターに関する注意点
このパラメータ（省略可能）が指定された場合は、通話が終了したときに、XOXZOクラウドシステムが指定されたURLを呼び出します。
XOXZOクラウドシステムはこのURLを呼び出すとき、httpのPOSTメソッドを使います。コールバックのパラメーターは「プレーバック発信ステータス確認」とほぼ同じです。 プレーバック発信ステータス確認 を参照して下さい。
コールバックURLは http のステータス 200 で応答する必要があります。この応答をうけとるまで、最大１０回まで呼び出しを繰り返します。
注釈
tags パラメーターに関する注意点
このパラメータ（省略可能）が指定された場合は、各API呼び出しにタグをつけることができます。このタグは、後から発信ステータスを確認するAPIをつかって読み出すことができます。
タグは、コンマで区切ることで複数付けられます。タグの前後の空白は取り除かれます。
例¶
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/playbacks/
レスポンス¶
レスポンスは、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."
]
}
音声プレーバックAPIでテキスト読み上げ機能を使う¶
追加機能：追加料金で、あらかじめ用意した音声ファイルのかわりに、テキスト読み上げ機能を音声プレーバックAPIで使うことが可能です。この機能を使うには テキスト読み上げ機能 を参照してください。
プレーバック発信ステータス確認¶
通話状態を調べるには、エンドポイントに <callid> をつけた、GETリクエストを行ってください。curlを用いた例は次のようになります。
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/voice/calls/<callid>/
発信を行うたびに、 <callid> を含むレスポンスが得られますので、この <callid> を通話状態の確認にご利用ください。
レスポンスは、JSON構造となり、ステータスコード HTTP 200 OK にて返されます。
HTTP/1.0 200 OK
Content-Type: application/json
{
"callid": "<callid>",
"recipient": "<recipient>",
"url": "https://api.xoxzo.com/voice/calls/<callid>/",
"tags": [
"tag2",
"tag3"
],
"end_time": "2019-03-05 01:38:50",
"direction": "outbound",
"cost": 1,
"status": "NO ANSWER",
"duration": 0,
"call_type": "simple/playbacks",
"start_time": "2019-03-05 01:38:10",
"caller": "<caller>"
}
レスポンスデータ¶
名称
詳細
callid
この通話固有のIDです。
cost
この通話にかかった料金をクレジット数で表示しています。
duration
この通話の時間を表示します。
start_time
通話が開始された時間が、UTC（協定世界時）にて表示されます。
end_time
通話が終了した時間が、UTC（協定世界時）にて表示されます。
caller
この通話の発信元番号を表示します。
recipient
この通話の着信番号を表示します。
status
この通話の状態を表示します。
url
この通話状態のURLを表示します。
tags
この通話に付けられたタグです。タグが無いときは空のリスト[]になります。
direction
この通話の向きを表示します。
call_type
この通話のタイプを表示します。
よくある通話のステータス¶
status データ内にある、ステータスのリストです。
通話状態
詳細
ANSWERED
通話は受信者が応答したか、留守番電話へとつながりました。
FAILED
この発信は、受信者へつながりませんでした。
IN PROGRESS
現在通話中
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 パラメーターに関する注意点
注釈
lang パラメーターに関する注意点
このパラメータは電話会議開始時のガイドの言語を指定します。
ISO 639-1 形式の２文字の言語コード https://en.wikipedia.org/wiki/ISO_639-1
このパラメータは省略可能です。デフォルトは ja です。
現在使えるのは en と ja です。
レスポンス¶
レスポンスは、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
この参加者の着信番号
電話会議ステータス確認¶
電話会議のステータスを調べるには、エンドポイントに <conferenceid> をつけた、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
}
詳細は レスポンスデータ を参照してください。