2018.05.22. Cisco Webex TeamsからCisco Webex Teamsへの名称変更に伴い、記載内容を変更しました。
この記事では、以下に関して記載しています
- Cisco Webex TeamsのBot用アカウントの概要
- Cisco Webex TeamsのBot用アカウントのつくり方
- Cisco Webex TeamsのBot用アカウントの特徴や性質
1. Cisco Webex TeamsのBot用アカウント
Cisco Webex TeamsのBot用アカウントは、
アプリケーション用のCisco Webex Teamsアカウントの１つです。
アプリケーションは、Botアカウント用に発行されたトークンを使ってAPIを実行することで、
チャットボットなどをCisco Webex Teams上で動作させることができます。
Bot用アカウントは、通常のCisco Webex Teamsのアカウントとは異なり、
Cisco Webex Teamsのクライアントアプリでログインしたりはできません。
Cisco Webex Teamsのユーザは、Botを任意のスペースに追加することができ、
追加されたスペース内で、そのBotが動作することになります。
Bot用アカウントの構成要素は以下のようになります。
Botの作成、設定ページに合わせて要素名を英語にしています。
ユーザが目にするものもあれば、Botアプリ側に関係あるものもあります。
| 要素 | 説明 | 補足 |
|---|---|---|
| Name | Botの表示名 | スペース内でも、この名前で表示される。名前設定時には、間にスペースは入れない方がよいかも。 |
| Bot Username | "@webex.bot"で終わるメールアドレス形式のID | このIDをスペースに追加すれば、このBotでスペース内のメッセージの読み書きができる。 |
| Icon | Botを表すアイコン | スペース内でも、このアイコンで表示される。 |
| Description | Botの説明文 | Botの詳細を記載しておく。 |
| Bot's Access Token | Bot用のトークン | アプリ側でAPIを呼び出す際に、Authorizationヘッダーで指定するトークン。厳重管理が必須。 |
| Bot ID | Botの管理上のID | 内部管理やAPI上で利用されるBotのID。 |
2. Bot用アカウントの作成
開発者は、無償アカウントを使って、
Cisco Webex Teamsの開発者サイトにログインして、
Bot用のアカウントを作成できます。
2.1. Botアカウント作成画面へ行く
- Cisco Webex for Developers(https://developer.webex.com/)に行きます。
- 画面右上の[Log In]から、Cisco Webex Teamsのアカウントでログインします。
- 画面右上の自分のアイコンを押してから[My Webex Teams Apps]をクリックして、表示されたページで、右側の[+]ボタンを押します。
- [Create a Bot]ボタンを押すと、Botアカウント作成画面に進みます。
[Create an Integration]の方は、ユーザの代理として動作するアプリケーションを作る仕組みの方ですが、
まずは、Botの方が、とっかかりやすいと思います。
2.2 作りたいBotの情報をうめていこう
上の表を参考に情報をうめていきます。
いくつかのポイントです。
- ほとんどの項目はあとでも変更できますが、[Bot Username]は変更できない。
- [Name]は、日本人しか絶対に使わないBotなら日本語もOKだが、まあ、ASCII文字だけにしておくのが無難。
- [Name]は、Cisco Webex Teamsクライアント側でファーストネーム等が処理される場合があるので、間にスペースを含まない名前にするのが無難。
- [Bot Username]は、"@webex.bot"より前の部分を半角英数と一部の記号のみで設定。
- [Bot Username]は、世界中でまだ誰も使ってないものなら取得できる。
- [Icon]は、512 x 512ピクセル以上のpngかjpgファイルをアップロード、または、サンプルから選択。
- [Description]には、分かりやすい説明をつけておく。
- Botの仕組み上、ユーザはBotに直接語り掛けるので(後で説明)、[Name]と[Bot Username]には、かっちょいいものを考えて設定するのが吉。
2.3. [Add Bot]ボタンを押せば、Botアカウント作成完了
[Add Bot]を押すと、Botアカウントの作成が完了します。
作成完了後の画面に、
[Bot's Access Token]が表示されるので、このトークンをコピーしてアプリケーション側で、
APIを呼び出す際に指定します。
[Bot's Access Token]は、厳重に管理して、絶対に漏らさないようにします。
設定画面では、1度だけ表示されるので、わかんなくなった場合は、[Regenerate Access Token]で、
新しいトークンが発行されます。
2.3. 開発者サイトからログアウトしよう
Botのアカウント作って、[Bot's Access Token]も取得した後は、
とりあえず、ログイン状態の開発者サイトは、一旦、用済みになります。
必要ない間は、開発者サイトからログアウトしましょう。
開発者サイト右上のユーザアイコン部分を押すと、[Log Out]リンクが出てきます。
「開発者トークン」が無効になる趣旨のメッセージが表示されますが、
[Log Out]ボタンを押してログアウトしましょう。
ログアウトで無効になるのは、[開発者トークン]であって、
[Bot's Access Token]は、開発者サイトからログアウトしても有効なままです。
3. Cisco Webex TeamsのBotを開発者目線でさくっと説明
細かいことは、また別記事にしようと思いますが、ポイントだけさくっと。
3.1. [Bot's Access Token]の使い方
httpsで、Cisco Webex TeamsのAPIを呼び出すときに、
Authorizationヘッダーに、"Bearer" + " " + "BotのToken文字列"を指定します。
例えば、[Bot's Access Token]が、xyzだったと仮定すると、
Authorization: Bearer xyz
のようなAuthorizationヘッダをつけて、APIを呼び出すことになります。
これで、該当のAPIの呼び出しは、Botアカウントで実行されます。
3.2. Botが読めるメッセージは制限されている
Botは、そのBotに対して明示的に話しかけられたメッセージだけを読めます。
つまりは、以下の条件が成立するときのみ、そのメッセージをAPIで取得できます。
- Botに明示的に@メンションで話しかけた、または、Botとの1:1スペース内で話しかけたメッセージ。
- Bot自身が投稿したメッセージ。
Webhook(別記事で説明予定)を使って、リアルタイムに投稿されたメッセージの通知を受けることができますが、
その場合も、上記と同様のメッセージのみが通知されます。
スペース内では、Botアプリにまったく無関係なセンシティブな情報もやりとりされている可能性もあります。
Botがスペース内の任意の情報にアクセスできると、これらBotに無関係な情報まで、
Botアプリで取得できるようになってしまうため、このような制限が意図的にかけられています。
3.3. Botにはよく話しかけることになるので、よい具合の名前を
上記の仕様のおかげで、ユーザは、明示的にBotに話しかけるようになるので、
広まりやすい、呼びかけやすい、よい名前をつけるとGoodです！
3.4. [Bot Username]の使い方
"@webex.bot"で終わるメールアドレス形式のIDを、Cisco Webex Teamsのスペースのメンバーに追加すると、
そのスペースでBotが動作できるようになります。
上で説明した制限の範囲で、APIを使ってメッセージの読み書き、Webhook(別記事で説明予定)での通知受信などができます。
公開できるレベルまで開発を進めたあとは、
Cisco Webex App Hubに、Botの公開を申請することもできます。
開発完了後に申請するものなので、Botアカウント作成直後は、普通はまだ関係ありません。
Cisco Webex App Hubで公開すると、
ユーザは、より簡単に、スペースにBotを追加できるようになります。
申請は、Botの設定変更ページを表示して、[Submit Your Bot to Webex App Hub]タブからできます。
3.5. [Bot ID]の使い道
いろいろありますが、よく使う使い方を１つ。
[Bot ID]は、Cisco Webex TeamsサービスやAPIで利用する、Botの内部的な管理IDです。
Webhook(別記事で説明予定)を使うと、Botに対して投稿されたメッセージをほぼリアルタイムで通知を受けることができます。
Bot自身が投稿したメッセージも通知されるので、通知されたメッセージに対して、返答するようなBotアプリを作るとループすることがあります。
メッセージを投稿した人のIDが[Bot ID]の場合は、返答しないような処理をすることでループを回避できます。
なお、[Bot ID]は、API経由で取得できるので、アプリ側で設定で持っておくよりも、
アプリ起動時に取得してしまう方が柔軟だと思います。
[Bot's Access Token]を使って、
GET https://api.ciscospark.com/v1/people/me
APIを使えば、Bot IDは取得できます。
リファレンス的には、こちら : Get My Own Detailsです。
3.6. Botアカウントは、特定のCisco Webex Teamsアカウントに紐づく
Botアカウントは、Botアカウント作成時に開発者サイトにログインしたCisco Webex Teamsアカウントに紐づくことになります。
特定のCisco Webex Teamsユーザに紐づくのが都合が悪い場合は、
Botアカウントのベースになる専用のCisco Webex Teamsアカウントを作っておくなどの対応が必要だと思います。
困る例で考えるとわかりやすいです。
Botアカウントを生成した、とあるCisco Webex Teamsアカウントのユーザが転職した場合とか、
その人のアカウントに紐づいていると、該当のBotアカウントの管理に困る場合があります(管理画面に行けないので)。
3.7. Botにも、どの組織に属するかの概念がある
Cisco Webex Teamsは、ビジネスコラボレーションサービスのため、
ユーザアカウントには、どの組織に属するかの概念があります。
もちろん、組織間でのコラボレーションでCisco Webex Teamsを利用することが可能です。
Botアカウントは、作成した人のCisco Webex Teamsアカウントと同じ組織に属します。
ほかの組織で作成されたBotをスペースに追加できますが、スペースに「外部からの参加者あり」のマークがつく場合があります。