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

概要

Botを実現するためには投稿されたメッセージ内にキーワードが含まれているかどうか判断し、Botによる自動化タスクを開始することから始まります。これを実現するためにTocaroへ投稿されたメッセージデータを外部のサーバに転送できるAPIを提供しています。

このEventAPIのエンドポイントは、Botユーザー作成後に登録することができ、Tocaroの要求事項を満たしているかどうか確認しています。この検証リクエストが成功しない限り、メッセージデータは外部へ送信されません。

要求事項

Tocaro から外部へメッセージデータを送信するために以下の要件を満たす必要があります。

https(SSL v3.0)
domainによるホスト解決(IPアドレスは不可)
SSL 証明書が自己証明書ではないこと
SSL 証明書の有効期限が期限内であること
Tocaro が発行した Signing Secret のキーが一致していること

エンドポイントの検証シーケンス

エンドポイントを検証するときのシーケンスは以下の通りです。

blobid0.dat

SSL & URL Verification Handshake

エンドポイントのホストに対して POST /events/url_verification を application/json で送信します。

{
    "token": "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz(Tocaroが発行した Signing Secret)",
    "challenge": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx(ランダムな文字列をTocaro側で発行)",
    "type": "url_verification"
}

ThirdParty 側で Token の検証を実施し、以下のレスポンスを返してください。

HTTP 200 OK
Content-Type: application/json
{
  "challenge": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx(リクエストで送信されてきたランダム文字列)"
}

Events 一覧

現時点で対応している Event はメッセージ投稿のみです。順次、外部に送信できる Event を追加していく予定です。

#	Event Type	Summary
1	message.posted	対象のグループにメッセージが投稿されたとき

エンドポイントへのリクエスト

次のリクエストを登録されたエンドポイントに送信します。

共通

どの Event Type でも共通のJSONフォーマットは次の通りです。

{
    "token": "API Token",         // API トークンキー
    "event": {
        "user": "usxxxxxx",       // Event を発生させたユーザーコード
        "type": "message.posted", // Events 一覧に記載した Type
        "item": {
            "type": "message",    // Item オブジェクトの Type を表現
            // ここは Event Type 毎に変更
        }
    },
    "type": "event_callback",     // Fixed Value
    "authedUser": "usxxxxxx",    // この API トークンキーを発行したユーザーコード
    "eventTime": 1542001689000   // Event が発生した時間(UnixTime:ミリ秒) 
}

※ item 部分は、Event Type 毎にフォーマットを変更する。基本的なJSONフォーマットは公開APIと同様の構造とする。

message.posted イベントのリクエスト

"item": {
    "type": "message",
    "ts": 1531111716092, // メッセージの投稿日時（ミリ秒）
    "text": "@Tocaro 太郎: これをお願いします。", // メッセージの内容
    "mentions": [ // mention のユーザーコード
        "usxxxxxxx"
    ],
    "group": "grxxxxxx", // メッセージが投稿されたグループコード
    "user": "usxxxxxx" // メッセージを投稿したユーザーコード
}

SDK

エンドポイントの検証やイベントデータのハンドリングを簡単に実現できるように Node.js の SDK を以下のプライベートリポジトリで公開しています。

https://registry.tocaro.im

レジストリの指定

$ npm config set registry https://registry.tocaro.im

SDK のインストール

$ npm install @tocaro/events-api

URL Verification Handshake

開発環境では ngrok などを使って、ドメイン解決とSSL対応を実現してください。

$ npx tocaro-verify -s xxxxxxxxxxxxxx

サンプルコード

// Load environment variables from `.env` file (optional)
require('dotenv').config();

const tocaroEventsApi = require('@tocaro/events-api');
const http = require('http');
const express = require('express');

const tocaroSigningSecret = process.env.TOCARO_SIGNING_SECRET;
if (!tocaroSigningSecret) {
  throw new Error('A Tocaro signing secret are required to run this app.');
}

const tocaroEvents = tocaroEventsApi.createEventAdapter(tocaroSigningSecret, {
  includeBody: true
});

// Initialize an Express application
const app = express();

app.use('/tocaro/events', tocaroEvents.expressMiddleware());

tocaroEvents.on('message_posted', (message, body) => {
  console.log('------ message_posted handling');
  console.log(message);
  console.log(body);
});

tocaroEvents.on('error', (error) => {
  if (error.code === 'SIGNATURE_VERIFICATION_FAILURE') {
    console.error(`An unverified request was sent to the Slack events Request URL. Request body: \
${JSON.stringify(error.body)}`);
  } else {
    console.error(`An error occurred while handling a Slack event: ${error.message}`);
  }
});

// Start the express application
const port = process.env.PORT || 3001;
http.createServer(app).listen(port, () => {
  console.log(`server listening on port ${port}`);
});

注意事項

Evnet の送信に失敗した場合は一定の間隔(60s)で最大5回リトライを実施し、リトライの情報を HTTP の header(x-tocaro-retry) に指定します。

5回失敗した場合は対象のエンドポイントを無効化し、ユーザーによる再登録を実施しない限りは有効化されません。

概要