カスタム関数 #

カスタム関数を使用すると、AIボットがライブ会話中に他のシステムと接続できるようになります。「確認して折り返します」と言う代わりに、ボットが注文状況を検索したり、在庫を確認したり、CRM（HubSpotやSalesforceなど、リードや顧客を追跡するために使用する顧客関係管理システム）にレコードを作成したりできます。これらすべてを、顧客を待たせることなくリアルタイムで行うことができます。

カスタム関数とWebhookの違い #

これは最もよくある混乱のポイントですので、何かを構築する前に明確にしておく価値があります。

どちらを選ぶべきか: 何かが発生したことを別のシステムに通知するだけでよい場合は、Webhook（別のシステムに送信される一方向の自動メッセージ。設定 → インテグレーション → Webhookを参照）を使用してください。ボットが会話を続ける前に別のシステムから何かを学習する必要がある場合は、カスタム関数を使用します。

カスタム関数で実現できることの例 #

応答が会話にフィードバックされるため、カスタム関数はWebhookでは不可能なことを実現します。

• ShopifyやWooCommerceのライブ在庫検索 — 顧客に見積もりを出す前に、ボットがリアルタイムで在庫を確認し、「確認して折り返します」と言う代わりに「はい、Mサイズが12個あります」と回答します。
• Googleスプレッドシートからの動的価格設定 — 営業チームがシートの価格を更新すると、ボットは会話の途中で最新の行を読み取り、AI設定を誰も触ることなく現在の価格を提示します。
• 音声AIコールバックエージェント — ボットがリードを適格と判断すると、音声エージェント（例：ElevenLabsを利用した発信者）を起動して数分以内にリードに電話をかけさせ、顧客に「承知いたしました。5分以内に電話があります」と伝えます。
• カスタム見積もりPDFの生成とチャット中のメール送信 — ボットが要件を収集し、見積もり作成ツールを呼び出してPDFのURLを取得し、顧客に「見積もりをメールで送信しました。受信トレイを確認してください」と伝えます。

カスタム関数で何ができるか？ #

カスタム関数は、ボットに単なる会話以上のスーパーパワーを与えるものだと考えてください。実際の例をいくつか挙げます。

• 注文追跡 - 顧客が「注文はどこですか？」と尋ねると、ボットがeコマースシステムを確認し、配送状況と追跡リンクを返信します。
• 在庫確認 - 「サイズ10はありますか？」という質問に対し、ボットが在庫システムを確認してリアルタイムで回答します。
• CRMの更新 - ボットがリードを適格と判断すると、HubSpot、Salesforce、その他のCRMのレコードを自動的に作成または更新します。
• 見積もり生成 - ボットが顧客の要件を収集し、価格設定システムからパーソナライズされた見積もりを生成します。
• 予約 - ボットが外部の予約システムにアポイントメントを作成します。
• 割引の検証 - 「このクーポンコードは有効ですか？」という質問に対し、ボットが確認して回答します。
• アカウント検索 - リピーターの顧客を自動的に認識し、アカウント詳細を呼び出します。

顧客は舞台裏で何が起こっているのかを知ることはありません。 彼らは単に、最新の正確な情報で質問に答えてくれるボットを体験するだけです。

カスタム関数の仕組み（簡易版） #

会話中にカスタム関数がトリガーされると、以下のような処理が行われます。

1. 顧客が何かを尋ねる（例：「注文はどこですか？」など、リアルタイムのデータが必要な場合）
2. ボットが認識する（回答するためにカスタム関数を使用する必要があることを認識します）
3. ボットが情報を収集する（不足している情報を顧客から収集します。例：「注文番号は何ですか？」）
4. プラットフォームがリクエストを送信する（関連する詳細情報とともに、お客様のシステム（Webサイト、CRM、その他のツール）へリクエストを送信します）
5. システムが応答する（データ（注文状況、追跡番号、配送日など）を返します）
6. ボットが応答を読み取る（自然な返信を作成します。「ご注文 ORD-4582 は発送済みで、金曜日までに到着予定です！」）

カスタム関数呼び出しのコスト #

各カスタム関数呼び出しは、エージェントのAI品質ティアに基づいて課金されます：

カスタム関数の設定（ステップバイステップ） #

1. メインサイドバーの AI Studio で、Custom Functions をクリックします。

2. 右上の緑色の + Add Function（または New function）ボタンをクリックします。

カスタム関数リストには、以下の列を持つテーブルが表示されます。

これにより、関数を一目で確認し、必要なものを簡単に見つけることができます。

ステップ 1: 名前と説明を入力する #

ヒント: 説明と目的は非常に具体的に記述してください。関数を使用すべきタイミングを明確にすればするほど、ボットは適切なタイミングでより確実にそれを使用できるようになります。

ステップ 2: 接続を設定する #

リクエストの送信先をアプリに指定する必要があります。

どのメソッドを選択すべきか:

どちらを使用すべきか不明な場合は、開発者または接続先システムのドキュメントを確認してください。GET（検索用）とPOST（レコード作成用）が最も一般的です。

ステップ 3: 認証ヘッダーを追加する #

ほとんどのシステムでは、リクエストを受け入れるために認証が必要です。必要なヘッダーを追加してください：

Authorization や X-API-Key など、キーやパスワードを含むヘッダーの値は、入力するとドットで表示されます。値の横にある目のアイコンをクリックすると、内容を確認できます。

