2018.08.24 Fri

チャットワークAPIを使ってメッセージの投稿やタスクの追加をしてみよう

今回はチャットワークAPI(ChatworkAPI)の使い方の解説と、サンプルプログラムを例にメッセージの投稿やタスクの追加をやってみようと思います。
当記事の対象者としましては以下のとおりです。

チャットワークAPIの使い方を知りたい方
チャットワークAPIを使用したサンプルプログラムを見たい方(PHP言語)
雨が降りそうな日に傘を忘れたくない方(理由は後ほど紹介いたします)

どうぞ最後までよろしくお願いいたします。

目次／このページでわかること

チャットワークAPIとは

チャットワークAPIは、外部のプログラムから簡単に使用できたり、チャットワークで発生したイベントを外部のプログラムに提供することができます。

簡単言うと、チャットワークAPIを利用すれば、自作のプログラムからチャットワークへメッセージを投稿したりタスクの追加をしたり、メッセージを表示したり、チャットワークの様々な操作を可能としてくれます。

チャットワークAPIを利用するためには

チャットワークAPIを利用するためには、APIの利用申請を行い、APIトークンを取得する必要があります。

APIの利用申請とAPIトークンの取得方法は、契約しているチャットワークのプランによっては取得方法が異なります。

フリープラン・パーソナルプランの場合は、チャットワーク画面右上の「利用者名」をクリックして表示されるメニューの「API設定」から、すぐに利用することができるようです。

ビジネスプラン・エンタープライズプランの場合は、組織管理者の申請が必要となるようです。

サンプルプログラム

早速ですが、チャットワークAPIを利用してPHP言語からメッセージの投稿やタスクの追加をしてみようと思います。

以前私が書いた『プログラムの自動実行にcronを使おうサンプルプログラム付きで設定も簡単』という記事にありますサンプルプログラムを改良して、天気予報情報をチャットワークにメッセージを投稿してみます。(※当記事では天気予報情報の取得方法については割愛いたします。以前書いた記事をご参考ください。)

実行ファイルが1つとクラスファイルが2つありますので、一旦ファイルの中身を紹介いたします。解説は次の章で行います。

実行ファイル – run.php

<?php
require_once "WeatherHacks.php";
require_once "Chatwork.php";

define("CHATWORK_ROOM_ID", ルームIDを記載する);
define("CHATWORK_TO_ID"  , タスクの担当者のIDを記載する);

$result = WeatherHacks::getWeather(450010);

if($result !== array()){
    $today = $result['today'];

    $body  = $today->date . " の天気は『" . $today->telop . "』です。\r\n";
    $body .= str_replace(["\r", "\n", " ", "　"], "", $result['discription']);

    Chatwork::postMessage(CHATWORK_ROOM_ID, $body);

    if (preg_match('/雨|曇/u', $today->telop)){
        Chatwork::postTask(CHATWORK_ROOM_ID, "雨が降りそうなので傘を忘れないこと。", time(), array(CHATWORK_TO_ID));
    }
}

天気予報情報を取得するためのクラス – WeatherHacks.php

<?php
class WeatherHacks{
    /**
     * 天気予報情報を返す
     * @param integer $city_id 地域ID
     * @return array $result 取得失敗時は空の配列を返す
     */
    public static function getWeather($city_id){
        $result = array();
        if(false !== $json = self::getWeatherHacks($city_id)){
            $result['title']       = $json->title;
            $result['discription'] = $json->description->text;
            $result['datetime']    = $json->publicTime;
            $result['today']       = $json->forecasts[0];
            $result['yesterday']   = $json->forecasts[1];
        }
        return $result;
    }

    /**
     * 天気予報情報をWeatherHacksより取得する
     * @param integer $city_id 地域ID
     * @return mixed 天気予報の情報をJSONで返す。取得できない場合はFALSEを返す。
     */
    private static function getWeatherHacks($city_id) {
        $url = "http://weather.livedoor.com/forecast/webservice/json/v1?city={$city_id}";
        if (false === $data = @file_get_contents($url)) return false;
        return json_decode($data);
    }
}

チャットワークAPIを利用するためのクラス – Chatwork.php

<?php
<?php
define("API_URL", "https://api.chatwork.com");
define("CHATWORK_TOKEN", "取得したチャットワークAPIトークンを記入する");

class Chatwork{
    /**
     * ChatWorkにメッセージを投稿する
     * @param integer $room_id ChatWorkのルームID
     * @param string $body 投稿する文字列
     * @return array $result 結果を返す
     */
    public static function postMessage($room_id, $body){
        $headers = [ "X-ChatWorkToken: " . CHATWORK_TOKEN ];
        $option = [ 'body' => $body ];
        $curl = curl_init(API_URL . "/v2/rooms/${room_id}/messages" );
        curl_setopt($curl, CURLOPT_POST, true);
        curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($option));
        curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        $result = curl_exec($curl);
        curl_close($curl);
        return $result;
    }

    /**
     * ChatWorkにタスクを登録する
     * @param integer $room_id ChatWorkのルームID
     * @param string $body 投稿する文字列
     * @param integer $limit タスクの期限(UNIX TIME)
     * @param array $to_ids タスクの担当者
     * @return array $result 結果を返す
     */
    public static function postTask($room_id, $body, $limit, $to_ids){
        $headers = [ "X-ChatWorkToken: " . CHATWORK_TOKEN ];
        $option = [
            'body' => $body,
            'limit' => $limit,
            'to_ids' => implode(",", $to_ids)
        ];
        $curl = curl_init(API_URL . "/v2/rooms/${room_id}/tasks" );
        curl_setopt($curl, CURLOPT_POST, true);
        curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($option));
        curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        $result = curl_exec($curl);
        curl_close($curl);
        return $result;
    }
}

