LineWorksでBot経由でメッセージを送信するリクエストの例

前提

API2.0を使用
API用のクライアントとBotは発行してある
2023/1時点の手順
Google Chromeの拡張機能であるTalend API Testerを使ってリクエストを送信する

全体の流れ

APIを経由して、特定のアカウントにメッセージを送信するには以下の手順が大枠の流れとなる。

API2.0用のクライアントを発行する。権限、「bot」が必要
URL：https://developers.worksmobile.com/jp/console/openapi/v2/app/list/view
Botを登録する。
URL：https://developers.worksmobile.com/jp/console/bot/view
API2.0用のクライアントを使ってアクセストークンを取得する
取得したアクセストークンを使ってBotにリクエストを送信する

こんな流れになります。

そして、OAuthやJWTを知らない人にとってハードルが高いのがアクセストークンを取得する部分となりますから、そこを説明します。
正直、API仕様書だけでは簡単には分からないと思います。。。

前提に記載の通り、クライアントの発行とBotの登録は省略します。

メッセージを送る

早速手続きをしていきます。

アクセストークンの発行

まずは、Botを使用するためのアクセストークンの発行です。
一連の流れで説明します。

API用クライアントのService Accountの発行

今回はユーザ認証ではなく、サービスから認証を行う必要があります。
よって、使用するのはService Account認証 (JWT)です。

APIクライアントの管理画面から、Service Accountの発行操作をしてください。
特に何も注意点はなく、ボタンをポチポチしたら終わります。

Service Accountを発行したら、そのままPrivate Keyを発行します。
これを発行すると、テキストファイルがダウンロードされます。
これは認証に関する非常に重要なデータとなりますので、安全に秘匿して保管しましょう。

アクセストークンの発行

作成したService Accountを使ってアクセストークンを発行します。
リクエストはAPI仕様書にあるOAuthのエンドポイントのうち
https://auth.worksmobile.com/oauth2/v2.0/token
を使用します。

基本的なリクエスト形式はAPI仕様書を確認してください。
ここでは重要なポイントになるところだけを記載します。

clien_idとclient_secretについて
この項目はLineWorksの管理画面に記載されているものをそのままコピーして貼ってください。
assertionについて
JWTという形式で用意します。
JWTは形式の決まった文字列です。
私はこのサイトでJWTを手動生成することが多いです。
右側のDecodedに以下の情報を手入力します。

LineWorksでBot経由でメッセージを送信するリクエストの例 — JWT生成例

Service AccountとClient IDは管理コンソールから取得、Private Keyは先ほどダウンロードされたテキストファイルの中身を丸ごとコピーして貼り付けてください。
そうすると、左側のEncodedに文字列が表示されます。
これがassertionに設定する文字列です。

なお、トークン発行時に「error_description": "JWT is already expired."」という応答があった場合は、JWTのiatとexpが現在の時刻よりも古くなっていることが原因です。
iatを現在の時刻にして、expを3600秒後以内の時刻を設定してJWTを再度生成してください。
iatはUNIX秒という値で、この辺のサイトから現在時刻をUNIX秒で取得できます。その値を使ってください。
expは有効期限の値で同様にUNIX秒です。iatの値から+3600以内の値を自分で計算して入れてください。

ここで返ってきた応答のうち、access_tokenがメッセージ送信に必要なパスワードということになります。

TalendAPI Testerの例だと、こんな感じになります。

Bot経由でメッセージを送る

次は、発行したアクセストークンを使ってメッセージを送信します。
JSON形式のリクエストを送りますが、API仕様書のものをそのまま使うのが良いでしょう。
https://developers.worksmobile.com/jp/reference/bot-user-message-send?lang=ja
を参照してください。

リクエストの中で、注意が必要な部分のみ記載します。

https://www.worksapis.com/v1.0/bots/{botId}/users/{userId}/messagesについて
botIdは管理コンソールのBot情報からコピーしたBotID
userIdはLineWorksの中にあるランダムなユーザ識別子。これの値の取り方は別記事で説明します。
また、userIdにはメールアドレスも指定できます。メールアドレスの場合は相手のメールアドレスを入力してください。
なおメールアドレスはURLエンコードが必要です。
Authorizationについて
Bearerの後に設定するのは、先ほど取得したアクセストークンです。