セキュリティのヒント: 権限を制限した専用のAPIキーを使用してください。管理者レベルの認証情報は使用しないでください。

APIキーの場所: 接続先システム（CRM、eコマースプラットフォーム、予約ツールなど）の設定または開発者向けセクションを確認してください。

ステップ 4: 入力を定義する（ボットが送信する内容） #

入力パラメーターは、ボットが会話から収集し、システムに送信する情報です。

各パラメーターについて、以下を指定します：

利用可能なパラメータータイプ：

各パラメータには、オプションの Request body path（リクエストボディパス）フィールドもあります。通常、パラメータはリクエストボディのトップレベルフィールドとして（または query_param 型の場合はクエリ文字列の値として）送信されます。エンドポイントがネストされた形式（例: {"order": {"id": "ORD-123"}}）を期待している場合は、パスを order.id に設定すると、プラットフォームが自動的にその場所に値をネストします。

例：注文状況の検索の場合、以下のように定義します：

• order_number (string, 必須): 「顧客の注文番号。通常はORD-の後に数字が続きます。顧客が言及していない場合は、これを尋ねてください。」
• email (string, 任意): 「追加確認のための顧客のメールアドレス。注文番号だけでは一致が見つからない場合にのみ必要です。」

システムが自動的に受信するもの #

定義した入力パラメータに加え、プラットフォームはすべてのリクエストにシステムデータを自動的に含めます。エンドポイントは、このデータを system フィールドで受信します。

これは、システムが連絡先を識別する必要がある場合、どのエージェントが関数を呼び出したかを確認する場合、またはテスト中に異なる動作をさせる必要がある場合に役立ちます。

フォローアップチェックが関数を呼び出す場合（チェックが合格したときのみ送信を参照）、そのリクエストは会話中の呼び出しとは異なります。入力パラメータはなく、systemフィールドにはsystem.contact（そのidを含む）とsystem.follow_upブロック（type、cycle_number、follow_up_number、reason、campaign_id、agent_id）のみが含まれます。その中にcampaignオブジェクトはありません。システムデータをスキップは、その呼び出しにも適用されます。

システムデータが不要ですか？ 関数ビルダーで システムデータをスキップ (Skip System Data) トグルをオンにします。これにより、ボットは定義した入力パラメータのみを送信し、連絡先データやエージェントデータは送信されなくなります。エンドポイントが予期しないフィールドを拒否する場合や、単にペイロードを軽量化したい場合に使用してください。

ステップ 5: テストを実行し、ボットにレスポンスを読み取らせる #

通常、レスポンスフィールドをマッピングする必要はまったくありません。エンドポイントが応答すると、ボットはJSONレスポンス全体を読み取り、関数の Description（説明）と Purpose (AI Action)（目的（AIアクション））、および各パラメータ自身の説明を使用して、何が重要かを判断し、自然な形で提示します。関数自体の明確な説明（「配送情報や追跡情報を含む顧客注文の現在のステータスを取得します」など）は、フィールドごとのマッピングよりもはるかに効果的です。

エンドポイントが大きなレスポンスを返し、ボットに特定のいくつかの値のみを認識させたい場合は、Response mapping（レスポンスマッピング）セクション（デフォルトでは折りたたまれており、Testのすぐ上にあります）を開いてください。各行でレスポンスから1つのトップレベルフィールドを選択します。Response field はAPIのJSON応答におけるフィールド名で、Output field はボットがそれを受け取る際の名称です。少なくとも1行を入力すると、ボットはレスポンスボディ全体ではなく、マッピングされた値のみを受け取ります。デフォルトの全レスポンスを受け取る動作を維持するには、このセクションを空のままにしてください。

保存する前に、ビルダー下部にある Test セクションを使用して、設定通りにリクエストを送信し、アプリを離れることなく実際のレスポンスを確認してください。

ここに表示されているレスポンスは、エンドポイントからの生の応答です。上記でレスポンスマッピングを設定している場合、実際のチャット内のボットはマッピングされたフィールドのみを受け取ります。テストでは常に完全な生のレスポンスが表示されるため、マッピング可能な項目を確認できます。もし何かがおかしい（予期しないフィールド名、余分なネストなど）場合は、エンドポイント側で修正するか、マッピングを調整してください。

エージェントへの関数の割り当て #

カスタム関数を作成した後、各エージェントに使用させる関数を指定する必要があります。

1. AI Studio → AIエージェント から エージェント を開きます。
2. AI機能 (AI Abilities) タブに移動します。
3. 作成したすべてのカスタム関数の一覧が表示されます。このエージェントのボットが呼び出せるようにしたい各関数をオンに切り替えます。
4. 下部の 変更を保存 (Save changes) をクリックします。選択内容は保存されるまで適用されません。

割り当てられた関数のみが、そのエージェントのボットで使用可能です。これにより、ボットが関連性のない関数を誤って使用することを防ぎます。

カスタム関数のテスト #

本番環境で公開する前に、十分にテストを行ってください。

