コメントAPI

kintone ではレコードに対してコメントを投稿できますが、REST API を使えば、プログラムからコメントの追加・取得・削除を行うことが可能です。

例えば、レコードの更新時に自動でコメントを投稿したり、特定のユーザーにメンション付きのコメントを送ったり、コメント履歴を外部システムに連携したりといった活用ができます。

この記事では、コメント API の基本的な使い方から、メンション機能の活用、全件取得のパターンまで解説します。

コメント API の概要

コメント API は、以下の 3 つのエンドポイントで構成されています。

コメントの追加

kintone から利用する場合

/**
 * レコードにコメントを追加する
 * @param { Object } params
 * @param { string | number } params.app - アプリID
 * @param { string | number } params.record - レコードID
 * @param { Object } params.comment - コメント情報
 * @param { string } params.comment.text - コメント本文
 * @param { Object[] } [params.comment.mentions] - メンション情報
 * @returns { Promise<{ id: string }> } 追加されたコメントID
 */
const addComment = (params) => {
  return kintone.api(kintone.api.url('/k/v1/record/comment.json', true), 'POST', params);
};

シンプルなコメントの投稿

(() => {
  'use strict';

  kintone.events.on(['app.record.detail.show'], async (event) => {
    const appId = kintone.app.getId();
    const recordId = kintone.app.record.getId();

    // シンプルなテキストコメントを追加
    const result = await addComment({
      app: appId,
      record: recordId,
      comment: {
        text: 'このレコードの確認が完了しました。',
      },
    });

    console.log(`コメントID: ${result.id} を追加しました`);
    return event;
  });
})();

メンション付きコメントの投稿

特定のユーザーやグループにメンションを送ることで、コメントの通知を届けることができます。

(() => {
  'use strict';

  kintone.events.on(['app.record.detail.process.proceed'], async (event) => {
    const appId = kintone.app.getId();
    const recordId = kintone.app.record.getId();
    const action = event.action.value;

    if (action === '承認依頼') {
      await addComment({
        app: appId,
        record: recordId,
        comment: {
          text: '承認をお願いいたします。内容をご確認ください。',
          mentions: [
            {
              code: 'approver-user',      // ユーザーのログイン名
              type: 'USER',
            },
            {
              code: '総務部',              // 組織名
              type: 'ORGANIZATION',
            },
            {
              code: '承認者グループ',      // グループ名
              type: 'GROUP',
            },
          ],
        },
      });
    }

    return event;
  });
})();

メンションの type には以下の値を指定できます。

コメントの取得

kintone から利用する場合

/**
 * レコードのコメント一覧を取得する
 * @param { Object } params
 * @param { string | number } params.app - アプリID
 * @param { string | number } params.record - レコードID
 * @param { 'asc' | 'desc' } [params.order] - ソート順（デフォルト: desc）
 * @param { number } [params.offset] - 取得開始位置
 * @param { number } [params.limit] - 取得件数（最大10、デフォルト10）
 * @returns { Promise<{ comments: Object[]; older: boolean; newer: boolean }> }
 */
const getComments = (params) => {
  return kintone.api(kintone.api.url('/k/v1/record/comments.json', true), 'GET', params);
};

基本的な取得パターン

(() => {
  'use strict';

  kintone.events.on(['app.record.detail.show'], async (event) => {
    const appId = kintone.app.getId();
    const recordId = kintone.app.record.getId();

    // 最新の 10 件を取得
    const result = await getComments({
      app: appId,
      record: recordId,
      order: 'desc',
    });

    for (const comment of result.comments) {
      console.log(`${comment.createdAt} - ${comment.creator.name}: ${comment.text}`);
    }

    return event;
  });
})();

レスポンスの構造

コメント取得のレスポンスは以下のような構造を持っています。

{
  "comments": [
    {
      "id": "3",
      "text": "承認いたしました。",
      "createdAt": "2026-02-24T10:30:00Z",
      "creator": {
        "code": "user1",
        "name": "田中 太郎"
      },
      "mentions": [
        {
          "code": "user2",
          "type": "USER"
        }
      ]
    }
  ],
  "older": true,
  "newer": false
}

全件取得のパターン

