この記事はシスコの有志による Cisco Systems Japan Advent Calendar 2021 (2枚目）の8日目として投稿しています。
Cisco Systems Japan Advent Calendar
2017年版: https://qiita.com/advent-calendar/2017/cisco
2018年版: https://qiita.com/advent-calendar/2018/cisco
2019年版: https://qiita.com/advent-calendar/2019/cisco
2020年版: https://qiita.com/advent-calendar/2020/cisco
2020年版(2枚目): https://qiita.com/advent-calendar/2020/cisco2
2021年度： https://qiita.com/advent-calendar/2021/cisco
2021年度（２枚目）：https://qiita.com/advent-calendar/2021/cisco2
##はじめに
クラウドPBXが徐々に脚光を浴びて、今後ますますユーザが増えていくことが予想されています。Cisco もWebex Calling というクラウドベースでPBX機能を提供するサービスを提供しています。
今まで会社でしか使えなかった電話が、オフィス、外出先、自宅、どこにいても利用できます。Webex Callingの製品概要にご興味がある方はこちらをご覧ください。
そんな中、自社で展開しているシステムと連携したいという要望を聞くことも出てきました。自社のシステムから宛先を決めて電話をかけたい、発着信のイベント情報を自社のシステムと連携させたい、といったご相談です。そういうときはWebex Calling のAPI機能の出番です。この記事ではWebex Calling のAPIを紹介していきます。
なお、Webex Calling APIを始めてみよう-３種類のAPIを試してみた-にて、実際にAPIを試した例も紹介していますので、合わせてご確認いただけると幸いです。
##Webex Calling APIの種別
Webex Calling で利用するAPIは大きく下記の3つがあります。
- 呼制御：REST APIを利用して 電話の発信、応答、切断をはじめとした呼の制御が可能です。
- イベント：Webhook を利用して電話の発着信、ステータスの変化、切断を通知することが可能です。
- 設定:RESTAPIを利用してWebex Calling に関連した設定を行うことが可能です。
それぞれのAPIについて、もう少し詳しくご紹介していきます。
Webex Calling API 呼制御
REST APIを利用して呼の制御をすることができます。
REST APIの認証には他のWebex サービスと同様、各ユーザに紐付けをされたAccess Tokenを利用します。また、それぞれの動作に対して必要なパラメータを入れて呼の制御を行います。
WebexのAccess Tokenを試験用に利用するにはWebex for Developers から自分のアカウントに紐付いた試験用のTokenを取得する方法が便利です。実際のサービスで利用するためにはIntegrations の仕組みを用いてAcess Tokenを取得することが可能です。
試験用の時間限定のAccess Token は下記の場所から取得可能です。
Webex Calling APIの呼制御を利用してできる内容をいくつかご紹介します。
- ユーザに紐付けをした電話機から発信を行う
- 着信した呼に対してユーザのプライマリの電話機で応答する
- 呼を切断する
- 応答前に拒否する
- 呼を保留・保留解除する
- 呼を転送する
- パークする、パークした呼を取得する
- 録音の開始・終了・ポーズ・ポーズ解除
- アクティブな呼の情報をリストで取得
- 特定の呼の詳細を取得、履歴を取得する
各制御、及び情報の取得はGuideのCall Controlセクションから、選択することで確認が可能です。
Answerのように該当呼を特定する必要がある場合、CallID情報が必要です。CallIDの情報は List Calls を利用してCallIDを確認するか、このあと紹介するWebex Callingのイベント通知から取得する方法が可能です。
List Calls からCallIDを取得した例
実際には制御する内容によって、宛先番号、送信するDTMF情報など、各メソッドに応じたパラメータを指定してAPIを利用します。
Webex Calling API イベント
Webhookを利用して電話の発着信、ステータスの変化、切断を通知することが可能です。該当するイベントが発生すると指定されたURLに対して通知を行います。
Webhookの設定はREST APIを利用することで可能です。Webhook の名前、受信するTargetURL、どのイベントを取得するかを決めてREST APIで作成します。TargetURLはWebex から到達可能なインターネット上のURLである必要があります。
Webex Calling のイベントを取得する場合、resource パラメーターには telephony_callsをEventパラメーターには下記の4つの内いずれかを設定します。
- created: 呼を発信、または着信した際に通知。
- updated: 呼のステータスが変わった際（応答、転送等）に通知。
- deleted: 呼を切断した（された）場合に通知。
- all: 上記全てのEventを通知。
フィルター条件もWebhook作成時に設定することが可能です。これにより、特定の条件にマッチする場合のみ通知することが可能です。
WebhookのBodyにはJSON形式で情報が含まれます。Webhook自体の情報に加えて、dataの中に呼の情報が含まれます。前述したCallIDもイベントによる通知から取得が可能です。
Webex CallingのEventをWebhookで受信した例：
Webex Calling API 設定
REST APIを利用してWebex Calling に関連した設定を行うことが可能です。
Webexでは各種サービスが一元化された管理ポータル Webex Control Hub から設定を行うことが可能です。ユーザ設定などWebex全体で共通して利用するもの、Webex Calling 特有のユーザ単位設定、全体で利用する機能設定など、多くの設定をREST APIから実行することが可能です。
Webex全体で利用するユーザ情報としてはメールや名前情報に加えて、Webex Callingで利用する電話番号も含まれます。Peopleを利用して、ユーザの追加、アップデート、削除を行うことができます。
WebexCalling 特有のユーザ設定に関してはWebex Calling Person Settingsで、利用するプロファイルや転送の設定などを実行することが可能です。
また、ユーザレベルでボイスメールの操作をWebex Calling Voice Messaging実施することができます。
管理者レベルで設定を行うWebex Calling 特有の機能もAPIから設定できるものがあります。例えば、コールピックアップの作成・アップデート・削除、ハントグループの作成・アップデート・削除など。多くの設定がAPIを利用して可能です。Webex Calling Organization Settingsから確認が可能です。
設定をする際にWebex CallingはLocation 情報が必要な場合があります。Location情報はAPIからは読み取りのみが可能です。Locationsを利用してLocationIDが取得可能です。
終わりに
この記事では３種類のWebex Calling のAPIについて紹介しました。
クラウドを利用した電話サービスは今後も拡大が予想されています。より自分たちにとって、お客様にとって便利な電話の使い方を目指す上でWebex Calling のAPIが活用できるシーンが出てくると考えています。
APIを実際に試した例をWebex Calling APIを始めてみよう-３種類のAPIを試してみた-で紹介しています。
これらの記事の内容を参考にして、Webex Calling 自体、そしてAPIを試していただき活用していただけると幸いです。
##免責事項
本サイトおよび対応するコメントにおいて表明される意見は、投稿者本人の個人的意見であり、シスコの意見ではありません。本サイトの内容は、情報の提供のみを目的として掲載されており、シスコや他の関係者による推奨や表明を目的としたものではありません。各利用者は、本Webサイトへの掲載により、投稿、リンクその他の方法でアップロードした全ての情報の内容に対して全責任を負い、本Web サイトの利用に関するあらゆる責任からシスコを免責することに同意したものとします。