1. 組み込みテストの実行 - 関数ビルダー内の Test セクション（上記参照）を使用して、アプリを離れることなく簡単に確認します。現実的な値を入力し、「Run test」をクリックしてください。
2. システムの直接テスト - 以下のチェックリストを完全に網羅するには、Postmanのような専用ツールを使用して、「Run test」よりも詳細な調査を行います。
3. Try Outでのテスト - 顧客が関数をトリガーするような質問をした場合を想定した会話をシミュレーションします。
4. レスポンスの確認 - ボットがデータを正しく読み取り、提示しているかを確認します。
5. エラーシナリオのテスト - 顧客が無効な注文番号を入力した場合はどうなるか？システムが一時的にダウンしている場合はどうなるか？

テスト結果が 401 または 403 の場合 #

401 または 403 は、エンドポイントがリクエストを受信したものの、それを拒否したことを意味します。特徴的なのは、自身のログに何も表示されないことです。ほとんどのツールは、ワークフローを開始する前に未承認の呼び出しを拒否するため、こちら側には何も表示されず、リクエストが一度も届かなかったように見えます。

これはほぼ間違いなく認証の不一致です。エンドポイントが要求する認証情報と、関数が送信している認証情報が異なっています。ステップ 3 で追加したヘッダーが、システムが期待するものと完全に一致しているか確認してください。

Basic Auth で保護されたWebhook（n8n、Make、およびほとんどのセルフホストツールでは、Webhook自体のチェックボックスでこれを有効にできます）に対して、関数が X-My-Secret のようなカスタムシークレットヘッダーを送信している場合が最も一般的です。Basic Auth は Authorization ヘッダーのみを受け入れるため、カスタムヘッダーは無視され、呼び出しは拒否されます。以下の2つの選択肢があります。

• Webhookの Basic Auth をオフにし、代わりにワークフロー内でカスタムヘッダーをチェックします。
• Basic Auth をオンのままにし、関数に Authorization ヘッダーを追加します。その値は Basic という単語の後に base64 エンコードされた username:password を続けたものにします。

どちらの方法でも機能しますが、両側で設定が一致していることを確認してください。

テスト結果が 404 の場合 #

エンドポイントのURLが間違っているか、ワークフローが公開されていません。特に n8n では、すべてのWebhookに個別の Test URL と Production URL があり、Test URL はエディタを開いている間のみリッスンします。Production URL をコピーし、ワークフローがアクティブであることを確認してください。

「試用」および「チャット」での失敗の確認 #

会話中にAIがカスタム関数を呼び出し、認証情報の誤り、エンドポイントのダウン、タイムアウトなどが原因で呼び出しが失敗した場合、その旨が会話に表示されるようになりました。エージェントの**「Try Out」タブおよび「Chats」内の実際の会話の両方で、スレッド内に赤い「(関数名) failed」**というマーカーが表示されます。マーカーをクリックすると詳細が展開され、エンドポイントが返したステータスコードとレスポンスボディが表示されます。通常、これだけで修正すべき内容がわかります（「unauthorized」メッセージを含む 401 は認証ヘッダーの問題、タイムアウトはエンドポイントの処理に30秒以上かかったことを意味します。より長い時間が必要なジョブについては、長時間実行ジョブを参照してください）。

成功した呼び出しにもマーカーが表示されます。クリックすると、エンドポイントが実際に何を返したかを確認できます。これは統合をエンドツーエンドでデバッグする最も迅速な方法です。「試用」でテスト会話を行い、関数マーカーをクリックするだけで、ページを離れることなく実際の要求結果を確認できます。

実際の会話でツールが失敗し続ける場合 #

AIエージェントとのチャット中に同じカスタム関数が24時間以内に3回失敗すると、1日1回、メール、ベルアイコンの通知、および有効にしている場合はプッシュ通知でアラートが送信されます。アラートにはツール名、最後のエラー内容、および影響を受けたチャットへのリンクが含まれます。これは、エージェントがその連絡先に対して技術的な問題が発生したことを伝えているためです。ツールの動作が正常に戻るまで、設定内の関数の行にはエラー回数と最後のエラー内容を含む失敗という行が表示されます。一度でも呼び出しに成功すれば、この表示は消去されます。これらのアラートは、設定 → 通知 → ツールのエラーからオフにすることができます。

完全な例：注文ステータスの照会 #

テンプレートとして使用できる、完全に設定された例を以下に示します。

基本情報:

• 名前: check_order_status
• 説明: “配送情報や追跡情報を含む、顧客の注文の現在のステータスを取得します”
• AIアクション: “顧客が注文状況、荷物の場所、到着予定日について尋ねたときにこれを呼び出します。必ず最初に注文番号を尋ねてください。”

接続:

• URL: https://api.mystore.com/orders/lookup
• メソッド: POST

ヘッダー:

• Authorization: Bearer sk_live_abc123
• Content-Type: application/json

入力パラメーター:

• order_number (text, 必須): “顧客から提供された注文番号”
• customer_email (text, 任意): “追加確認のための顧客のメールアドレス”

レスポンスのマッピングは不要です — 上記で明確な説明とAIアクションが設定されていれば、ボットはエンドポイントが返すJSON（ステータス、追跡番号、配送日、商品など）を読み取り、それについてどのように話すべきかを判断します。

会話の例:

顧客: ねえ、私の注文はどこにあるの？

ボット: こんにちは！注文状況をお調べしますね。注文番号を教えていただけますか？

顧客: ORD-78234 です

ボット: お調べします…

ご注文 ORD-78234 は発送済みで、現在配送中です！到着予定日は3月10日です。こちらのリンクから荷物を追跡できます: https://tracking.example.com/1Z999AA1

