❎ 🤷🏼 🤵🏽 無料のPBXおよびテレフォニー用のAPIインターフェイス 🦄 🌁 🌍

数週間前、Zadarmaプロジェクトは独自のAPIを公開しました。 IPテレフォニーの基本機能と無料のクラウドPBXを統合できます。

誰でも数分で無料のクラウドベースのPBXを作成し、APIをそれに接続し、それを介してPBXをアプリケーションと統合できます。

この記事では、メソッドのリストと説明、クラスへのリンク、および作業用にすでに存在するサンプル（公開されたPHPクラス）を公開しています。 APIのさらなる開発、CRMおよびその他のシステムとの統合のために、お客様のフィードバックに非常に興味を持っています。

APIで利用可能な主な機能：

SIPアカウントの設定を表示および変更します（番号転送の設定/変更、SIMカードにバインドする機能を含む）。
バランス表示、さまざまな詳細（SIPと無料PBXの両方）を使用した統計サンプリング。
発信呼び出し（外部および内部番号へのコールバック機能）;
SMSメッセージの送信（ロシア連邦外）;
PBXへの各着信呼び出しに関するサーバーへの通知、およびアプリケーションによるこれらの呼び出しのルーティング。

現在の機能は、CRM、コールトラッキングなどの簡単な統合に十分です。サービスとのより緊密な統合のために、次のバージョンでAPIの機能を拡張したいと考えています。

すべての方法の完全な公式説明は、サイトで入手できます。

利用可能な例とクラス：

現在、APIを操作するための完全なPHPクラスが利用可能です。Githubからダウンロードできます。すべての機能を使用する例もあります。

公式に加えて、PHPで作業するための、さらにはWindowsコマンドライン用の代替クラスが表示されます。

承認と開始

APIの使用を開始するには、Zadarmaシステムにアカウントを既に持っている必要があります。無料のPBX / 番号 / SIMカードが必要な場合は、最初にそれらをオンにすることをお勧めします。

次に、アカウントで認証用のキーを取得する必要があります。

承認が必要な各リクエストには、次の形式の追加ヘッダーが付随します。

「 認証：user_key：署名」

署名は、次のアルゴリズムに従ってコンパイルされます。

送信されたパラメーターの配列（GET、POST、PUT、DELETE）は、キー名のアルファベット順にソートされます。
結果の配列（たとえば、PHPのhttp_build_query関数）からクエリ文字列が形成されます。例：「from = DATEFROM＆to = DATETO ...」;
そしてさらに-式で接続されています：
文字列= method_name + query_string + md5（query_string）、
ここで、「method_name」は、パラメータがリストされるまで、ドメイン（APIバージョンを示す）から始まるクエリ文字列です。たとえば、-/ v1 / sip / "
受信した文字列は、ユーザーの秘密キーを使用してsha1アルゴリズムを使用してキャッシュされます。
ハッシュ=ハッシュ（文字列、secret_key）
さらに、ハッシュはbase64でエンコードされます
署名= base64_encode（ハッシュ）

PHPの例：

ksort($params); $paramsStr = http_build_query($params); $sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret)); $header = 'Authorization: ' . $userKey . ':' . $sign;

フォーマットと制限

応答形式：json（デフォルト）およびxml。

APIからxml形式の応答を取得するには、パラメーター「format = xml」がクエリ文字列に追加されます。

各応答には、制限と現在の要求に関する情報が含まれます。次に例を示します。

 X-Zadarma-Method: /v1/ X-RateLimit-Reset: 1434371160 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99

どこで

X-Zadarma-Method-呼び出される現在のメソッド。
X-RateLimit-Remaining-メソッドごとおよびユーザーごとの制限を考慮した残りのリクエストの数。
X-RateLimit-Limit-1分あたりのコールの合計制限の数値。
X-RateLimit-Reset-制限をリセットする時間。

ブロッキングの場合、メソッドは429ヘッダーに「レート制限を超えました」という応答を返します。

答えは、必要なキー「ステータス」（成功またはエラー）で構成されます。さらに、メソッドに応じて、要求された情報を持つキーが提供されます。

エラーが発生した場合、追加のキー「メッセージ」にエラーの説明が表示されます。

API経由の発信呼び出しの例

発信コールは、CallBackを介して行われます（コールバック操作の説明はこちら）。

仕事のスキーム：

ZadarmaサーバーへのAPIリクエストを受信しています
着信コールを受信し、「コールを待ちます」というメッセージを聞きます
サーバーは、必要なサブスクライバーの電話に2番目の呼び出しを送信します
加入者がコールに応答すると、通信できます。

