はじめに
Chatwork API 利用規約Chatwork サービスサイト

エンドポイントについて

Chatwork APIはRESTの原則に基づいてAPI設計されています。RESTではチャット、タスクといったそれぞれのリソースに対して固有のURI（エンドポイントと呼ぶ）が与えられており、そのエンドポイントに対してGETやPOST、PUT、DELETEといったHTTPメソッドでパラメーターを送ることで、投稿や削除などリソースの操作を行います。

エンドポイントのベースURIは、https://api.chatwork.com/v2となっています。この後に各エンドポイントのパスを記述してください（例：/meの場合はhttps://api.chatwork.com/v2/me）。

今後APIのバージョンが上がった場合は/v2のバージョン部分が変更され、旧バージョンのAPIは一定の移行期間維持されます。

リクエスト

Chatwork APIのエンドポイントへは、必ずhttpsで接続する必要があります（httpでは接続エラーになります）。

また全てのリクエストには必ずAPIトークンを含める必要があり、APIトークンはHTTPリクエストヘッダーにx-chatworktokenというキーでセットする必要があります。

POSTメソッドやPUTメソッドを使用するエンドポイントのリクエストボディは、content-type: application/x-www-form-urlencodedである必要があります。

リソースの更新や削除にはPUTやDELETEメソッドを用いる必要がありますが、それらのメソッドに対応していないクライアントのため、URLのクエリストリングに?method=PUTおよび?method=DELETEと指定することで使用したいメソッドを明示することもできます。

❗️

重要

APIトークンは有効期限がなく、機能にフルアクセスが可能なものになっています。第三者へ開示しないよう取り扱いには十分ご注意ください。またAPIトークンはURLのクエリーストリングではなく必ずHTTPリクエストヘッダーで送信するようにしてください。

レスポンス

レスポンスはJSON形式となります。成功や失敗などを表すステータスコードはJSONデータには含まれていないため、成否判定にはHTTPレスポンスヘッダーを利用してください。

下記は自分の未読数などを取得するGET /my/statusの実行例です。

HTTPレスポンスヘッダー：

HTTP/2 200
content-type: application/json

HTTPレスポンスボディ：

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

エラーの場合は、対応するHTTPコードとエラーメッセージとをJSONで返します。下記はAPIトークンが間違っていた場合のエラー例です。

HTTPレスポンスヘッダー：

HTTP/2 401
content-type: application/json

HTTPレスポンスボディ：

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

エラーの場合は、errorsというキーに配列形式で、エラーメッセージが返却されます。

APIの利用回数制限について

APIのリクエスト数は5分あたり300回までとなります。残りコール可能な回数や、リセットされる時間はHTTPレスポンスヘッダーから参照できます（APIの利用回数は今後変更される可能性があります）。

HTTPレスポンスヘッダーの例：

HTTP/2 200
content-type: application/json
x-ratelimit-limit: 300
x-ratelimit-remaining: 244
x-ratelimit-reset: 1390941626

それぞれのパラメーターは、

  • x-ratelimit-limit：最大コール回数
  • x-ratelimit-remaining：残りコール回数
  • x-ratelimit-reset：次に制限がリセットされる時刻。Unix時間（秒）

を表しています。この制限を超えた場合、APIのレスポンス・ステータスコードが429 (Too Many Requests)となるエラーを返すようになります。

HTTPレスポンスヘッダーの例：

HTTP/2 429
content-type: application/json
x-ratelimit-limit: 300
x-ratelimit-remaining: 0
x-ratelimit-reset: 1390941626

チャットルーム単位のメッセージ投稿回数制限について

上記のAPI利用回数制限に加え、下記のエンドポイントについてはさらに10秒あたり10回までという回数制限があります（回数はそれぞれのエンドポイントの呼び出し回数の合算です）。

この制限を超えた場合、APIのレスポンス・ステータスコードが429 (Too Many Requests)となるエラーを下記のメッセージとともに返すようになります。

{
    "errors": ["Rate limit for message posting per room exceeded."]
}

このエラーが出た場合、10秒ほど待機していただいた後にリトライしていただくようお願いいたします。

Updated about 1 month ago