Webex Calling APIを始めてみよう-３種類のAPIを試してみた-

この記事はWebex Advent Calendar 2021　の8日目として投稿しています。

Webex Advent Calendar
2021年版： https://qiita.com/advent-calendar/2021/webex


## Webex Calling APIを試す
[Webex Calling APIを始めてみよう-概要を把握する-](https://qiita.com/tatakaya/items/1d076ec4328d2033701e) では下記３種類のAPIについてご紹介しました。

1. 呼制御：REST APIを利用して　電話の発信、応答、切断をはじめとした呼の制御が可能です。
1. イベント：Webhook を利用して電話の発着信、ステータスの変化、切断を通知することが可能です。
1. 設定:RESTAPIを利用してWebex Calling に関連した設定を行うことが可能です。

この記事では簡単に使えるツールを利用して実際に3種類のAPIを試してみた例をご紹介します。


## Webex Calling API 呼制御を試してみた
呼制御のAPIを試したりデモをするために便利な[Postman Collection](https://github.com/webex/postman-webex-calling) が公開されています。
この記事では、最も基本的な呼の発信と着信をPostman Collectionで試した例を紹介します。

**利用前提**

- 利用するユーザ向けにWebex Calling の設定にて電話機を関連付けして利用できるようにしておきます。
- Postman Collectionのリンクからwebex-calling-calls-api.json を取得します。
- POSTMANを起動しJSONファイルのインポートを行います。
- 試験用のBearer Tokenを取得します。
- 利用するシナリオのフォルダ設定のAuthenticationタブでTypeにBearer Tokenを選択し、Token情報を入力　Saveします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/7ec684bb-4390-140f-d73d-59db82fb5d49.png)




**呼の発信**

- Dial(Click to Calal)を選択します。
- Body　の DESTINATION に宛先情報を入力しPOSTします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/2eb10390-722c-5f2f-6a53-c65767db8ade.png)


- 自分に関連付けした電話機が鳴動するため応答します。
- 上記自電話機での応答後、宛先の電話が鳴動するためこちらも応答します。
- 呼が繋がっていることを確認します。

**呼の着信**

- 対向の電話機から自電話機に対して発信をします。
- 自電話機が鳴動していることを確認します。
- Get Call Status (APIとしては[List Calls](https://developer.webex.com/docs/api/v1/call-controls/list-calls)を利用)のタブを開きGETします。
- レスポンスを確認し、応答する呼のidをコピーします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/f3fe726e-8ef8-84bc-5578-15fdafad58f9.png)

- Answer a Call を開きBodyのCallIdに先程コピーした情報を入力してPOSTします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/08156e81-9712-c510-a0eb-52087dc25e5e.png)

- 呼が繋がっていることを確認します。

他のシナリオも似たような手順で試験が可能です。
試す内容によっては事前にWebex Calling側で設定が必要なものがありますのでご注意ください。

## Webex Calling API イベント試してみた
このポストでは試験としてWebex for Developer ページから呼の発着検知用のWebhookを作成、webhook.site を利用して実際のwebehookを取得したところまでの例を紹介します。

**Webhookの設定**

- [webhook.site](https://webhook.site/)を開き、テスト用のWebhook target URL情報を取得します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/117e53f6-4206-7119-a14a-c89e753cddb1.png)


- Webex for Developer のページを開き、Webex Calling のアカウントを持っているユーザでログインします。
- [Create a Webhook](https://developer.webex.com/docs/api/v1/webhooks/create-a-webhook)を開き、下記のパラメーターを入れてRun ボタンを押します。
    - Name: (任意の名前でOK)
    - targetURL: webhook.siteで取得したURL
    - resource: telephony_calls
    - event：created

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/f8160afa-2164-fcbc-0e8e-6aaa09ea9720.png)

- 200OKが返ってきてWebhookが設定されたところを確認します。

**Webexでの通知テスト**

- 実際に自分の電話機に向けて他の電話機から発信します。
- webhook.site 上でWebhookによる通知があったことを確認します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/8b739cda-d39c-59e8-a764-e6641c66b748.png)

同様の手順で他の手順も試すことが可能です。またフィルター条件を付与するすことも可能です。

## Webex Calling API 設定を試してみた。
この記事ではWebex for Developer のページからピックアップグループを設定した例を紹介します。

ハントグループを設定するにあたり、設定するロケーション、ハントグループ用の設定名、ピックアップグループに含まれるユーザや電話機を事前に決めておきます。

**ユーザ、電話機、ロケーションの情報の取得**

- Webex for Developer のページを開き、管理者権限でログインします。
- ピックアップグループに入れるユーザ情報を[List People](https://developer.webex.com/docs/api/v1/people/list-people)を使って取得します。200 OKが返却され、Bodyにユーザ情報が含まれるため、該当ユーザのIDを保管します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/4f8c6eec-bf99-00be-a3c6-fcb64aa2d2d8.png)


- ユーザに紐付けされていない電話機をハントに含める場合には[List Workspaces](https://developer.webex.com/docs/api/v1/workspaces/list-workspaces)を使ってID情報を取得します。
- List Locations を使って設定するLocation のID情報を取得します。

**ピックアップグループの設定**

- [Create a Call Pickup](https://developer.webex.com/docs/api/v1/webex-calling-organization-settings-with-call-pickups/create-a-call-pickup)を開き、下記のパラメータを入れてRun します。
    - LocationID:取得したLocationIDをtargetURLの中に含めるように設定
    - name:(任意の名前でOK)
    - agent: 取得したIDを利用
- 201 Created が返却され、ピックアップグループが作成されたことを確認します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/5c0ebc19-e485-2d2f-238b-8e96ea651ad1.png)


- Control Hub からピックアップグループが作成されていることを確認します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/412449/25c7a819-0b23-144a-e65f-5cb265fd6093.png)

設定する項目によってパラメータが異なりますが、同様の手順で確認をすることが可能です。

## 終わりに
この記事ではWebex Calling のAPIを試した例を紹介しました。
Webex Calling APIの概要は[Webex Calling APIを始めてみよう-概要を把握する-](https://qiita.com/tatakaya/items/1d076ec4328d2033701e)で紹介しています。
これらの記事の内容を参考にして、Webex Calling 自体、そしてAPIを試していただき活用していただけると幸いです。

##免責事項
本サイトおよび対応するコメントにおいて表明される意見は、投稿者本人の個人的意見であり、シスコの意見ではありません。本サイトの内容は、情報の提供のみを目的として掲載されており、シスコや他の関係者による推奨や表明を目的としたものではありません。各利用者は、本Webサイトへの掲載により、投稿、リンクその他の方法でアップロードした全ての情報の内容に対して全責任を負い、本Web サイトの利用に関するあらゆる責任からシスコを免責することに同意したものとします。