注：「電話」の場所と「電話先の電話」の場所の両方に、SIPログイン番号またはPBX内線番号がある場合があります。これにより、オフィス内のIP電話/ゲートウェイ/ SIPプログラムからの発信通話だけでなく、ネットワーク内の通話も可能になります。

メソッド名： / v1 / request / callback /

パラメータ：

from-電話番号またはSIP。コールバックと呼ばれます。
to-呼び出されている電話番号またはSIP。
sip（オプション）-SIPユーザーの番号（このSIPに割り当てられた特定のCallerIDを使用する場合）。
予測（オプション）-このフラグが指定されている場合、要求は予測的です（システムは最初に「宛先」番号を呼び出し、ダイヤルされた場合のみSIPまたは電話番号に接続します）。

回答例：

ジョンソン

 { "status":"success", "from": 442037691880, "to": 442037691881, "time": 1435573082 }

XML

 <?xml version="1.0"?> <answer> <status>success</status> <from>442037691880</from> <to>442037691881</to> <time>1435573082</time> </answer>

Zadarmaクラスを使用したPHPの例：

 <?php include_once 'include.php'; $params = array( 'from' => '442037691880', 'to' => '442037691881', // 'sip' => 'YOURSIP' ); $zd = new \Zadarma_API\Client(KEY, SECRET); $answer = $zd->call('/v1/request/callback/', $params); $answerObject = json_decode($answer); if ($answerObject->status == 'success') { print_r($answerObject); } else { echo $answerObject->message; }

コールセンターの利便性

特にコールセンターでは、述語ダイヤルの可能性があります。システムは最初に「宛先」番号を呼び出し、ダイヤルする場合にのみ、SIPまたは電話番号に接続します。

たとえば、コールする番号の大きなリストとコールセンターの複数の従業員がいて、予測ダイヤルを使用すると、従業員が番号を1つずつダイヤルして結果を待つ必要がありません（労働時間の損失）。

コールセンターから番号を簡単に呼び出すには：

APIのコールバック関数への呼び出しを介して数値のリストを渡す
fromパラメータには、コールセンターの従業員が接続している無料の電話交換機の番号を指定し、予測フラグも示します。
できた！システム自体が顧客に電話をかけ、顧客が電話に出た場合にのみ、従業員が電話を受信して会話が開始されます。従業員の顕著な時間の節約。

注：有効な番号の4分の1以上が含まれている場合にのみ、システムはそのような呼び出しを行います。

着信通知

Zadarmaシステムは、各着信コールに関する情報を仮想PBXに送信し、回答に応じてコールを目的の内線番号にルーティングできます。これを行うには、Zadarmaシステムからの情報を含むPOSTリクエストを受け付ける、一般公開のリンクを作成する必要があります。

システムがリンクを受け入れるためには、スクリプトの最初に確認コードを追加する必要があります。

PHPの例：

 <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>

コールバックリンクに送信されるパラメーター：

caller_id-発信者の番号。
called_did-彼らが呼んだ番号。
callstart-通話開始時間

リクエストごとに、現在のコールのシナリオを「オンザフライ」で変更し、情報への応答として送信できます。

 { "redirect": ID, "caller_name": NAME }

どこで

redirect-スクリプトIDまたはPBX内線番号をリダイレクト、または「ブラックリスト」-この場合、通話はビジー信号で拒否されます。
caller_name-着信番号に名前を付けることができます。

PHPコード例：

 <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); if ($_POST) { $callerId = $_POST['caller_id']; // number of calling party; $calledDid = $_POST['called_did']; // number of called party; $callstart = $_POST['callstart']; // start time of call /* // For each request you can easily change work scenario for current call by sending in response on information: echo json_encode(array( 'redirect' => 1, 'caller_name' => 'TestName' )); exit(); */ }

APIメソッドの完全なリスト：

/ v1 / info / balance / -現在のユーザーのバランス。

/ v1 / info / price / -ユーザーの現在の関税を考慮した通話料金。

/ v1 /リクエスト/コールバック/ -コールバックのリクエスト（上記）;

/ v1 / sip / -ユーザーのSIP番号のリスト。

/ v1 / sip / callerid /-CallerIDの変更（取得または確認された番号から）;

/ v1 / sip / redirection / -ユーザーのSIP番号による現在のリダイレクトの表示、リダイレクトの有効化/無効化、リダイレクトパラメーターの変更。

/ v1 / sms / send /-SMSを送信します。

/ v1 /統計/ -一般統計を取得します。

/ v1 /統計/ pbx / -フリーPBXの統計。

将来的には、メソッドの数の増加が計画されています。 APIに追加する必要があるメソッドがあると思われる場合は、コメントを記入してください。

無料のPBXおよびテレフォニー用のAPIインターフェイス