知話輪APIドキュメント

知話輪は他社のチャットツール等のタイムラインベースのコミュニケーションツールと同等の機能を備えていますが、さらに外部のシステムと柔軟に連携できるように様々なAPIを用意しています。これらは「知話輪API」と呼ばれます。

以下は知話輪APIを構成する主なコンポーネントです。

Incoming WebHooks
知話輪に対してメッセージを送信したい場合のもっとも簡単な方法です。HTTPのメソッドでリクエストを送信するだけなので、様々な環境から実行可能です。当面はBotを介しての利用となります。
Outgoing WebHooks
知話輪上のメッセージを外部のシステムやサービスに渡したい場合のもっとも簡単な方法です。当面はBotを介しての利用となります。
Bot Users
ボットは様々なグループに常駐させることが可能で、グループメンバーとして扱われます(既存の知話輪利用者向けに設定画面を2017年4月に当サイトにて提供予定です)。外部サービスやシステムからボットにメッセージを送信させたり、ユーザからのメンションを契機に外部システムやサービスを呼び出すといった独自の機能が提供可能になります。
Web API
知話輪のデータや機能に簡単にアクセスできるようにするインタフェースです。WebHookと併せて利用することで、対話型ボットアプリケーションの開発が可能です。
Custom Commands
すべてのグループで利用可能な独自の機能を追加できるインタフェースを準備中です(提供時期未確定)。外部サービスと直接やりとりできる独自コマンドを追加したり、サードパーティが提供しているApp commandsを登録して、気軽に独自機能を追加したい場合に利用します。実行結果は原則として実行したユーザのみ見られます。当初はカスタムメニューを追加できるようにするところから公開していく予定です。

これらのAPIを利用することで、外部プログラムから任意のタイミングで知話輪にメッセージを送ったり、知話輪から外部プログラムを実行したりすることができ、コミュニケーションの一層の活性化を実現することができます。

INSUITE®やひびき®Sm@rtDB等のドリーム・アーツの製品についても知話輪APIを利用して知話輪と連携しています。以下はドリーム・アーツ社内で知話輪APIが利用されている具体例です。

  • サポートサイト宛に頂いた問い合わせで、回答期限が迫っているものがあれば、担当者にプッシュ通知
  • 知話輪上で簡単なメッセージを書き込むだけで自分に新規にアサインされたお問い合わせの一覧を取得
  • ホスティングさせていただいているシステムに異常があった際に関係者にプッシュ通知
  • 各種サービスの日次や週次の統計情報の自動通知

WebAPI

WebAPIを使用することでユーザ情報、グループ情報取得といった知話輪のデータや機能にプログラムから簡単にアクセスできます。
外部システムの情報をグループチャット内にメッセージとして投稿したり、Webhook機能と併せることで対話型ボットアプリケーションの開発が可能になります。

リクエスト

APIエンドポイントURLへはhttpsで接続してください。 (httpで接続された場合は知話輪側でhttpsへリダイレクトします。)
また認証用のAPIトークンをHTTPヘッダー(X-Chiwawa-API-Token)にセットしてください。

レスポンス

レスポンスはJSON形式になっています。API呼び出しの成否はHTTPステータスコードで判定してください。
失敗の場合 `code,error`プロパティにエラー内容がセットされます。

{ "code":"CAE001", "error":"somethig_bad" }

ベースURL

APIエンドポイントのベースURLはhttps://{企業ID}.chiwawa.one/api/public/v1になります。
ベースURLに続けて各APIのエンドポイントパスを付加してください。
企業IDは管理画面から確認できます。

API認証

API認証はトークンにより行われます。
APIリクエスト時にHTTPヘッダー(X-Chiwawa-API-Token)にAPI利用トークンをセットします。
API利用トークンは知話輪管理画面でAPI利用ユーザ(Botユーザ)を登録することで発行されます。
API利用ユーザは利用目的に合わせて任意の数登録可能です。
APIトークンの取扱には十分注意してください。APIトークンを使用すると知話輪のデータに自由にアクセスできます。公開リポジトリやJavascriptのようなクライアントサイドのコードに置かないで下さい。

利用回数制限(Rate Limit)

APIの呼び出しには一定時間毎の利用回数に制限があります。この制限を超えた場合APIのレスポンスとして429 Too Many Requestsエラーが返されます。
利用回数制限は利用プラン毎に異なります。

知話輪API一覧

知話輪で利用できるAPI一覧を紹介します。