他にお手伝いできることはありますか？

完全な例：Shopify注文ステータス #

ストアがShopifyで運営されている場合、ルックアップエンドポイントを構築するために開発者は不要です。Shopifyのシステム自体が注文に関する質問に直接回答できます。（Shopifyストアの商品や在庫に関する質問の場合、カスタム関数は全く必要ありません。ストアの組み込みサーバーを接続してください。詳細はShopifyストアを接続するを参照してください。）

まず、Shopifyでアクセストークンを作成します。 Shopifyは2026年中にこの仕様を変更しました。アプリはShopify管理画面内で作成できなくなり、新しいアプリ作成画面では、すぐに使えるトークンの代わりにクライアントIDとクライアントシークレットが発行されるようになりました。以下の手順で、それらを永続的なトークンに変換します。ストアごとに1回、約10分かかります。（ストアですでに従来の方法で作成された古いアプリがある場合、既存のトークンはそのまま機能し続けるため、以下のカスタム関数の手順に直接進んでください。）

1. Shopify開発者ダッシュボード（dev.shopify.com）にアクセスし、組織を開いて Apps → Create app をクリックします。Order lookup のような名前を付けます。
2. アプリに read_orders 権限を付与し、バージョンをリリースして、ストアにアプリをインストールします。
3. アプリの Settings を開き、ストア独自のWebアドレス（例：https://www.yourstore.com/）を許可されたリダイレクトURLに追加して保存します。
4. 同じく Settings で、Client ID と Client secret をコピーします。
5. そのストアのShopify管理画面にログインしているブラウザで、以下のURLを開きます。その際、ストア名、クライアントID、リダイレクトアドレスを自分のものに置き換えてください： https://YOUR-STORE.myshopify.com/admin/oauth/authorize?client_id=YOUR-CLIENT-ID&scope=read_orders&redirect_uri=https://www.yourstore.com/&state=12345 表示された画面を承認します。ブラウザがリダイレクトアドレスに遷移し、アドレスバーに code= とそれに続く長い値が表示されます。その値をコピーしてください。これは数分間しか有効ではないため、すぐに次のステップに進んでください。
6. そのコードをトークンと交換します。これは Your AI Connector 内で行うことができます。カスタム関数ビルダーで、Method を POST に、URL を https://YOUR-STORE.myshopify.com/admin/oauth/access_token に設定し、client_id、client_secret、code という名前の3つのテキスト入力パラメータを追加します。次に「テスト」をクリックし、3つの値を入力して実行します。レスポンスに access_token が含まれます。これが永続的なトークンです。安全な場所にコピーしてから、ビルダーをクリアし、以下の手順で実際の関数をセットアップしてください。

次に、カスタム関数を設定します：

基本情報：

• 名前： check_shopify_order
• 説明： “ストアのShopifyシステムで注文を検索し、ステータス、追跡情報、商品情報を返します”
• AIアクション： “顧客が注文ステータスや配送について尋ねたときにこれを呼び出します。必ず最初に注文番号を尋ねてください。”

接続：

• URL： https://YOUR-STORE.myshopify.com/admin/api/2026-01/orders.json?status=any — YOUR-STOREをストアの.myshopify.com名に置き換えてください（このアドレスはストアのカスタムドメインではなく、技術的なShopifyドメインを使用します）
• メソッド： GET

ヘッダー：

• X-Shopify-Access-Token: shpat_... （上記で取得したトークン）

入力パラメーター：

• name (query_param, 必須): “注文確認メールに記載されている通りの注文番号（#記号を含む、例：#1001）。顧客が言及していない場合は尋ねてください。”

レスポンスのマッピングは不要です — ボットが返された注文情報（支払いステータス、配送ステータス、追跡情報、商品）を読み取り、自然に回答します。

知っておくべきこと： この方法で作成されたトークンは、過去60日間の注文を参照できます。日常的なサポートの質問には十分ですが、全注文履歴ではありません。

完全な例：予約の作成 #

基本情報:

• 名前: create_booking
• 説明: “予約システムに新しい予約を作成します”
• AIアクション: “日付、時間、連絡先を顧客と確認した後に使用してください。顧客が予約を明示的に希望するまで呼び出さないでください。”

接続:

• URL: https://booking.mycompany.com/api/appointments
• メソッド: POST

入力パラメーター:

• date (text, 必須): “YYYY-MM-DD形式の予約日”
• time (text, 必須): “HH:MM形式の予約時間”
• name (text, 必須): “顧客の氏名”
• phone (text, 必須): “顧客の電話番号”
• service_type (text, 必須): “予約するサービスの種類”

完全な例: ニュースレター購読者をCRMに追加する #

非常によくあるパターンとして、ボットが回答を終えた後にニュースレターを提案し、連絡先がメールアドレスで返信し、そのアドレスを即座にメールツールへ登録するというものがあります。ほとんどのCRM（FluentCRM、ActiveCampaign、MailerLite、Brevoなど）は、これに対してシンプルなPOSTリクエストを受け入れるため、間に自動化プラットフォームを挟む必要はありません。

この例では、WordPress上のFluentCRMを使用します。「インバウンドWebhook」や「購読者の作成」エンドポイントを提供する他のツールでも、構成は同じです。

