Tocaro - Web API 技術仕様 – Tocaroヘルプセンター

概要

現時点では、Botを実現するために必要最低限の操作（データの取得・新規作成）ができるAPIを提供しています。

#	API種類	概要
1	ユーザー操作	同一契約内のユーザーデータを検索、取得することができます。
2	グループ操作	Bot ユーザーをグループのオーナーとしたグループを新規作成することができます。
3	メッセージ投稿	グループ、トークに対してBotユーザーからメッセージを投稿することができます。
4	ToDoリスト	対象のグループに関連づけたToDoリストを新規作成することができます。
5	タスク操作	ToDoリストに新規タスクを作成することができます。

認証方式

Web API の認証には OAuth 2.0 JWT Bearer Token を用いて、認証を実現します。

必ず、HTTPのリクエストヘッダーに以下のような定義を指定してください。

Authorization: Bearer {Token}

スコープ

Token に対して Scope を設定し、 Readonly / Writeonly などの Access Control を付与することができます。

Botユーザーの作成手順

以下の手順でBotユーザーを新規作成することができます。

Tocaroにログイン後、次のURLにアクセス　https://tocaro.im/application/api
新規作成をクリック
必要な設定項目を入力し、登録ボタンをクリック
- 名前: Botユーザーのユーザー名を指定してます。
- 言語: Botが投稿するデフォルト言語を指定(基本的に日本語を選択)
- 投稿先グループ: Botユーザーを参加させたいグループを選択します。（任意）
  - ※一覧に表示されるグループはログインユーザーがオーナーのグループのみです。
  - また、WebAPI経由で新規作成したグループは自動でBotユーザーとログインユーザーがオーナーのグループとなります。
- スコープ: 権限のスコープを選択します。
  - read: GETメソッドのAPIに対応
  - write: POSTメソッドのAPIに対応
- アイコン: Botユーザーのプロフィール画像を指定します。
JWT の Token キーが発行されますので、必要に応じて保管してください。
- JWT の Token キーは認証に変わる重要な情報です。適切に管理してください。

API の詳細な仕様

各APIのリクエスト・レスポンスデータの詳細は以下のURLで公開しています。

https://storage.googleapis.com/tocaro-api-docs/index.html

こちらを参照してください。

Botユーザーからのメッセージ投稿

Botユーザーからメッセージを投稿する場合は通常のメッセージもしくはユーザーからのアクションに応答できるメッセージを投稿することができます。

メッセージの投稿はグループ・トークのいずれかを選択し、投稿してください。

グループへのメッセージ投稿

Botユーザーを作成するときに指定したグループに対してメッセージを投稿することができます。

また、Webhook で実現が難しかった特定ユーザーへメンション付きのメッセージを投稿することができます。

メンション付きのメッセージを投稿する場合はメッセージ本文に <@user_code> のように指定してください。

curl -X POST https://api.tocaro.im/messages
              -H 'Content-Type: application/json' \
              -H 'Authorization: Bearer $TOKEN' \
              -d @- << EOF
              '
                {
                  "group": "grxxxxxxxx",
                  "text": "<@us11111111> Hello World!"
                }
               '

ユーザーコードはグループのメンバ情報および同一契約内のユーザー操作APIより取得してください。

トークへのメッセージ投稿

Botユーザーから特定のユーザーに対してメッセージを投稿することもできます。

特定のユーザーに対してメッセージを投稿する場合は、リクエストデータでuserパラメータを指定します。

curl -X POST https://api.tocaro.im/messages
              -H 'Content-Type: application/json' \
              -H 'Authorization: Bearer $TOKEN' \
              -d @- << EOF
              '
                {
                  "user": "urxxxxxxxx",
                  "text": "Hello World!"
                }
               '

注意事項

Web API で操作できるデータは同一契約内のデータおよびBotユーザーが所属するグループのみです。この範囲を超えてデータを取得することはできません。

また、Botユーザーは作成したユーザーに関連づけて管理していますので、Botユーザーを作成するユーザーはアカウント停止されないシステムユーザーなどで作成してください。

概要