メッセージ投稿

グループチャットにメッセージを投稿します。

エンドポイント

POST /groups/{外部参照グループID、グループID、外部参照ユーザIDまたはユーザID}/messages

リクエスト

POST /groups/%2FInsuite%2Fgroup%2F2000001/messages { "text":"こんにちは", "from":{ "userId":"/Insuite/member/1000003", "name":"知話輪 太郎" }, "to":[ "/Insuite/member/1000001", "/Insuite/member/1000002", ], }
フィールド名 サブフィールド名 データ型 必須 内容
to - 配列 メッセージをメンションするグループ所属ユーザのユーザIDもしくは外部参照ユーザID。
from - オブジェクト メッセージ送信元のユーザ情報。未指定の場合、利用APIトークンにひもづくAPI利用ユーザ情報が使用される。
- userId 文字列 メッセージ送信元のユーザIDもしくは外部参照ユーザID。存在しないユーザが指定された場合は無視される。
- name 文字列 メッセージ送信元のユーザ名称。userIdフィールドで指定されたユーザの名称より優先して使用される。
toAll - 真偽値 メッセージをグループ全体にメンションする場合はtrueをセット。
text - 文字列 必須 メッセージ本文。
attachments - 配列 メッセージ付加情報。詳細は以下のattachmentsを参照。

attachments

フィールド名 サブフィールド名 データ型 必須 内容
attachmentId - 文字列 必須 付加情報を識別するためのユニークなID。
viewType - 文字列 付加情報の表示形式。text: テキスト。
title - 文字列 付加情報タイトル。
text - 文字列 付加情報テキスト本文。
textInTimeline - 文字列 タイムラインに表示するテキスト。指定がない場合は、本文の先頭を表示する。
lineBreakInTimeline - 文字列 改行の表示パターン。trim: タイムライン表示の際に改行を消す、none:改行はそのまま(デフォルト)
textType - 文字列 本文の形式。指定がない場合は改行のみBRタグに変換される。html:html形式、md:Markdown形式、none:改行のみBRタグに変換。
color - 文字列 付加情報のテーマカラー。16進数のカラーコードで指定。指定がない場合は色をつけない。
tagIcons - 配列 通知の種別を示すアイコン。
bell:、calendar:、check:、checkeddocument:、clock:、document:、graph:、location:、lock:、reply:、rss:
displaysCommentField - 文字列 yes: コメント入力欄を表示する。no: コメント入力欄を表示しない。
commentField - オブジェクト - コメント入力欄情報。
- placeholderText 文字列 - コメント入力欄が空の場合に表示する説明用のテキスト。デフォルトは「コメントを書く」。
- localizedPlaceholderText オブジェクト - "ISO言語コード": "当該言語のplaceholderText。マッチする言語がない場合はplaceholderTextを表示。"
actions - 配列 付加情報に表示するボタン。
- buttonTitle 文字列 選択肢ボタンのタイトル。タイムライン上のボタンは2つ目以降非表示。
- localizedTitle オブジェクト "ISO言語コード": "当該言語のボタンタイトル。マッチする言語がない場合はbuttonTitleを表示。"
- displaysIn 文字列 選択肢ボタンの表示条件。timeline: タイムラインに表示、detail: 詳細画面に表示、both: 両方(デフォルト)
- actionUrl 文字列 選択肢ボタンが押された時の遷移先URL。次のプレースホルダーが指定可能。
%groupId% : グループID (INSUITEから連携されたグループの場合は外部キーをセット)
%messageId% : メッセージID
%userId% : ユーザID (INSUITEから連携されたユーザの場合は外部キーをセット)
- authType 文字列 遷移先の認証種別。sdb: Sm@rtDB、insuite: INSUITE、none: なし
- actionType 文字列 選択肢ボタンを押下した時の動作種別。detail: 詳細画面を開く、inAppBrowser: アプリ内ブラウザで開く、externalApp: 外部アプリで開く、get: HTTP GETリクエストを送信、post: POSTリクエストを送信
- postBody オブジェクト 遷移先URLにPOSTする内容。postBodyContentTypeをform形式にする場合は、key, valueともにStringのオブジェクトのみ指定可。次のplaceholderが指定可能。%groupId% : グループID (INSUITEから連携されたグループの場合は外部キーをセット) %messageId% : メッセージID %userId% : ユーザID (INSUITEから連携されたユーザの場合は外部キーをセット)
- postBodyContentType 文字列 リクエストのpostBodyのコンテントタイプ。
json: JSON形式(デフォルト。ただし、authTypeがsdb, insuiteの場合はデフォルトはフォーム形式となる。なお、sdb, insuiteの場合も明示的にJSON形式を指定することも可能。)
form: フォーム形式