まず、CRMからURLを取得します。 WordPressで FluentCRM → 設定 → インバウンドWebhook を開き、Webhookを作成します。新しい連絡先に適用するリスト、タグ、購読ステータスを選択し、生成されたWebhook URLをコピーします。ここで設定した内容はすべて自動的に適用されるため、ボットはメールアドレスを送信するだけで済みます。

次に、カスタム関数を設定します：

基本情報:

• 名前: add_newsletter_subscriber
• 説明: “チャットで提供されたメールアドレスを使用して、ニュースレターリストに登録する”
• AIアクション: “連絡先がニュースレターの購読に同意し、メールアドレスを提供した瞬間にこれを使用してください。実際にアドレスが提供される前に呼び出したり、同じ人物に対して二度呼び出したりしないでください。”

接続:

• URL: CRMからコピーしたWebhook URL
• メソッド: POST

入力パラメータ:

• email (文字列、必須): “会話の中で連絡先が提供したメールアドレス”
• first_name (文字列、任意): “連絡先が言及した場合の、その人の名”

システムデータをスキップ: これをオンにします。CRMには上記のフィールドのみが必要であり、ペイロードを軽量化することで、予期しないフィールドを拒否するツールでのエラーを回避できます。

レスポンスマッピング: ここでは不要です。ボットが処理を継続するために戻り値を受け取る必要はありません。

会話を実行するエージェントに対して関数を有効にすることを忘れないでください（エージェントへの関数の割り当てを参照）。これは、正しく構築された関数が実行されない最も一般的な理由です。

信頼性の高いカスタム関数を作成するためのヒント #

1. 繰り返しリクエストが安全であることを確認する。 同じリクエストが誤って2回送信された場合でも、重複したレコードが作成されないようにする必要があります。ネットワークの不具合により、このような事態が発生することがあります。

2. 明確なエラーメッセージを返す。 システム側で何らかの問題が発生した場合は、人間が理解できるエラーメッセージを返してください。ボットがそれを顧客に適切に伝えます。

3. 応答時間を10秒以内に抑える。 システムの処理に時間がかかる場合は、まず簡単な応答を返すことを検討してください。

4. 期限切れや無効な認証情報を処理する。 APIキーの有効期限が切れた場合は、ボットが再試行せずに人間に通知できるよう、明確なエラーメッセージを表示するようにしてください。

5. 詳細な説明を記述する。 AIは、いつ関数を呼び出し、会話からどのように適切な情報を抽出するかを判断するために、あなたの記述を使用します。説明が曖昧だと、誤った結果につながります。

6. 実際の会話でテストする。 「試用（Try Out）」は初期テストには最適ですが、最初の数件のライブ会話を監視して、実際の顧客の問い合わせで問題なく動作することを確認してください。

7. ログを保持する。 アプリから送信されるリクエストを記録するよう開発者に依頼し、問題が発生した際に迅速にデバッグできるようにしてください。

8. ファイアウォールでIP許可リストが必要な場合、すべてのカスタム関数呼び出し（およびその後のチェック）は、当社のWebhookで使用しているものと同じ固定のIPv4アドレスから送信されます。範囲指定やIPv6、ローテーションはありません。サポートまでご連絡いただければ、そのアドレスをお伝えします。信頼性を確認する真の手段としてリクエスト署名を有効にして署名を検証し、IPアドレスは補助的なフィルタとして扱うようにしてください。

9. 公開されている最終URLを使用してください。 関数のURLは、公開されているWeb（HTTP/HTTPS）アドレスである必要があります。内部アドレス、localhost、プライベートネットワークのアドレスはセキュリティ上の理由から拒否されます。また、プラットフォームはリダイレクトに従わないため、リダイレクト先ではなく、最終的なURLを直接関数に指定してください。

長時間実行ジョブ：結果を後で取得する #

通常、カスタム関数は連絡先が返信を待っている間に30秒以内で応答する必要があります。動画のレンダリング、与信チェック、社内担当者の承認待ちなど、それ以上の時間がかかるジョブもあります。そのような場合は、「結果は後で送信 (長時間実行)」をオンにしてください。AIの呼び出しはジョブを開始するだけになります。サービスは即座に応答し、AIは連絡先に結果が準備中であることを伝えて会話を続行します。その後、サービスはジョブが完了した時点でコールバックリンクに結果を送信します。

使用するタイミング #

サービスが30秒以内に確実に応答できない場合に使用してください。注文状況、在庫確認、価格照会などの迅速なルックアップにはオフのままにしておきます。これらは通常の呼び出しとして処理する方が簡単です。AIが同じ返信内で結果を回答できるためです。

エディタでの設定 #

これらはカスタム関数エディタの**「システムデータをスキップ」**の横にあります。

サービスが受け取るもの #

トグルをオンにすると、上記のすべて（入力パラメータ、system ブロック、署名ヘッダー）に加えて、すべての呼び出しにコールバックリンクが3か所に含まれます。

このリンクは各呼び出しに固有のもので、その連絡先と呼び出しに紐付いており、1回限り有効で、**「待機時間」**が経過すると期限切れになります。使用するためにAPIキーは必要ありません。リンク自体が権限となります。パスワードのように扱い、公開ログには決して書き込まないでください。

結果の送信 #

ジョブが完了したら、コールバックリンクに対してPOSTリクエストを送信します。

POST https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 },
  "message": "Your video is ready: https://cdn.example.com/spring-offer.mp4"
}

