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

概要

ユーザーのアクションによって実行するロジックをBot側でハンドリングできるようにするためにこのAPIを提供してます。

この Interactive API のエンドポイントは、Botユーザー作成後に登録することができ、Tocaroの要求事項を満たしているかどうか確認しています。

要求事項

https(SSL v3.0)
domainによるホスト解決(IPアドレスは不可)
SSL 証明書が自己証明書ではないこと
SSL 証明書の有効期限が期限内であること

メッセージ投稿のリクエスト

ユーザーがアクション可能なメッセージを投稿する場合は attachments のデータに必ず callback_id を指定する必要があります。このパラメータで指定された callback_id を元に Bot へリクエストを送信したときのハンドリングのキーになる値です。

{
  "group": "grxxxxxxxx",
  "text": "<@us11111111> Hello World!",
  "attachments": [
    {
      "title": "チケット",
      "text": "トライアル申込がありました。",
      "callback_id": "accept_tos",
      "fields": [
        {
          "title": "ID",
          "value": "1000",
          "short": true
        },
        {
          "title": "Name",
          "value": "Tocaro 太郎",
          "short": true
        }
      ],
      "actions": [
        {
          "name": "OK",
          "text": "はい",
          "type": "button",
          "value": "1000",
          "style": "primary"
        },
        {
          "name": "cancel",
          "text": "キャンセル",
          "type": "button",
          "value": "cancel",
          "style": "danger"
        }
      ]
    }
  ]
}

Field

#	Key	Value	説明
1	title	チケット	項目名
2	value	トライアル申し込みがありました。	項目区切りのメッセージ
3	short	false	true/false のいずれか、省略された場合は false

Action

#	Key	Value	説明	必須
1	name	ok	特定のアクションに名前を設定	◯
2	text	OK	ボタンに表示するテキスト
3	type	button	アクションの形式(buttonのみ)	◯
4	value	ok	コールバック関数に渡す値を設定
5	style	primary	default / primary / danger の3つ、省略された場合は default のスタイル

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

{
  "callback_id": "accept_tos",
  "value": "OK",
  "action": {
    "name": "OK",
    "value": "1000",
    "type": "button",
    "text": "はい",
    "style": "default"
  },
  "action_by": {
    "code": "usxxxxxxxxx",
    "name": "Tocaro 太郎"
  },
  "user": {
    "code": "uszzzzzzzz",
    "name": "Bot"
  },
  "group": {
    "code": "tkxxxxxxxx",
    "name": "xxx-xxxx"
  },
  "message": {
    "type": "interaction_message",
    "subtype": "interaction_message_posted",
    "ts": "1568014697969",
    "userName": "Bot",
    "botId": "usjiwvsv2u",
    "text": "トライアル申し込みがありました。",
    "attachments": [{
      "title": "チケット",
      "text": "トライアル申込がありました。",
      "callback_id": "accept_tos",
      "fields": [
        {
          "title": "ID",
          "value": "1000",
          "short": true
        },
        {
          "title": "Name",
          "value": "Tocaro 太郎",
          "short": true
        }
      ],
      "actions": [
        {
          "name": "OK",
          "text": "はい",
          "type": "button",
          "value": "1000",
          "style": "primary"
        },
        {
          "name": "cancel",
          "text": "キャンセル",
          "type": "button",
          "value": "cancel",
          "style": "danger"
        }
      ]
    }],
    "attached": true
  }
}

#	Key	説明
1	action	ユーザーによって実行されたアクションのデータ
2	action_by	アクションを実行したユーザーのデータ
3	message	メッセージデータ

SDK

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

https://registry.tocaro.im

レジストリの指定

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

SDK のインストール

$ npm install @tocaro/interactive-messages

サンプルコード

const http = require('http');
const express = require('express');
const { createMessageAdapter } = require('@tocaro/interactive-messages');

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

const interactions = createMessageAdapter(tocaroSigningSecret);

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

// Attach the adapter to the Express application as a middleware
app.use('/tocaro/actions', interactions.expressMiddleware());

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

// Tocaro interactive message handlers
interactions.action('accept_tos', (payload, respond) => {
  console.log('accept_tos::callback start');
  console.log(payload);
  const reply = payload.message;
  delete reply.attachments[0].actions;
  reply.text = "アクションを実行しました";
  return reply;
});

注意事項

現在、attachments に指定できる値は 1つのみです。

今後、複数指定することができるように対応する予定ですが、対応できるまではメッセージ投稿を複数に分割して対応してください。

Bot側で処理が正常に完了(HTTPのステータスコード 200)した場合はアクションのボタンを自動で削除しますが、すでに投稿されているメッセージデータはBot側で変更・削除することができません。

概要