レスポンス

{ "messageId":"-KWbIsaqyS9k-K8nMhzH" }
フィールド名 内容
messageId 登録されたメッセージのシステムID。

メッセージ一覧取得

グループチャットに投稿されたメッセージ一覧を取得します。
メッセージは作成日時の降順で取得されます。

エンドポイント

GET /groups/{外部参照グループIDもしくはグループID}/messages

リクエスト

GET /groups/%2FInsuite%2Fgroup%2F2000001/messages?maxResults=100&createdAtFrom=14792020158
パラメータ名 データ型 必須 内容
createdAtFrom 数値 メッセージ取得の起点となるメッセージ作成時日タイムスタンプ(UTCミリ秒)。指定した作成日時以降のメッセージが取得対象となります。デフォルトは0。
createdAtTo 数値 メッセージ取得の終点となるメッセージ作成時日タイムスタンプ(UTCミリ秒)。指定した作成日時以前のメッセージが取得対象となります。デフォルトは現在日時。
maxResults 数値 一度のリクエストでの最大取得件数。上限は100。デフォルトは20。

レスポンス

{ "messages":[ { "messageId":"-KWbIsaqyS9k-K8nMhzH", "type":"text", "text":"こんにちは", "createdAt":14792020158, "createdBy":"-KWGbhXzcbPBBSPS3R_j", "createdUserName":"知話輪 太郎" } ] }
フィールド名 内容
messageId メッセージID。
type メッセージタイプ。text:テキスト、image:画像
text メッセージ内容。typeがtextのときのみ設定されます。
createdAt メッセージ作成日時タイムスタンプ(UTCミリ秒)。
createdBy メッセージ作成ユーザのシステムID。
createdUserName メッセージ作成ユーザの名前。

メッセージ情報取得

メッセージ情報を取得します。

エンドポイント

GET /groups/{外部参照グループIDもしくはグループID}/messages/{メッセージID}

リクエスト

GET /groups/%2FInsuite%2Fgroup%2F2000001/messages/-KWbIsaqyS9k-K8nMhzH

レスポンス

{ "messageId":"-KWbIsaqyS9k-K8nMhzH", "text":"こんにちは", "type":"text", "createdAt":14792020158, "createdBy":"-KWGbhXzcbPBBSPS3R_j", "createdUserName":"知話輪 太郎" }
フィールド名 内容
messageId メッセージID。
type メッセージタイプ。text:テキスト、image:画像
text メッセージ内容。typeがtextのときのみ設定されます。
createdAt メッセージ作成日時タイムスタンプ(UTCミリ秒)。
createdBy メッセージ作成ユーザのシステムID。
createdUserName メッセージ作成ユーザの名前。

メッセージ削除

メッセージ情報を削除します。

エンドポイント

DELETE /groups/{外部参照グループIDもしくはグループID}/messages/{メッセージID}

リクエスト

DELETE /groups/%2FInsuite%2Fgroup%2F2000001/messages/-KWbIsaqyS9k-K8nMhzH

レスポンス

なし

メッセージ付加情報変更

メッセージ付加情報を変更します。

エンドポイント

PUT /groups/{外部参照グループID、グループID、外部参照ユーザIDまたはユーザID}/messages/{メッセージID}/attachments

リクエスト

PUT /groups/%2FInsuite%2Fgroup%2F2000001/messages/-KWbIsaqyS9k-K8nMhzH/attachments { attachments: [ { "attachmentId":"u001", "viewType":"text", "title":"タイトル", "text":"本文", "actions":[ "buttonTitle":"ボタンタイトル", "authType":"sdb", "actionType":"get" ] } ] }
フィールド名 サブフィールド名 データ型 必須 内容
attachments - 配列 メッセージ付加情報。詳細は以下のattachmentsを参照。

attachments