サンプルプログラムの解説

今回は3つのファイルを準備しました。それぞれの役割は以下の通りです。

実行ファイル – run.php
天気予報情報を取得するためのクラス – WeatherHacks.php
チャットワークAPIを利用するためのクラス – Chatwork.php

3つのプログラムを使用される際は、PHPコマンドから run.php を実行してください。

php run.php

cronで定期的に自動投稿したい場合は以下のようにcrontabで設定してください。以下の設定で朝7時00分に実行されます。

0 7 * * * /home/sv01/run.php

設定方法については、以前私が書いた『プログラムの自動実行にcronを使おうサンプルプログラム付きで設定も簡単』をご参照ください。

実際に投稿されたメッセージとタスクは以下のとおりです。

どうですか、毎朝これが届けば雨が降りそうな日に傘を忘れなくなりますね! (今年は台風多いですね…。)

サンプルプログラムの解説(メッセージ投稿について)

メッセージを投稿する際に使用するAPIのエンドポイントは、

/rooms/{room_id}/messages

になります。こちらのエンドポイントにPOSTリクエストをしてあげればメッセージの投稿ができます。エンドポイントの中にある {room_id}は、投稿先のルームIDとなります。

チャットワーク各ルームをブラウザで表示すると、
URLが https://www.chatwork.com/#!rid******** となります。
ridより後の数字がroom_idとなりますので、そちらを使用してください。

では、そのエンドポイントをプログラム的に使用している箇所はどこになるかといいますと、run.phpの13-16行目、Chatwork.phpの7-24行目になります。

run.phpの13-16行目は実際にチャットワークへ投稿する文章を作成し変数$body へ格納、それからChatworkクラスのpostMessage関数を使用している箇所となります。

    $body  = $today->date . " の天気は『" . $today->telop . "』です。\r\n";
    $body .= str_replace(["\r", "\n", " ", "　"], "", $result['discription']);
 
    Chatwork::postMessage(CHATWORK_ROOM_ID, $body);

Chatwork.phpの7-24行目は実際にメッセージを投稿する処理になります。メッセージを投稿するエンドポイントをcurlでPOSTリクエストをするように設定しております。受け取ったルームID($room_id)とメッセージ($body)をもとに、該当するルームへメッセージを投稿します。

    /**
     * ChatWorkにメッセージを投稿する
     * @param integer $room_id ChatWorkのルームID
     * @param string $body 投稿する文字列
     * @return array $result 結果を返す
     */
    public static function postMessage($room_id, $body){
        $headers = [ "X-ChatWorkToken: " . CHATWORK_TOKEN ];
        $option = [ 'body' => $body ];
        $curl = curl_init(API_URL . "/v2/rooms/${room_id}/messages" );
        curl_setopt($curl, CURLOPT_POST, true);
        curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($option));
        curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        $result = curl_exec($curl);
        curl_close($curl);
        return $result;
    }

サンプルプログラムの解説(タスク追加について)

メッセージを投稿する際に使用するAPIのエンドポイントは、

/rooms/{room_id}/tasks

になります。こちらのエンドポイントにPOSTリクエストをしてあげればタスクの追加ができます。エンドポイントの中にある {room_id}は、メッセージの投稿と同じように投稿先のルームIDとなります。

では、そのエンドポイントをプログラム的に使用している箇所はどこになるかといいますと、run.phpの18-20行目、Chatwork.phpの26-49行目になります。

run.phpの18-20行目は、雨が降りそうな日に傘を持っていくようにというタスクを追加するようにしております。今日の天気に「雨」もしくは「曇」といった表現がある場合に作動します。

    if (preg_match('/雨|曇/u', $today->telop)){
        Chatwork::postTask(CHATWORK_ROOM_ID, "雨が降りそうなので傘を忘れないこと。", time(), array(CHATWORK_TO_ID));
    }

Chatwork.phpの26-49行目は実際にタスクを追加する処理になります。タスクを追加するエンドポイントをcurlでPOSTリクエストをするように設定しております。受け取ったルームID($room_id)とメッセージ($body)とタスクの期限($limit)とタスクの担当者($to_ids)をもとに、該当するルームへ担当者へタスクの追加をします。

    /**
     * ChatWorkにタスクを登録する
     * @param integer $room_id ChatWorkのルームID
     * @param string $body 投稿する文字列
     * @param integer $limit タスクの期限(UNIX TIME)
     * @param array $to_ids タスクの担当者
     * @return array $result 結果を返す
     */
    public static function postTask($room_id, $body, $limit, $to_ids){
        $headers = [ "X-ChatWorkToken: " . CHATWORK_TOKEN ];
        $option = [
            'body' => $body,
            'limit' => $limit,
            'to_ids' => implode(",", $to_ids)
        ];
        $curl = curl_init(API_URL . "/v2/rooms/${room_id}/tasks" );
        curl_setopt($curl, CURLOPT_POST, true);
        curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($option));
        curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        $result = curl_exec($curl);
        curl_close($curl);
        return $result;
    }