• result はAIが読み取る内容です。テキストまたはJSONオブジェクトを指定できます。
• message はオプションです。Send the text as is（テキストをそのまま送信）を選択した場合、送信時に連絡先は message を受け取ります。それ以外の場合は、テキストとして result を受け取ります。
• media_url はオプションです。ファイル（画像、動画、音声、ドキュメント）への https リンクを指定すると、連絡先はリンクとしてではなく、実際の添付ファイルとして受け取ります。以下の ファイルの送信 を参照してください。
• Content-Type: text/plain を使用してプレーンテキストの本文を送信することもできます。これは result として扱われます。
• 本文は最大64 KBまでです。

コールバックリンクの応答内容:

完全な例：3分かかる動画 #

1. AIがあなたの関数を呼び出します。あなたは（短縮された）以下を受け取ります:

POST https://api.example.com/render
X-Callback-Url: https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "video_title": "Spring offer",
  "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
  "system": {
    "contactId": "...",
    "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
    "callback_expires_at": "2026-10-20T19:15:00.000Z"
  }
}

2. あなたのサービスがレンダリングを開始し、即座に応答します:

{ "status": "started" }

3. AIは連絡先に動画を作成中であることを伝え、チャットを続けます。
4. 3分後、あなたのサービスがコールバックリンクに結果を投稿します:

