GoHighLevelのタスクをAPIで更新すると欄が消える——全項目を送り、完了は値で読む

コンタクトにぶら下がるタスクは、「次に誰が何をするか」を残す場所です。Claude Codeに、担当の割り当てや期限の変更をまとめて任せたくなります。

私たちは、あるコンタクトのタスクを整理したときに、2つのことを学びました。更新では送らなかった欄が消えること(私たちが試した旧版での経験で、現在の公式仕様と同じとは限りません)、そして完了を目で読むと間違えることです。

目次

タスクの口は、コンタクトの下にある

タスクは、コンタクトごとに持ちます。口は次のとおりです。

  • 一覧:コンタクトのタスクを配列で返す
  • 作成:タイトル、本文、期限、完了の状態を渡す
  • 更新:コンタクトとタスクの両方のIDを指定する

期限は、ISO 8601の形で渡します。日本時間の朝8時なら、+09:00 を付けて書きます。一方、読み出すと、期限は協定世界時(末尾が Z)で返ります。書いた時刻と読み出した時刻が9時間ずれて見えるのは、仕様どおりであり、日付をまたぐ場合(日付が前後して見える)も同じ時刻として確かめます。

旧版での経験:更新でタイトルを求められ、送らなかった欄が消えた

更新で気をつけたいのは、旧版の経験で見られた、タイトルの扱いと部分更新の挙動です。対象APIバージョンや実際の送信JSON、応答・再取得記録に照らすと、旧版の経験ではタイトル必須による拒否が見られました(※公式の現在ページであるv3ではtitleのrequired表示が見えない場合もあり、旧版の経験を現在の共通仕様とすることは避ける必要があります)。また、送らなかった欄が上書きされて消える挙動についても、旧版の経験では見られましたが現在の公式仕様と同じとは限らないため公式の現行ページで確かめる必要があります。

たとえば担当だけを変えたいとき、送信内容やAPIバージョンによっては拒否される場合や、本文と期限が上書きされて消える場合があります。

更新前後の値を比べる表の例

更新を行う前と後で、どのような値の動きになるかを事前に把握しておくことが大切です。次のような構造を意識してスクリプトや指示を組みます。

  • 更新前:元のタイトル、本文、期限、完了、担当がすべて揃っている状態
  • 部分更新で起こりうる失敗例(旧版の経験):担当だけを送った場合、タイトルや期限などの情報が消えて空になる状態
  • 正しい更新の例:読み出したすべての値(読み取り専用で送れない項目を除く)を保持したまま、変えたい欄だけを差し替えて送る状態

このように日本語の名前だけでカスタムフィールドを作ると、2本目から400で止まるような細かな仕様と同様に、タスク更新時も全項目を意識して扱う必要があります。

直し方は、読み出した値を持ったまま送ること

手順は、次のとおりです。

  • 対象のタスクを読み出す
  • 変えたい欄だけを書き換え、残りは読み出した値のまま持つ
  • 全部の欄(読み取り専用で送れない項目を除く)を入れて更新を送る
  • もう一度読み出して、変えた欄と変えていない欄の両方を確かめる

私たちは、この手順を小さなスクリプトにしました。実行の前に、対象と書き換える内容を表示するだけの確認用の実行(ドライラン)を入れてあります。本番の実行は、確認を見たあとに行います。

完了の欄は、明示しない限り現状のまま

もう一つ決めたのは、完了の状態を勝手に変えないことです。担当や期限を変えるだけのつもりで、完了の欄を空で送ると、完了済みのタスクが未完了に戻ることがあります。

読み出した値をそのまま送り返す作りにしておくことで事故を防ぎやすくなりますが、他処理の同時実行や更新競合がある場合は、再取得や競合確認を行う必要があります。完了にしたいタスク、未完了に戻したいタスクは、IDを指定して別に扱います。

Claude Codeへ最初に渡す指示の例

Claude Codeにタスクの更新を任せる際は、事前の指示にルールを明確に盛り込みます。たとえば、次のような口調や制約をプロンプトに含めます。

  • 「タスクを更新する際は、事前に対象のタスクを読み出し、全項目を維持した状態で送信してください。」
  • 「旧版の仕様では部分更新ができないため、送らなかった欄が消えないように読み出した値を持ったまま送るスクリプトを使用してください。」
  • 「完了状態については画面の目視ではなく、APIで返る値に基づいて正しく判断し報告してください。」

こうした事前の指示を徹底することで、AIの引き継ぎをGHLのノートに残す。カードIDが実はコンタクトIDだった罠のような思い違いを防ぎ、正確な自動化を進めることができます。

期限の時刻の書き方の例(日本時間と協定世界時)

期限を扱う際には、タイムゾーンの変換や表記の仕方に注意が必要です。プログラムから送信する場合と、APIから受け取る場合で見た目が変わるため、次の例を基準にします。

  • 日本時間での指定例:ISO 8601形式で、朝8時の場合は `+09:00` を付与して送信します。
  • 協定世界時での返却例:APIから読み出すと、末尾が `Z` の形式で返ります。
  • 見え方の違い:書いた時刻と読み出した時刻に9時間のズレが生じますが、これは仕様通りでありデータ自体は正しく保持されています。日付をまたぐ場合(日付が前後して見える)も同じ時刻として確かめます。

完了は、画面のチェックではなく値で読む

私たちは、一度失敗しています。タスクの一覧画面を見て、「完了にしたはずのものが、まだ未完了に見える」と報告したのです。

