音声API

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

警告

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

音声プレーバックAPI

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

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

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

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

注釈

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のサンプルは以下のとおり

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(協定世界時)にて表示されます。
発信者 発信元番号
recipient 着信番号

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

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

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