コメントは 1 回のリクエストで最大 10 件までしか取得できないため、全件取得するにはページング処理が必要です。

/**
 * 指定レコードの全コメントを取得する
 * @param { Object } params
 * @param { string | number } params.app - アプリID
 * @param { string | number } params.record - レコードID
 * @returns { Promise<Object[]> } 全コメント
 */
const getAllComments = async (params) => {
  const { app, record } = params;
  const allComments = [];
  let offset = 0;

  while (true) {
    const result = await kintone.api(
      kintone.api.url('/k/v1/record/comments.json', true),
      'GET',
      { app, record, order: 'asc', offset, limit: 10 }
    );
    allComments.push(...result.comments);

    if (!result.older) {
      break;
    }
    offset += 10;
  }

  return allComments;
};

コメントの削除

kintone から利用する場合

/**
 * コメントを削除する
 * @param { Object } params
 * @param { string | number } params.app - アプリID
 * @param { string | number } params.record - レコードID
 * @param { string | number } params.comment - コメントID
 * @returns { Promise<{}> }
 */
const deleteComment = (params) => {
  return kintone.api(kintone.api.url('/k/v1/record/comment.json', true), 'DELETE', params);
};

使用例

(() => {
  'use strict';

  kintone.events.on(['app.record.detail.show'], async (event) => {
    const appId = kintone.app.getId();
    const recordId = kintone.app.record.getId();
    const commentId = 5; // 削除するコメントのID

    try {
      await deleteComment({
        app: appId,
        record: recordId,
        comment: commentId,
      });
      console.log('コメントを削除しました');
    } catch (error) {
      console.error('コメントの削除に失敗しました', error);
    }

    return event;
  });
})();

kintone 以外から利用する場合

Node.js を使用した場合

const BASE_URL = 'https://__your_subdomain__.cybozu.com';
const API_TOKEN = 'YOUR_API_TOKEN';

// コメントを追加する
const addComment = async (app, record, text, mentions = []) => {
  const response = await fetch(`${BASE_URL}/k/v1/record/comment.json`, {
    method: 'POST',
    headers: {
      'X-Cybozu-API-Token': API_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      app,
      record,
      comment: { text, mentions },
    }),
  });
  return response.json();
};

// コメント一覧を取得する
const getComments = async (app, record, order = 'desc', offset = 0) => {
  const params = new URLSearchParams({ app, record, order, offset, limit: 10 });
  const response = await fetch(`${BASE_URL}/k/v1/record/comments.json?${params}`, {
    method: 'GET',
    headers: { 'X-Cybozu-API-Token': API_TOKEN },
  });
  return response.json();
};

// コメントを削除する
const deleteComment = async (app, record, comment) => {
  const response = await fetch(`${BASE_URL}/k/v1/record/comment.json`, {
    method: 'DELETE',
    headers: {
      'X-Cybozu-API-Token': API_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ app, record, comment }),
  });
  return response.json();
};

実践パターン：レコード更新時に自動コメント

レコードの保存時に自動でコメントを投稿する実装例です。変更内容を記録する用途に活用できます。

(() => {
  'use strict';

  const events = ['app.record.edit.submit.success'];

  kintone.events.on(events, async (event) => {
    const appId = kintone.app.getId();
    const recordId = event.recordId;
    const loginUser = kintone.getLoginUser();

    await kintone.api(kintone.api.url('/k/v1/record/comment.json', true), 'POST', {
      app: appId,
      record: recordId,
      comment: {
        text: `${loginUser.name} がレコードを更新しました。`,
      },
    });

    return event;
  });
})();

まとめ

• コメント API は /k/v1/record/comment.json（追加・削除）と /k/v1/record/comments.json（取得）の 2 つのエンドポイントで構成される
• コメントの追加時に mentions を指定すると、対象ユーザー・組織・グループに kintone 通知が届く
• コメントの取得は 1 リクエストあたり最大 10 件 のため、全件取得にはページング処理が必要
• コメントの削除は 投稿したユーザー自身 またはアプリ管理者のみが実行できる
• プロセス管理イベントと組み合わせることで、ステータス変更時の自動コメント投稿が実現できる

練習問題