{ "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 } }

5. AIは「動画の準備ができました: https://cdn.example.com/spring-offer.mp4」のように、自身の言葉で次のメッセージを作成します。

ZapierやMakeを使用していますか？ トリガーとなるWebhookで呼び出しを受け取り、フローの最後のステップでトリガーデータから callback_url へのPOSTを実行してください。

チャットで起こること #

結果は関数エントリとして会話に保存されるため、他のカスタム関数呼び出しと同様に受信トレイで確認できます。その後、結果が到着したときの設定に応じて、AIが次のメッセージを作成して送信する（AIメッセージと同様にAIの返信回数を1回消費します）か、あなたのテキストがそのまま送信されます。テキストをそのまま送信を選択した場合、message フィールドを含めるとそれが送信され、それ以外の場合はプレーンテキストとして result が送信されます。テキストなしでオブジェクトのみを投稿した場合は、代わりにAIがメッセージを作成します。

結果が到着した時点でその連絡先に対してAIがオフになっている場合（チームメンバーが対応を引き継いだ、AIが一時停止中、エージェントがオフライン、またはクレジット不足など）、結果は会話に保存されますが、メッセージは送信されません。AIが再びオンになったときに後から送信されることもありません。チームメンバーはチャット内で結果を確認し、それを利用できます。

エージェントの 試用 (Try Out) タブでもフロー全体が機能し、テストチャットに結果が届きます。

ファイルの送信（動画、画像、PDF） #

サービスがバックグラウンドでレンダリングした動画などのファイルである結果は、どちらのモードでも、連絡先がチャット内で開くことができる添付ファイルとして届きます。プラットフォームは、コールバック内のファイルを次のように検索します。

1. 本文内の media_url（送信した場合）。
2. それ以外の場合は、result オブジェクトのファイルフィールド：file_url、video_url、image_url、pdf_url、document_url、audio_url、attachment_url、または download_url。
3. それ以外の場合は、テキスト内でファイル拡張子（.mp4、.jpg、.png、.pdf など）で終わる最初の https リンク。

The AI writes the next message（AIが次のメッセージを作成）を選択すると、AIがテキストを作成し、そのメッセージにファイルが添付されます（AIにはリンクを貼り付けないよう指示されます）。Send the text as is（テキストをそのまま送信）を選択した場合、あなたの message が添付ファイルのキャプションになります。

{
  "result": { "status": "done", "title": "Spring offer" },
  "message": "Your video is ready.",
  "media_url": "https://cdn.example.com/spring-offer.mp4"
}

ファイルは最大16 MBまでで、https 経由でアクセス可能である必要があります。各チャネルで扱える種類は異なります。たとえば、メールやWhatsAppチャネルでは動画、画像、音声、ドキュメントを扱えますが、SMSではファイルを扱えません。チャネルがファイルを扱えない場合やファイルが大きすぎる場合、連絡先はメッセージを受け取りますが、最後にファイルへのリンクが追加されます。

結果が届かない場合 #

最大待機時間が経過しても何も投稿されない場合、AIには結果が届かなかったことが通知され、連絡先にその旨を伝えられるようになります。設定 → エラーログの下にコード APP-3103 のエントリが表示され、ツールエラーの通知が届きます。

制限の概要 #

• コールバックリンク1つにつき1つの結果。同じリンクへのその後の投稿は重複として扱われ、何も変更されません。
• 結果1つにつき最大64 KB。
• 結果1つにつき1つのファイル、最大16 MB、https 経由。
• 1つのリンクに対して1分間に最大20件の投稿。
• Wait up to（最大待機時間）は1時間から168時間。
• サービスは最初の呼び出しに対して30秒以内に応答する必要があります。

呼び出しが確実に当社からのものであることを検証する #

関数のURLを知った第三者は、偽のリクエストを送信する可能性があります。認証ヘッダーに長いシークレットを使用することは有効ですが、すべての呼び出しで同じ値が使用されるため、一度でもリクエスト（ログやスクリーンショットなど）を目にした人はそれを再利用できてしまいます。リクエスト署名はこれを解決します。すべての呼び出しに、シークレットを保持している者だけが生成でき、数分で期限切れになる署名が付与されます。

署名はオプションであり、デフォルトではオフになっています。これはアカウント全体の設定であり、1つのシークレットですべてのカスタム関数に署名します。

署名の有効化 #

1. カスタム関数を開きます。
2. 関数リストの下にあるリクエスト署名カードを見つけ、署名を有効にするをクリックします。
3. 表示をクリックしてシークレット（whsec_で始まります）をコピーし、呼び出しを受信するシステムに保存します。パスワードと同様に扱ってください。

同じカードから、シークレットの再コピー、ローテーション（古いシークレットは即座に使用できなくなります）、または署名の無効化を行うことができます。

送信される内容 #

署名が有効になると、カスタム関数が行うすべての呼び出しに2つの追加ヘッダーが付与されます。これには、チャット中のAIによる呼び出し、フォローアップ送信条件、エディタ内のテスト実行ボタンが含まれます。

署名の有無にかかわらず、すべての呼び出しには、独自のUser-Agentヘッダーを設定しない限り、User-Agent: Custom-Function/1.0も含まれます。

ヘッダーと署名の仕組みは署名付きWebhookと完全に同じであるため、すでに当社のWebhookを検証している場合は、同じコードをそのまま使用できます。異なるのはシークレットのみです。

検証方法 #

署名は、署名用シークレットをキーとして使用した、文字列<timestamp>.<raw request body>のHMAC-SHA256ハッシュです。受信した正確なバイト列であるrawボディに対して検証を行ってください。JSONを解析してテキストに戻すとバイト列が変化し、署名が一致しなくなります。

GETを使用する関数（または送信内容のないPOST）にはボディがないため、署名対象の文字列は空のボディを持つ<timestamp>.のみとなります。この場合、署名は呼び出しが当社からのものであり、最近行われたものであることを証明しますが、クエリ文字列は対象外となります。

Node.jsの例:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"] || ""; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const received = signature.replace("v1=", "");

  return received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Pythonの例:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Webhook-Timestamp", "")
    signature = headers.get("X-Webhook-Signature", "").replace("v1=", "")
    if not timestamp or abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

エディタ内のテスト実行で確認してください。署名が有効になると、テスト呼び出しもライブ呼び出しと全く同じように署名されるため、テストに合格した関数は、実際のチャット中のチェックにも合格します。

APIを使用していますか？ 同じシークレットを/v1/custom-functions/signing-secret上のGET、POST、およびDELETEを使用して読み取り、生成、ローテーション、削除することができます。

実行制限 #

すべてのカスタム関数には、エディターの下部にオプションの 実行制限 セクションがあります。これは、AIが関数を実行できる頻度や、以前の結果を再利用できるかどうかを制御します。ここにある設定はすべてオプションです。すべて空のままにすれば、関数はこれまで通りに動作します。

読み取り専用関数。 関数がデータの読み取り（株価検索、価格チェック、注文状況の検索など）のみを行い、データの作成や変更を一切行わない場合にこれをオンにします。AIが回答中に一時的なネットワーク障害で中断された場合、プラットフォームは顧客に回答を返せないままにするのではなく、安全に会話のターンを再試行できます。関数が本当に書き込みを行わない場合にのみ有効にしてください。レコードを作成する関数は、再試行によって誤って2回実行されることがないよう、オフのままにしておく必要があります。GETメソッドを使用する関数は、GETリクエストがデータの取得のみを目的としているため、自動的に読み取り専用として扱われます。POST、PUT、PATCH、DELETE関数にはこの切り替えが必要です。

繰り返し呼び出し時にキャッシュされた結果を返す。 AIが同じ入力で関数を再度呼び出した場合（例：顧客が同じ質問を2回した場合）、エンドポイントを再度呼び出す代わりに、以前の結果が再利用されます。キャッシュされた結果は最大24時間保持されます。入力が「異なる」呼び出しは、常にエンドポイントへ新しく送信されます。

会話ごとの最大実行回数。 1つの会話内で関数を実行できる回数の上限です。見積もりの生成、コールバックのトリガー、自動化の開始など、チャットごとに1回だけ実行すべき関数には「1」を設定します。上限に達すると、AIには関数がすでに実行済みであることが伝えられ、最新の結果が提供されるため、AIは沈黙することなく顧客に回答を続けることができます。

時間枠ごとの最大実行回数。 時間経過に基づくレート制限です（例：60分間に最大5回）。有料のサードパーティサービスを呼び出したり、負荷の高い自動化をトリガーしたりする関数に役立ちます。両方のボックスを併せて入力する必要があります（実行回数と、最大7日までの分単位の時間枠）。

LinkedInでのオファー、契約書、請求書の送信について。 AIがLinkedInで返信する際は、アカウント所有者自身の受信トレイから送信されるため、所有者の指示がない限り、オファー、契約書、見積書、請求書、支払いリンク、またはアクセス権を所有者に代わって送信すべきではありません。自動（Automatic）（デフォルト）設定では、送信に関連する名前や説明を持つ関数はLinkedIn上で実行されません。その場合、AIは何も送信されなかったと判断し、所有者が対応する旨を相手に伝えます。関数をLinkedIn上で実行させるには**許可（Allowed）を選択し、自動チェックをすり抜けてしまう関数を制限するにはLinkedInでは実行しない（Never on LinkedIn）**を選択してください。他のチャネルには影響せず、上記の制限とは異なり、この設定は「試用（Try Out）」にも適用されます。

いくつか知っておくべきこと:

• 制限は「成功した」実行のみをカウントします。エンドポイント側で失敗した呼び出しは、予算を消費しません。
• 制限によって実行がブロックされた場合でも、顧客が放置されることはありません。AIにはその理由が伝えられ、すでに持っている情報を使って対応します。
• 制限は、関数が実行されるすべての場所（すべてのチャネルでの通常のチャット、および自動化によって管理される関数）に適用されます。「試用（Try Out）」でのテスト会話はカウントされず、制限も適用されません。

組み込みボットツール #

自身で構築するカスタム関数に加え、プラットフォームにはAIボットが会話中に使用できる組み込みツールライブラリが用意されています。これらは、チームメンバーへの通知、予約の作成、連絡先へのタグ付け、Webサイトの検索、フォローアップのスケジュール設定など、ボットが必要とする一般的な機能を網羅しているため、ゼロから構築する必要はありません。

ボットは、会話の状況とエージェントの設定に基づいて、各ツールを使用するタイミングを判断します。 これらのツールのほとんどは、関連機能が有効になると自動的にオンになります（例：予約ツールは、カレンダーを接続して予約を有効にすると利用可能になります）。

クレジットコスト: 各ツール呼び出しはエージェントのAI品質ティアに基づいて課金され、自分で構築したカスタム関数も同様に課金されます：

チームおよびタスクツール #

連絡先ツール #

予約・アポイントメントツール #

これらのツールは、エージェントで予約が有効になっており、カレンダーイベントタイプが設定されている場合にのみ利用可能です。

ナレッジ・Webツール #

フォローアップツール #

これらのツールを使用するには、エージェントでフォローアップを有効にする必要があります。

カスタム関数実行ツール #

レストラン予約ツール (ZenchefおよびFormitable) #

これらのツールは、ZenchefまたはFormitableの統合が接続されている場合にのみ使用できます。ボットがレストランの予約をエンドツーエンドで管理できるようになります。

ツールのオン/オフの切り替え #

ほとんどのツールは、エージェントの AI機能 (AI Abilities) タブで管理されます。

• 予約ツールは、同じAI機能タブにある予約 (Bookings) カードで予約を有効にし、カレンダーを接続するとオンになります。
• フォローアップツールは、フォローアップを有効にするとオンになります。
• レストランツールは、ZenchefまたはFormitableアカウントを接続するとオンになります。
• ウェブ検索は、FAQとナレッジタブに専用のトグルがあります。
• タスクツールは、AIにタスク作成を許可するトグルを使用してエージェントごとにオフにできます（デフォルトではオンです。設定 → プロフィール → 機能にあるアカウント全体のタスクスイッチは、システム全体でタスク機能をオフにします）。
• 連絡先更新ツールは、同じAI機能タブで管理されます（AIが連絡先の名前を変更したり、収集した追加情報を保存したりできるかどうかを設定します）。
• アラートツールは常に利用可能です。タグ付けはボットの返信ごとに自動的に実行されます（これはボットが呼び出すツールではありません）。

ボットに特定の組み込みツールを使用させたくない場合は、基盤となる機能を無効にするのが最も確実な方法です（例：予約をオフにすると、すべての予約ツールが無効になります）。

オートメーションによって管理される関数 #

「カスタム関数」ページの一部のエントリには、**「オートメーションによって管理」というバッジが表示されることがあります。これらはこのページで作成されたものではなく、「AIエージェント関数」**トリガーを持つオートメーションから生成されたものです。これにより、外部のWebアドレスを指定する代わりに、オートメーションキャンバス上でステップを視覚的に構築して、エージェントに機能を持たせることができます。

管理対象関数は、システムによって自動的に管理されます。その名前、説明、フィールドは常にオートメーションのトリガー設定に従うため、このページから編集や削除を行うことはできません。変更が必要な場合は、Open automation（オートメーションを開く）リンクを使用して、オートメーション自体を編集してください。ただし、どのエージェントにその機能を持たせるかは、通常通り選択可能です。エージェントの AI Abilities（AI機能）タブでは、他の機能と並んで表示され、通常のオン/オフ切り替えスイッチで設定できます（オートメーションが一時停止されている場合はその旨が表示され、オートメーションが有効になると機能も利用可能になります）。それ以外の動作は他のカスタム関数と同様で、AIが呼び出すタイミングを判断し、定義された詳細情報を収集し、同じ会話内でオートメーションの返信を利用することができます。

どちらを選択するか迷っている場合：すでに呼び出し先のアドレスがあるシステムには通常のカスタム関数を指定してください。スプレッドシートやデータベースの検索、条件分岐、レコード作成など、サーバーを自分で運用せずにステップを組み合わせて作業を行いたい場合は、AIエージェント関数のトリガーを使用した自動化を構築してください。詳細は自動化を参照してください。

プランの要件 #

カスタム関数は、カスタム関数機能が含まれているプランで利用可能です。サブスクリプションを確認して、利用可能かどうかを確認してください。

次のステップ #

• MCPサーバーをボットに接続する — 関数を1つずつではなく、ツールをまとめて利用できます。
• AIエージェント — カスタム関数が属するAI Studioグループのメインページであり、カスタム関数をボットに割り当てる場所です。