あとで更新後の値を読み出すと、完了の欄は正しく完了になっていました。画面のチェックのアイコンで、完了と未完了を読み違えていたのです。

この経験から、ルールを1つ決めました。タスクの完了を報告するときは、毎回APIの値で確かめる、というルールです。画面は、人が全体を眺めるのには向いていますが、状態を数える根拠にはなりません。Claude Codeにも、この点を最初の指示に書いておきます。

よくある質問(画面で未完了に見えるとき)

タスクの更新に関して、現場で迷いやすいポイントを整理します。

  • Q. 画面上で完了になっているのに未完了に見えるのはなぜですか?
  • A. アイコンの読み違えや表示の反映ラグが考えられます。APIから値を取得して確かめてください。
  • Q. 担当者だけを変更したいのに他の項目が消えてしまうのはなぜですか?
  • A. 私たちが試した旧版の経験では、部分更新ができないことで送らなかった欄が空になる現象が見られましたが、現在の公式仕様と同じとは限らないため公式の現行ページで確かめてください。読み出した値を持ったまま送信してください。
  • Q. 期限の時間が9時間ずれて見えるのは不具合ですか?
  • A. 協定世界時(Z)で返る仕様によるもので、日本時間で正しく送信されていれば問題ありません。

連続して更新するときは間を空ける

複数のタスクを続けて更新するときは、1件ごとに少し間を空けます。私たちは、1件ごとに0.2秒待つようにしましたが、他処理の同時実行や更新競合がある場合はこれだけでは防げないため、指数バックオフや再取得、競合確認を行う必要があります。

担当の割り当ては、2つの流儀を分ける

担当者を割り当てるときは、2つの流儀を分けて使います。

  • 担当が空のタスクにだけ割り当てる:すでに担当がいるものは触らない
  • 全部のタスクの担当を上書きする:引き継ぎのときだけ使う

私たちが最初に使うのは、前者です。ある日のタスク整理では、担当が空のタスクだけを運用者に割り当て、骨子を作るタスクの期限を月末に動かしました。実行の前に、対象を表示するだけの確認用の実行で、どのタスクが変わるかを見てから、本番を流しました。

タスクの口は、自作のMCPには入れなかった

私たちは、コンタクト、ノート、クーポンを扱う自作のMCPを持っています。ただ、当時版の自作MCPではタスクの作成や更新を含めませんでした。タスクは、ここまで書いたとおりに、全項目を送る作法が要るので、専用のスクリプトで扱うほうが事故が少ないと考えたからです。

MCPの登録が外れていても、このスクリプトは単独で動きます。道具の数を増やすより、壊れにくい道具を1つ持つ、という選び方です。

更新のあとに、3つを突き合わせる

更新を終えたら、もう一度タスクを読み出して、次の3つを更新前と突き合わせます。

  • 担当:割り当てたとおりになっているか
  • 完了:触っていないタスクの状態が変わっていないか
  • 期限:書いた時刻が、協定世界時で読み出したときに9時間ずれて見えるだけか。日付をまたぐ場合(日付が前後して見える)も同じ時刻として確かめる。

3つ目は、ずれて見えるだけで、正しいのが普通です。慣れないうちは、「期限が壊れた」と思いがちなので、前もって知っておきます。

次に読む

タスクが「次の一手」を残す場所だとすると、「ここまでやった」を残す場所はノートです。AIの引き継ぎをノートに書くときの注意は、ノートの引き継ぎの記事にまとめました。

この記事の段取りを、自分の会社で回せるようにしたい方へ

音声メモから投稿文を作る、地図検索とSNSを整える、問い合わせをフォームで受けて一覧で管理する。集客から受付までの「小さな営業導線」を、AIを使って自分の手で作る実務講座を開いています。オンラインで30分の無料個別相談から始められます。

👉 AI活用講座のページへ

運営: 株式会社トレジャーハンティング

無料メール講座「AI社長のお困りごと相談」(全7回)

「AIに、会社の仕事をどこまで任せられるのか」を、全7回に分けてお送りしています。記事の続きの話は、ここでお届けします。

ご登録はメールアドレスだけ。いつでも解除できます。売り込みのメールは送りません。

中山博之(ニタ)/ニタ@AIと会社を経営する55歳
会計ソフト会社に29年、社長業は19年目。中小企業の現場で生まれた仕事の仕組みを、AI時代向けに作り直しています。

GoHighLevelを、日本語の道具箱つきで始める。

このページ経由で14日間の無料トライアルを始めた方には、日本語の使い方マニュアル・すぐ使えるテンプレート・個別のZoom相談まで、3つの特典をまとめてお渡ししています。

  • 特典1: 日本語スタートマニュアル(PDF)
    最初のつまずきをゼロにする初期設定ガイド
  • 特典2: すぐ使える日本語テンプレート
    インポートするだけで日本語仕様の画面になるひな形
  • 特典3: 個別20分のZoom相談
    自分のビジネスでどう使うか、直接相談できる時間

このページには、アフィリエイトリンク(紹介リンク)が含まれます。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

(株)トレジャーハンティング、アイ・シー・エス通商(株)、(株)ヒミコ代表取締役。15年以上、自社のネット集客を手掛けてきた実績をもとに、ネット集客コンサルティングを行ってきた。現在、GoHighLevelを使ったGoogleマップレビュー代行を中心に活動している。

目次