ワークフローはAPIで読めるのが6項目だけ。疎通テストと空メールの測り方

GoHighLevelのワークフローを、Claude Codeから組み立てられるか。結論は、半分です。APIで読めるのは一覧と状態までで、トリガーも、アクションも、読めません。作成や公開は、画面でしかできません。

この記事では、その制約を前提に、動いたかどうかを確かめる方法をお伝えします。

APIで読めるのは、6項目だけ

ワークフローの一覧は、取得できます。ただ、返ってくる項目は次の6つだけです。

• ID
• 名前
• 状態（下書きか公開か）
• 版
• 作成日時
• 更新日時

トリガーの条件も、各ステップの設定も、有効か無効かも、返りません。それらは、ビルダーの画面でしか見えません。

つまり、「ワークフローが完成しているか」は、APIでは途中までしか確かめられません。状態が公開になっているか、版が進んでいるか、更新日時が今日になっているか、までです。誰かが今日触ったことはわかりますが、中身が正しいかはわかりません。

作成と公開は、画面の仕事

作成、編集、公開は、公開されているAPIの範囲外です。私たちは、ここを無理に自動化しようとせず、役割を分けました。

• AIは、貼り付けるコードと手順書を用意する
• 人が、画面でワークフローを組み、保存する
• 合図を受けて、AIがAPIでデータを投入し、結果を確かめる

画面の操作が不安定な場面で、無理にAIに画面を操作させるより、この分け方のほうが速く、事故も少なくなりました。

疎通テストは、作る・待つ・読むの3手

動いたかを確かめる標準の手順は、次の5つです。

• 仕込み：検証用のカスタムフィールドを作り、ダミーのコンタクトとオポチュニティを入れる
• 発火：トリガーの条件を満たすレコードを、APIで新しく作る
• 待機：30秒ほど待つ
• 検証：作ったレコードを読み出し、対象のフィールドの値を期待値と突き合わせる
• 記録：結果を残す

期待値は、投入した値から先に計算し、手順書に書いておきます。目で見て合っていそう、という判定は使いません。

実測した例

月次の売上と人件費を入れると、計算結果が人件費率のフィールドに入るワークフローを試しました。売上が約1,030万、人件費が約572万のダミーを入れて、フィールドには55.5という値が入りました。期待どおりで、疎通は成功です。

後片付けを楽にする約束事

検証用のデータは、名前の先頭に「[検証]」を付けます。コンタクトには、検証用であることと、その日の日付を示すタグを付けます。日付のタグがあれば、あとで一括して消せます。

テスト用のワークフローは、検証が終わったらすぐに下書きへ戻します。戻ったかどうかは、一覧の状態で確かめます。

空メールは、送信済みの本文で見つける

メールを送るワークフローでは、別の確認が要ります。テンプレートが健全でも、ワークフローのメール送信ノードが空のメールを送ることがあるからです。

送信済みの本文は、APIで全数読めます。会話の一覧から会話をたどり、各メールのIDで本文を読み出します。件名、状態（届いた、開かれた、失敗）、本文のHTMLが取れます。

空メールの見分け方

本文が、配信停止のフッターの英文だけだったら、それは空メールです。GoHighLevelは、本文が空のメールに、英語の既定のフッターを自動で足します。

文字数では見分けにくいので、日本語の文字（かなと漢字）の字数で判定します。日本語が0字なら、本文は入っていません。受信側のメールソフトが「英語のようです」と判定するのは、この既定のフッターが原因です。

原因の探し方

私たちの調べでは、テンプレートの7本はすべて健全でした。それでも空のメールが届き続けました。メール送信ノード7つのうち6つで、テンプレートの参照が保存されていなかったためです。

件名はノードに手で入力する欄なので、正しく届きます。「件名は正しいのに、本文だけが空」という症状は、ノードの側を疑う合図です。テンプレートを作り直すと、正しいものを壊すだけです。

Custom Codeの出力は、returnではなくoutput

ワークフローのCustom Codeには、書き方の約束があります。結果を返すときは、return ではなく、output という変数に辞書を代入します。保存の前に、Test your code を実行しておくことも必須です。

画面で貼る人に渡す手順書には、この2点を最初の行に書いておきます。貼り付けたコードが動かないとき、原因の多くはこの書式だからです。

公開の状態を、読み出しで裏づける

テスト用に公開したワークフローが、戻されたかどうかは、一覧の状態で裏づけます。画面で下書きに戻したと聞いても、一覧を読み出して状態が下書きであることを確かめるまでは、戻ったと数えません。

次に読む

ワークフローの次は、ページを持つ機能です。ファネルとフォームについて、APIで見える範囲と見えない範囲は、ファネルとフォームの記事にまとめました。