フィールド名 サブフィールド名 データ型 必須 内容
attachmentId - 文字列 必須 付加情報を識別するためのユニークなID。
viewType - 文字列 付加情報の表示形式。text: テキスト。
title - 文字列 付加情報タイトル。
text - 文字列 付加情報テキスト本文。
textInTimeline - 文字列 タイムラインに表示するテキスト。指定がない場合は、本文の先頭を表示する。
lineBreakInTimeline - 文字列 改行の表示パターン。trim: タイムライン表示の際に改行を消す、none:改行はそのまま(デフォルト)
textType - 文字列 本文の形式。指定がない場合は改行のみBRタグに変換される。html:html形式、md:Markdown形式、none:改行のみBRタグに変換。
color - 文字列 付加情報のテーマカラー。16進数のカラーコードで指定。指定がない場合は色をつけない。
tagIcons - 配列 通知の種別を示すアイコン。
bell:、calendar:、check:、checkeddocument:、clock:、document:、graph:、location:、lock:、reply:、rss:
displaysCommentField - 文字列 yes: コメント入力欄を表示する。no: コメント入力欄を表示しない。
commentField - オブジェクト - コメント入力欄情報。
- placeholderText 文字列 - コメント入力欄が空の場合に表示する説明用のテキスト。デフォルトは「コメントを書く」。
- localizedPlaceholderText オブジェクト - "ISO言語コード": "当該言語のplaceholderText。マッチする言語がない場合はplaceholderTextを表示。"
actions - 配列 付加情報に表示するボタン。
- buttonTitle 文字列 選択肢ボタンのタイトル。タイムライン上のボタンは2つ目以降非表示。
- localizedTitle オブジェクト "ISO言語コード": "当該言語のボタンタイトル。マッチする言語がない場合はbuttonTitleを表示。"
- displaysIn 文字列 選択肢ボタンの表示条件。timeline: タイムラインに表示、detail: 詳細画面に表示、both: 両方(デフォルト)
- actionUrl 文字列 選択肢ボタンが押された時の遷移先URL。次のプレースホルダーが指定可能。
%groupId% : グループID (INSUITEから連携されたグループの場合は外部キーをセット)
%messageId% : メッセージID
%userId% : ユーザID (INSUITEから連携されたユーザの場合は外部キーをセット)
- authType 文字列 遷移先の認証種別。sdb: Sm@rtDB、insuite: INSUITE、none: なし
- actionType 文字列 選択肢ボタンを押下した時の動作種別。detail: 詳細画面を開く、inAppBrowser: アプリ内ブラウザで開く、externalApp: 外部アプリで開く、get: HTTP GETリクエストを送信、post: POSTリクエストを送信
- postBody オブジェクト 遷移先URLにPOSTする内容。postBodyContentTypeをform形式にする場合は、key, valueともにStringのオブジェクトのみ指定可。次のplaceholderが指定可能。%groupId% : グループID (INSUITEから連携されたグループの場合は外部キーをセット) %messageId% : メッセージID %userId% : ユーザID (INSUITEから連携されたユーザの場合は外部キーをセット)
- postBodyContentType 文字列 リクエストのpostBodyのコンテントタイプ。
json: JSON形式(デフォルト。ただし、authTypeがsdb, insuiteの場合はデフォルトはフォーム形式となる。なお、sdb, insuiteの場合も明示的にJSON形式を指定することも可能。)
form: フォーム形式

レスポンス

なし

ファイル取得

投稿されたファイルのコンテンツデータを取得します。

エンドポイント

GET /groups/{外部参照グループIDもしくはグループID}/files/{メッセージID}

リクエスト

GET /groups/%2FInsuite%2Fgroup%2F2000001/files/-KWbIsaqyS9k-K8nMhzH"

レスポンス

ファイルのバイナリデータを返します。

ファイル投稿

グループチャットに画像や動画等のファイルを投稿します。

エンドポイント

POST /groups/{外部参照グループIDもしくはグループID}/files

リクエスト

curl -X POST -H "X-Chiwawa-API-Token: eyJhbGciOiJSUzI1NiJ9" -F "file=@image.jpeg" -F "fileName=image.jpeg" "https://dreamarts.chiwawa.one/api/public/v1/groups/-KWaPuALgpl80GGa6pPs/files"
パラメータ名 データ型 必須 内容
file バイナリ 必須 multipart/form-dataを介して送信する画像ファイル内容。
fileName 文字列 必須 ファイル名。

レスポンス

{ "messageId":"-KWbIsaqyS9k-K8nMhzH" }
フィールド名内容
messageId登録されたメッセージのシステムID。

グループ所属ユーザ一覧取得

グループに所属するユーザ一覧を取得します。

エンドポイント

GET /groups/{外部参照グループIDもしくはグループID}/users

