Hiện tại chatwork là phần mềm quản lý trao đổi, quản lý công việc rất phổ biến trong các doanh nghiệp. Từ tính năng tiện lợi của chatwork　nên sẽ phát sinh vấn đề người dùng ở hệ thống của bạn muốn những thông tin update, notification của system　được thông báo qua chatwork. Trong trường hợp này , ta phải setting liên kết từ system đến chatwork thông qua API. Bài này mình sẽ chia sẻ những bước cơ bản để setting liên kết này .

1. Request sử dụng API chatWork API

※Nếu đã hoàn thành đăng kí API ChatWork rồi thì bỏ qua bước này 。

Hiện tại để sử dụng được API chatwork thì cần phải tiến hành request , ở link này http://developer.chatwork.com/ja/index.html Việc request này có thể máy 1~2 ngày 。

2. Get token API và room ID muốn liên kết

Get room ID

Mở room chat lên , copy giá trị kí tự ở sau rid trên URL của room chat https://www.chatwork.com/#!rid

Get API token

Mở menu ở góc trên bên phải 、Click vào 「動作設定」

Sau khi show dialog, chuyển sang tap 「API発行」。Nhập password, click vào hiển thị 「表示」 ※ Khi không đăng kí sử dụng API thì sẽ không hiển htij tab này 「API発行」

Copy token như hình bên dưới

Sau khi get xong giá trị token API, room_id có thể tiến hành thực thi request đến API thông qua end point

3.Về end point

API chatwork được setting dựa vào nguyên tắc của REST。Với mỗi resouce chat, task của REST sẽ có một URI duy nhất cố định( gọi là end point). Với mỗi endpoint này có thể tiến hành thao tác delete , post bằng cách gửi các parameter thông qua method HTTP GET hoặc POST, PUT, DELETE URI base của end point có format là https://api.chatwork.com/v2。 Sau v2 hãy thêm path của mỗi end point。(VD trong trường hợp path：/me -> https://api.chatwork.com/v2/me) khi version API tăng lên thì phải thay đổi phần verion /v2、API version cũ được maintain trong thời gian di chuyển sang version mới

Request

end point của API chatwork cần phải connect bằng https。 (sẽ lỗi trong trường hợp connect bằng http) Hơn nữa 、tất cả các request cần có token API.token API cần được set bởi key X-ChatWorkToken trong head request HTTP. Delete hoặc update resouce cần sử dụng method DELETE hoặc PUT nhưng vì client ko xử lý với các method này nên có thể chỉ định cả method muốn dùng trên URL request là ?method=PUT hoặc ?method=DELETE

*Điều quan trọng * Token API không có giới hạn thời gian (exprition date) mà có thể full access trong chức năng。Do đó hãy chú ý việc xử lý để có hay không public với người thứ 3 ( không liên quan)。Hơn nữa, API token không phải là query string của URL nên nhất định hãy gửi bằng request header HTTP

Response

Response có dạng JSON。 Status hiển thị fail hoặc success không bao gồm trong data json mà kết quả sẽ được sử dụng ở header response HTTP。 Bên dưới là ví dụ về thực thi của GET /my/status get số message chưa đọc

Header response HTTP

HTTP/1.1 200 OK
Content-Type: application/json

Body response HTTP

{
  "unread_room_num": 2,
  "mention_room_num": 1,
  "mytask_room_num": 3,
  "unread_num": 12,
  "mention_num": 1,
  "mytask_num": 8
}

Trong trường hợp lỗi, với code HTTP xử lý trả về message lỗi dạng json。Trong trường hợp API token bị sai thì sẽ bị lỗi như bên dưới

Header response HTTP

HTTP/1.1 401 Unauthorized
Content-Type: application/json

Body response HTTP

{
  "errors": ["Invalid API token"]
}

Trường hợp error , trả về message lỗi theo format array key

Về giới hạn số lượng sử dụng API

Số lượng request API có thể lên đến 100 lần trong vòng 5 phút。Thời gian reset hoặc số lần có thể call còn lại có thể tham khảo từ header response HTTP。 （số lượng dùng API sau này có thể thay đổi） Ví dụ header response HTTP

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 44
X-RateLimit-Reset: 1390941626

Với mỗi parametar thì sẽ hiển thị như bên dưới. X-RateLimit-Limit: max số lượng call X-RateLimit-Remaining: số lượng call còn lại X-RateLimit-Reset: thời gian được reset limit ở lần tiếp theo（Unix time）

Response API trả về mã lỗi 429 Too Many Requests trong trường hợp vượt qua số lượng giới hạn

Ví dụ header response HTTP

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1390941626

４.Source sample

Đây là ví dụ sử dụng API , gửi message đến roomchat bằng PHP 。

// chỉ định room ID muốn gửi mesage đến (※1)
$rid   = 123123;
//Chỉ định token của API  được sinh ra từ request  dùng API(※2)
$token = "asdasd";
//Message muốn gửi(※3)
$msg = <<<MSG
[To:111] 佐藤さん[To:222] 田中さん
ブログにコメントがつきました！
MSG;

header( "Content-type: text/html; charset=utf-8" );
$data = array(
  'body' => $msg
);

$opt = array(
  CURLOPT_URL => "https://api.chatwork.com/v1/rooms/{$rid}/messages",
  CURLOPT_HTTPHEADER => array( 'X-ChatWorkToken: ' . $token ),
  CURLOPT_RETURNTRANSFER => TRUE,
  CURLOPT_SSL_VERIFYPEER => FALSE,
  CURLOPT_POST => TRUE,
  CURLOPT_POSTFIELDS => http_build_query( $data, '', '&' )
);

$ch = curl_init();
curl_setopt_array( $ch, $opt );
$res = curl_exec( $ch );
curl_close( $ch );

//Trong trường hợp muốn xuất ra kết quả
echo "<pre>";
echo json_decode($res);

Nguồn tham khảo : http://www.wegirls.tech/entry/2016/11/04/184245 http://developer.chatwork.com/ja/index.html