リクエスト

GET /groups/%2FInsuite%2Fgroup%2F2000001/users

レスポンス

{ "groupId":"-KWbIsaqyS9k-K8nMhzH", "users":[ { "userId":"-KWbIsaqyS9k-K8nMhzH", "outerId":"/Insuite/member/1000006", "userType":"user", "name":"山田 太郎", "localizedName":{ "ja":"山田 太郎", "en":"Taro Yamada" }, "position":"課長", "phoneNumber":"090-0123-4567", "internalPhoneNumber":"123", "mailAddress:":"t-yamada@dreamarts.co.jp" }, ... ] }
フィールド名 サブフィールド名 内容
groupId - グループID。
users - ユーザ情報リスト。
- userId ユーザID。
- outerId 外部参照ユーザID。
- userType ユーザタイプ。user:一般ユーザ、bot:ボットユーザ
- name ユーザ名。
- localizedName 言語別のユーザ名。
- position 役職名。
- phoneNumber 電話番号。
- internalPhoneNumber 内線番号。
- mailAddress メールアドレス。

グループ一覧取得

グループの一覧を取得します。

エンドポイント

GET /groups

リクエスト

GET /groups

レスポンス

{ "groups":[ { "groupId":"-KWaSYmjV0482W4yk8Bo", "outerId":"/Insuite/group/2000006", "groupType":"group", "name":"営業第2部", "localizedName":{ "ja":"営業第2部", "en":"Sales Division Ⅱ" }, "isAbolished":false } ] }
フィールド名 サブフィールド名 内容
groups - グループ情報リスト。
- groupId グループID。
- outerId 外部参照グループID
- groupType グループタイプ。group:Insuite組織グループ、custom:カスタムグループ、direct:ダイレクトグループ
- name グループ名称。
- localizedName 言語別のグループ名称。
- isAbolished 廃止組織フラグ。

グループ情報取得

グループ情報を取得します。

エンドポイント

GET /groups/{外部参照グループIDもしくはグループID}

リクエスト

GET /groups/%2FInsuite%2Fgroup%2F2000001

レスポンス

{ "groupId":"-KWaSYmjV0482W4yk8Bo", "outerId":"/Insuite/group/2000006", "groupType":"group", "is_abolished":false, "name":"営業第2部", "localizedName":{ "ja":"営業第2部", "en":"Sales Division Ⅱ" } }
フィールド名 内容
groupId グループID。
outerId 外部参照グループID。
groupType グループタイプ。group:Insuite組織グループ、custom:カスタムグループ、direct:ダイレクトグループ
name グループ名称。
localizedName 言語別のグループ名称。
is_abolished 廃止組織フラグ。

Webhook

知話輪内で発生した各種イベント情報をリアルタイムにWebhook URLへ通知します。通知はPOSTメソッドで行われます。
Webhook URLは知話輪管理画面で設定・確認できます。

リクエスト

イベント情報を含んだJSONデータとして送信されます。

レスポンス

リクエストに対しては速やかにHTTP 200 OKを返して下さい。リクエストが何らかの理由でエラーになったとしても再送信はされません。

リクエスト検証

各通知リクエストのHTTPヘッダー(X-Chiwawa-Webhook-Token)には検証用トークンがセットされます。
リクエストの送信元が知話輪であることを確認するために使用して下さい。
検証トークンは管理画面でWebhookを登録する際に発行されます。

イベントタイプ

メッセージイベント

メッセージがグループチャットに投稿された際に通知されます。

リクエスト

{ "type":"message", "message":{ "messageId":"-KYNLTQGqVzhXq20kgiQ", "groupId":"-KWG0zzmnrdk0Im4ohiC", "type":"text", "text":"こんにちは知話輪", "createdAt":1479202015812, "createdBy":"-KWCrXk3EIWM56E180Kn", "createdUserName":"山田 太郎" } }
フィールド名 サブフィールド名 内容
type - イベントタイプ。
message - メッセージイベントオブジェクト
- messageId メッセージID。
- groupId メッセージが投稿されたグループID。
- extGroupId メッセージが投稿されたグループの外部参照グループID。
- type メッセージタイプ。
- text メッセージ本文。
- createdAt メッセージ作成日時(UTCミリ秒)。
- createdBy メッセージ作成ユーザID。
- extCreatedBy メッセージ作成ユーザの外部参照ユーザID。
- createdUserName メッセージ作成ユーザ名。