Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

カスタム CRM（汎用 API）でのエラー処理、再試行、呼び出しの順序

このドキュメントでは、CRM エンドポイントが HTTP 200 "Success." 以外のレスポンスを返す場合の CCAI Platform のカスタム CRM（汎用 API）機能の動作について説明します。これは、API アカウントと API レコードエンドポイントを構成するインテグレーター向けの動作リファレンスとして作成されています。

大まかな実行順序と関係

インタラクションによってカスタム CRM 統合がトリガーされると、プラットフォームは次の順序でエンドポイントを呼び出します。

アカウント単位のオペレーション（API アカウント）- 連絡先

例:
- 連絡先を見つけます。
- 連絡先を作成します。
- 連絡先を更新する。
レコードレベルのオペレーション（API レコード）- チケットまたはケース

例:
- チケットを探します。
- チケットを作成します。
- チケットを更新する。
セッション後のアクション（構成されている場合）

例:
- コメントやメモを追加します。
- 添付ファイルまたは文字起こしをアップロードします。
- まとめの更新を適用します。

通常、前のステップで生成された ID が後のステップで使用されます。たとえば、contact_id は、エンドポイントペイロードテンプレートに含まれている場合、チケット作成に渡すことができます。ticket_id は、一般的な汎用 API 設定のセッション後のアクションに必要です。すべてのエンドポイントが ID を抽出するように構成されているわけではありません。重要なニュアンス: 2xx + ID 抽出エンドポイントに ID がないをご覧ください。

重要なニュアンス: `2xx` + ID 抽出エンドポイントに ID がない

すべてのカスタム CRM エンドポイントが、受信したレスポンスから ID を抽出するわけではありません。この動作は、response_data_location と（作成エンドポイントの場合は）custom_id_location で構成されたエンドポイント（通常はルックアップエンドポイント（既存のレコードの ID を抽出）と作成エンドポイント（新しく作成されたレコードの ID を抽出））にのみ適用されます。コメント、添付ファイル、更新などのエンドポイントは、レスポンスから ID を抽出しません。

ID 抽出エンドポイントで ID が欠落している場合の影響

ルックアップエンドポイントの場合: 一致するレコードがない（したがって、抽出可能な ID がない）200 OK レスポンスは、通常の「見つかりません」という動作です。インスタンスで skip_account_creation または skip_record_creation が有効になっている場合、プラットフォームは作成を試みるのではなく、null の contact_id または ticket_id を使用して意図的にダウンストリームに進みます。これは、これらの構成で想定される動作であり、構成ミスではありません。
エンドポイントの作成の場合: 構成されたロケーションに新しく作成された ID が含まれていない 200 OK レスポンスは、構成またはレスポンス契約の問題です。HTTP リクエストは成功したため、再試行はトリガーされません。ただし、ダウンストリームステップはデータが欠落した状態で続行される可能性があります。
どちらの場合も、障害（障害が発生した場合）はエンドポイントエラーではなく、データの欠落として表示されます。これは、デバッグ中に混乱を招く可能性があります。

インテグレーター向けガイダンス

作成オペレーションでは、2xx を返すだけでなく、構成されたロケーションで想定される ID を返すことを成功契約の一部にします。ID がない場合は、調査に値する構成またはレスポンス契約の問題として扱います。
ルックアップオペレーションの場合、一致しない 200 OK を返すことは許容されます。インスタンスが「作成なしのルックアップ」パターン（skip_account_creation = true など）に意図的に依存している場合は、その決定をドキュメント化して、ダウンストリームエンドポイントが欠落している ID を適切に処理できるようにします。
テストでは、次の点を確認します。
- エンドポイントの作成では、ID はレスポンスに確実に存在し、カスタム CRM で構成された正確な場所にあります。
- ルックアップエンドポイントの場合、プラットフォームの下流の動作はインスタンスのスキップフラグ構成と一致します。

エラー処理: 概要

エンドポイントが成功以外のレスポンス（2xx 以外）を返すか、応答しない場合:

プラットフォームはリクエストを再試行することがあります。
- 一部のステータスについては、すぐに 1 回。
- 再試行可能なエラーの場合は、より長い期間にわたって再試行します。
プラットフォームがアップストリームステップの再試行を続けている間、ダウンストリームステップが遅延する可能性があります。
一部の障害は、再試行不可として扱われます（構成エラーや検証エラーなど）。

再試行ルールの詳細については、再試行とバックオフの動作をご覧ください。障害とダウンストリーム呼び出しの関係については、チェーンと依存関係のルールをご覧ください。

チェーンルールと依存関係ルール

カスタム CRM の動作は、インスタンスの CRM 構成（具体的には、CRM アカウントとレコードの作成をスキップするに記載されている設定）によって管理されます。このドキュメントでは、これらの設定をバックエンド構成名（skip_account_creation、skip_account_lookup、skip_record_creation）で参照しています。これは、次の JSON 構成例でそのように表示されるためです。

これらの設定では、プラットフォームは、常に「ハードストップ」するのではなく、可能な場合はチェーンを継続する方向に偏っています。たとえば、ルックアップが失敗し、アカウント作成が有効になっている場合に匿名連絡先を作成するなどです。

アカウントの障害がレコードオペレーションに与える影響

アカウントステップで連絡先が生成されない場合でも、レコードステップ（チケット / ケース）が実行されることがありますが、正確な動作はインスタンスの構成によって異なります。

構成に応じて、プラットフォームは次の処理を行うことができます。

フォールバックとして匿名の連絡先を作成し、チケットの作成を続行します。
アカウントの検索またはアカウントの作成をスキップするように設定されている場合は、contact_id なしでステップの記録に進みます。

エンドポイントへの影響

チケットの作成時に contact_id がない場合は、通常、アカウントの検索またはアカウントの作成が無効になっているインスタンス構成を示します。
インスタンスでアカウントが必要な場合は、contact_id がないことを、連絡先なしでチケットをサイレントに挿入するのではなく、調査に値するシグナルとして扱います。
構成で連絡先なしでチケットを作成することを意図的に許可している場合は、チケットエンドポイントがそのケースを明示的かつ予測可能に処理するようにしてください。

記録の失敗がセッション後のアクションに与える影響

チケット検索が構成されている一般的な API 設定の場合、プラットフォームは、ticket_id が存在するまで、call_finished、chat_finished、email_finished、save_call_recording、save_chat_history、update_ticket、done_ticket などのセッション後の呼び出しをディスパッチしません。

ticket_id なしでセッション後のエンドポイントが呼び出された場合、通常は次のいずれかの条件を示します。

インスタンス構成でチケット検索が無効になっています。これは、一般的な汎用 API 設定では一般的ではありません。
ペイロードテンプレートで ticket_id 変数が省略されています。これは、調査が必要な構成の問題です。

エンドポイントへの影響

セッション後の呼び出しで ticket_id が欠落している場合は、想定される動作として無視するのではなく、調査に値する構成シグナルとして扱います。
構成でチケットの検索が意図的に不要な場合は、ticket_id の欠落を適切に処理するようにセッション後のエンドポイントを構成します。たとえば、問題をログに記録して何もしないか、クラッシュするのではなく、明確で構造化されたエラーメッセージを返します。

再試行とバックオフの動作

再試行は次の 3 つのレイヤで行われます。

HTTP レベルの即時再試行（2 回目の試行をすぐに実行）。
アダプタレベルの再試行（ネットワーク障害と特定の一時的なレスポンスの高速復旧）。
コマンドレベルの再試行（数日間にわたるロングテール再試行）。

HTTP レベルの即時再試行（クイック再試行）

特定の過渡的なステータスの場合、プラットフォームは合計 2 回（最初の試行 1 回 + 即時の再試行 1 回）試行します。これは通常、次のエラーステータスに適用されます。

408、413、429、500、502、503、504、521、522、524

注: 400、401、403、404 などのステータスは、この即時 HTTP レイヤでは再試行されません。

アダプターレベルの再試行（高速ネットワーク復旧）

HTTP 呼び出しとコマンドレベルのスケジュールの間に、CRM アダプタ（command_runner.js）の中間再試行レイヤが、HTTP レスポンスをまったく生成しない障害や、特定の一時的なメッセージに一致する障害を処理します。

即時再キューイング: TCP / ソケットレベルのエラー（ECONNRESET、ENOTFOUND、ESOCKETTIMEDOUT、ETIMEDOUT、ECONNREFUSED、EHOSTUNREACH、EPIPE、EAI_AGAIN）によってトリガーされます。これらは、HTTP レスポンスが受信される前に発生するネットワーク障害です。
30 秒遅延の再試行: エラーメッセージが "Too Early"（HTTP 425）、"Service Unavailable"、または "Unordered Collection" の場合にトリガーされます。
このレイヤで再試行できないもの: その他はすべて、コマンドレベルの再試行スケジュール（レイヤ 3）にフォールスルーされます。

インテグレーターにとって重要な理由

これらのエラーは、プラットフォームがエンドポイントへの TCP 接続を確立または維持できない場合に発生します。つまり、内部インフラストラクチャだけでなく、サーバーの問題（サーバーのダウン、接続の拒否、リクエスト中の接続の切断）を示していることがよくあります。実際には、一部のネットワーク障害は 7 日間のコマンドレベルのスケジュールよりもはるかに早く（多くの場合、数秒以内に）復旧します。

コマンドレベルの再試行（約 7 日間、14 回の試行）

オペレーションが失敗し、再試行できる場合、プラットフォームは次のスケジュールを使用して、約 7 日間に最大 14 回再試行することがあります。

  10s → 1m → 5m → 30m → 1h → 6h → 6h → 12h → 1d → 1d → 1d → 1d → 1d → 1d

このロングテール再試行動作は、以下に適用できます。

アカウント運用。
オペレーションを記録する。
セッション後のオペレーション。

再試行できないエラー

一部の障害は、再試行不可として扱われます。次に例を示します。

構成または検証の失敗（たとえば、必要なエンドポイントが構成されていない、または構成が間違っている）。
プラットフォームによって検出された特定の内部エラーカテゴリ。

障害を永続的なものとして扱う（再試行しない）必要がある場合は、サポートまたは実装チームに連絡して、特定のセットアップで再試行不可能な障害を示す正しい方法を確認してください。

タイムアウトとネットワーク障害

このプラットフォームは、次の 2 つの異なるパスを処理します。

アプリケーションレベルのタイムアウト: 構成された HTTP タイムアウトを超えると（リクエストは送信されたがレスポンスが受信されなかった場合）、プラットフォームは内部エラーを発生させます。このエラーはコマンドレベル（レイヤ 3）で再試行できます。つまり、リクエストは標準のバックオフスケジュール（約 7 日間で最大 14 回の再試行）に従います。
TCP / ソケットレベルのエラー: HTTP レスポンスが受信される前にネットワークレベルで接続が失敗した場合（ETIMEDOUT、ESOCKETTIMEDOUT、ECONNREFUSED など）、アダプタレイヤ（レイヤ 2）がこれらをキャッチし、コマンドをすぐに再キューイングします。これらの障害からの復旧は通常、はるかに高速です。多くの場合、7 日間のスケジュールではなく、数秒以内に復旧します。

この区別が重要な理由

アプリケーションタイムアウト（サーバーが接続を受け入れたが、時間内に応答しなかった）は、より遅いペースで再試行されます。
ネットワークレベルのエラー（サーバーにまったくアクセスできない）の場合は、再試行がはるかに速くなります。
どちらの場合も、リクエストが部分的に処理されている可能性があるため、エンドポイントはべき等である必要があります。復元力のあるエンドポイントの構築（べき等性と設計のヒント）をご覧ください。

ステータスコードとタイムアウト動作のマトリックス（例を含む）

次の表と例は、CCAI Platform がさまざまな HTTP ステータスコード、タイムアウト、ネットワーク障害を処理する方法を示しています。

結果の概要表

次の表の ID 関連の行は、レスポンスから ID を抽出するように構成されたエンドポイント（ルックアップエンドポイントや作成エンドポイントなど）にのみ適用されます。他のほとんどのエンドポイントは、レスポンス ID の抽出を行いません。

結果	例	HTTP の即時再試行	ロングテール再試行（約 7 日間）？	下流への影響
ID 抽出エンドポイントの成功	`2xx` + 構成済みのレスポンスの場所に存在する想定される ID。	いいえ	いいえ	ダウンストリームは、抽出された ID を使用して処理を続行します。
一致しないルックアップ	`2xx` ですが、構成された場所にレコードが見つかりません。	いいえ	いいえ	通常の「見つかりません」という動作。`skip_account_creation` または `skip_record_creation` が有効になっている場合、ダウンストリームは意図的に null ID で処理を続行します。
ID なしでリピーターの `2xx` を作成する	`2xx`（作成エンドポイントから）。ただし、構成された場所に新しいレコードの ID がありません。	いいえ	いいえ	ダウンストリームは、データが欠落した状態で続行される可能性があります。構成またはレスポンス契約の問題として扱います。
ID 抽出エンドポイント以外からの成功	`2xx`: ID を抽出しないメモ、更新、添付ファイルのアクションなどのエンドポイントから。	いいえ	いいえ	ダウンストリームは、コマンドチェーンとインスタンス構成に従って処理されます。
一時的なエラー	`408`、`413`、`429`、`500`、`502`、`503`、`504`、`521`、`522`、`524`	はい（合計 2 回試行）	多くの場合、はい	再試行が行われている間、ダウンストリームステップが遅延する可能性があります。
その他のエラー	`400`、`401`、`403`、`404`、その他の `4xx` / `5xx`。	いいえ	多くの場合、はい	再試行が行われている間、ダウンストリームステップが遅延する可能性があります。
構成 / 検証の失敗	エンドポイントの欠落などです。	なし	いいえ	構成によっては、チェーンが停止したり、部分的に完了したりすることがあります。
ネットワークレベルの障害（TCP / ソケット）	`ECONNRESET`、`ENOTFOUND`、`ESOCKETTIMEDOUT`、`ETIMEDOUT`、`ECONNREFUSED`、`EHOSTUNREACH`、`EPIPE`、`EAI_AGAIN`。	なし	いいえ（アダプタレイヤ 2 で処理）	アダプタはすぐに再キューイングします。通常、復元は高速です（数秒）。ダウンストリームのステップが一時的に遅延する可能性があります。
アプリケーションレベルのタイムアウト	`HTTP timeout exceeded`（応答なし）。	なし	多くの場合「はい」（レイヤ 3）	コマンドレベルの再試行が発生している間、ダウンストリームステップが遅延する可能性があります。

最小限の汎用 API 構成を使用した実際の例

チェーンによって実行される 3 つのエンドポイント（連絡先の検索または作成、チケットの検索または作成、セッション後のコメント）を含む、ベースラインのカスタム CRM 汎用 API 設定。これを出発点として使用し、CRM の仕様に合わせて調整してください。

インスタンスレベルの設定

{
  "lookup_method": "genericApi",
  "auth_method": "basic",
  "basic_auth_username": "ccai-integration",
  "basic_auth_password": "<secret>",
  "api_request_timeout": 10,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}",
  "contact_lookup_url": "https://crm.example.com/api/contacts/{ACCOUNT_ID}",
  "skip_account_lookup": false,
  "skip_account_creation": false,
  "skip_record_creation": false
}

レスポンスの形状

CRM のレスポンスの形式は、お客様によって異なります。response_data_location は、解析されたレスポンス本文内の関連オブジェクトに到達する lodash スタイルのパスです。レスポンスを最上位の data フィールドでラップする必要はありません。次の例は、デフォルトで現実的なフラットな形状を示しています。

たとえば、data.contact の下にリソースをネストする CRM では、response_data_location: "data.contact" と { "contact": { "id": "c_99812" } } のレスポンス本文を設定します。構成の残りの部分は変更されません。

エンドポイント 1 - `contact_find_endpoint`

電話番号またはメールアドレスで連絡先を検索します。

{
  "request_url": "https://crm.example.com/api/contacts/search?phone={PHONE_NUMBER}&email={EMAIL}",
  "request_method": "GET",
  "request_parameters": {},
  "response_data_location": "data"
}

成功: 連絡先が見つかりました

200 OK
Content-Type: application/json
{ "id": "c_42018", "first_name": "Jane", "last_name": "Doe" }

連絡先が見つかりませんでした

404 Not Found

プラットフォームは 404 を「見つかりません」（エラーではありません）として扱います。skip_account_creation が false の場合、フローは contact_create_endpoint に進みます。

代替の「見つかりません」パターン: これも有効

200 OK
{}

一部の CRM では、一致するレコードがない場合に、404 ではなく空のデータを含む 200 OK が返されます。プラットフォームは両方を同等に処理します。どちらも次のステップ（有効になっている場合は作成）をトリガーします。

一時的な障害

503 Service Unavailable
}

レイヤ 1 の即時 HTTP 再試行をトリガーします（合計 2 回試行）。それでも失敗する場合は、レイヤ 3 のコマンドレベルの再試行にフォールスルーします。

エンドポイント 2 - `contact_create_endpoint`

連絡先を作成します。custom_id_location フィールドは、レスポンス内で新しい連絡先の ID を見つける場所をプラットフォームに指示します。

{
  "request_url": "https://crm.example.com/api/contacts",
  "request_method": "POST",
  "request_parameters": {
    "first_name": "{FIRST_NAME}",
    "last_name": "{LAST_NAME}",
    "email": "{EMAIL}",
    "phone": "{PHONE_NUMBER}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

作成に成功

201 Created
{ "id": "c_99812", "first_name": "John", "last_name": "Doe" }

2xx だが、構成されたロケーションに ID がない

200 OK
{}

エンドポイントは、構成されたロケーションに id がない 200 OK を返しました。プラットフォームは警告をログに記録し、null の contact_id をダウンストリームに転送します（例外はスローされず、再試行も行われません）。これは構成上の問題として扱ってください。response_data_location と custom_id_location は、エンドポイントがこのパスから返す 2xx の ID を確実に生成する必要があります。

エンドポイント 3 - `case_create_endpoint`

チケットを作成します。前のステップの contact_id は {ACCOUNT_ID} として使用できます。

{
  "request_url": "https://crm.example.com/api/cases",
  "request_method": "POST",
  "request_parameters": {
    "subject": "{TICKET_SUBJECT}",
    "description": "{TICKET_DESCRIPTION}",
    "contact_id": "{ACCOUNT_ID}",
    "channel": "{CHANNEL}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

作成に成功

201 Created
{ "id": "case_77103", "status": "new" }

response_data_location: "data" を使用すると、プラットフォームは解析されたレスポンス本文へのパスを解決します。次に、custom_id_location: "id" → ticket_id = "case_77103" のフィールドを読み取り、セッション後にフローします。

エンドポイント 4 - `case_comment_endpoint`

このエンドポイントは、通話またはチャットの終了後に、セッションの概要コメントをチケットに追加します。RECORD_ID 変数は、ステップ 3 で生成された ticket_id を保持します。

{
  "request_url": "https://crm.example.com/api/cases/{RECORD_ID}/comments",
  "request_method": "POST",
  "request_parameters": {
    "body": "{COMMENT_BODY}",
    "agent_email": "{AGENT_EMAIL}",
    "channel": "{CHANNEL}",
    "duration": "{CALL_DURATION}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  }
}

case_lookup_url が構成された一般的な API インスタンスの場合、チケット作成ステップが正常に完了するまで、プラットフォームはこのエンドポイントをディスパッチしません。そのため、ここで RECORD_ID がない場合は、一時的な状態ではなく、構成の問題を意味します。

バリエーション: アカウント作成が無効

この例は、最小限の汎用 API 構成の前の例とよく似ていますが、この例では、インスタンスで CRM での連絡先の作成が許可されていません。アカウントの検索は実行されますが、作成は実行されません。

インスタンス設定の変更

{
  "skip_account_creation": true,
  "skip_account_lookup": false
}

インスタンス設定の変更には、次の動作が含まれます。

アカウントステップでは contact_find_endpoint のみが呼び出されます。連絡先が見つからない場合、contact_create_endpoint は呼び出されません。
レコードステップは null の contact_id を受け取ります。プラットフォームは contact_id なしでチケットの作成に進みます。{ACCOUNT_ID} は空に解決され、contact_id フィールドは case_create_endpoint ペイロードから完全に削除されます。
つまり、チケット作成エンドポイントは、この構成で contact_id を使用せずにチケットを作成できる必要があります。CRM でチケットごとに関連付けられた連絡先が必要な場合、この構成は互換性がありません。

`case_create_endpoint` の防御パターン

contact_id がないと、CRM には発信者に関するコンテキストが通常よりも少なくなります。=DEFAULT_VALUE ヘルパーを使用すると、リクエストで利用可能な識別情報をキャプチャし、フォールバックシグナルとして渡すことができます。

"request_parameters": {
  "subject": "{TICKET_SUBJECT}",
  "contact_id": "{ACCOUNT_ID}",
  "contact_origin": "=DEFAULT_VALUE(\"{EMAIL}\", \"{PHONE_NUMBER}\", \"anonymous\")"
}

=DEFAULT_VALUE ヘルパーは、最初の空でない値を選択します。そのため、CRM は、メールアドレスまたは電話番号が利用可能な場合はそれを受け取り、どちらも利用できない場合はリテラル文字列 "anonymous" のみを受け取ります。これは、識別可能な連絡先情報が添付されていないチケットにフラグを付けるのに役立ちます。

バリエーション: 検索のみのチケットフロー（レコード作成なし）

アカウントのオペレーションは通常どおり実行されますが、チケットの作成は無効になります。この統合では、ルックアップによって表示された既存のチケットにのみコメントが添付されます。

インスタンス設定の変更

{
  "skip_record_creation": true,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}"
}

変更内容は次のとおりです。

記録ステップでは、case_find_endpoint を呼び出し、返されたチケットを使用します。チケットが見つからない場合、チェーンはレコードステップで停止し、case_create_endpoint は呼び出されません。
セッション後のエンドポイント（case_comment_endpoint、case_update_endpoint など）は、チケットが正常に検索された場合にのみディスパッチされます。Rails 側の ready? ガードにより、ticket_id が実体化されない場合、これらのコマンドはキューに格納されたままになります（最終的に期限切れになります）。
実用的な意味: この構成では、セッション後のエンドポイントは、既知のチケットに関連付けられたセッションのみを受け取ります。"missing ticket_id" ブランチを処理する必要はありません。

推奨されるべき等性キーの実践

プラットフォームは、SESSION_TYPE と SESSION_ID の両方をテンプレート変数として公開します。複合キーパターンを適用する最もクリーンな方法は、関連するすべてのリクエスト本文に直接組み込むことです。これにより、エンドポイントは、追加のロジックなしで、正規キーを操作できます。

"request_parameters": {
  "...your fields...": "...",
  "ccai_session_key": "{SESSION_TYPE}-{SESSION_ID}"
}

同じ呼び出しの場合、チェーン内のすべてのエンドポイント（アカウント > 記録 > セッション後）の再試行はすべて同じ ccai_session_key を生成します。CRM の作成または upsert ロジックで重複除去アンカーとして使用します。たとえば、（ccai_session_key、endpoint_kind）の upsert は、重複レコードを生成せずに再試行を安全に吸収します。

復元性に優れたエンドポイントの構築（べき等性と設計のヒント）

リクエストは繰り返される可能性があるため（即時再試行 + 数日間にわたる再試行）、エンドポイントはべき等である必要があります。

安定した複合インタラクション識別子をべき等キーとして使用します。
- セッションタイプとセッション ID を組み合わせます（例: call-12345、chat-12345）。
- call_id または chat_id のみに依存しないでください。各シーケンスは 1 から始まるため、音声 ID とチャット ID が重複する可能性があります。
重複していると思われるリクエストを受け取った場合:
- ペイロードを調べて、本当に重複しているかどうかを判断します。コメントエンドポイントやメモエンドポイントなどの一部の共有エンドポイントは、複数のコマンドタイプで使用できます。
- 作成オペレーションの場合、通常の成功条件では重複リクエストは発生しませんが、CRM がリクエストを処理した後、プラットフォームが成功レスポンスを受信する前にエラーが返された場合やタイムアウトが発生した場合は、重複リクエストが発生する可能性があります。
- 重複する作成リクエストが確認された場合は、別のレコードではなく、以前に作成されたレコード ID を返します。
存在しない ID を明示的に処理する:
- チケット作成時に contact_id がない場合は、通常、アカウントの検索またはアカウントの作成が無効になっている構成であることを示します。インスタンスでアカウントが必要な場合は、連絡先なしでチケットをサイレント作成するのではなく、調査してください。
- チケット検索が構成されている一般的な汎用 API 設定では、セッション後の呼び出しで ticket_id が欠落することは想定されていません。リクエストを通常の no-op として処理する前に、チケット検索の構成とペイロードテンプレートを確認してください。
更新の場合は、カウンタをインクリメントするのではなく、フィールドを特定の値に設定することをおすすめします。これにより、繰り返し呼び出しが安全になります。

トラブルシューティングとオブザーバビリティ

カスタム CRM 統合をデバッグする場合は、次のパターンに注意してください。

同じエンドポイントへの繰り返しの呼び出し:
- コマンドレベルの再試行（約 7 日間、14 回の試行）の再試行スケジュールとタイムスタンプを比較します。
- セッションタイプ + 通話またはチャットセッション ID などの複合セッション識別子を使用して、イベントを関連付けます。
- CCAI Platform からエクスポートされたログは、トレーサビリティのために API イベントとともに通話またはチャットのセッション ID を表示するのに役立ちます。
- エンドポイントが、再試行できない構成エラーではなく、再試行可能なエラー（500 など）を常に返しているかどうかを確認します。
「停止しない」再試行:
- エンドポイントから返されるエラーレスポンスを調べます。
- 永続的な失敗を意図している場合は、構成で再試行不可能なエラーを示す方法について、サポートにお問い合わせください。
エンドポイントが呼び出されませんでした。
- 次のことを検証する。
  - アップストリームの手順（アカウント / レコード）が正常に完了し、必要な ID が生成された。
  - エンドポイントが正しく構成され、カスタム CRM 設定で有効になっている。
- エンドポイントの構成ミスや無効化、またはチェーンの初期段階での障害により、特定のステップが実行されないことがあります。
ログの関連付け:
- インタラクション ID（call_id / chat_id）を含む、完全なリクエストとレスポンスを記録します。
- この ID を使用して、CRM ログとプラットフォームの動作を時間の経過とともに（特に再試行中に）関連付けます。

カスタム CRM（汎用 API）でのエラー処理、再試行、呼び出しの順序 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

大まかな実行順序と関係

重要なニュアンス: 2xx + ID 抽出エンドポイントに ID がない

ID 抽出エンドポイントで ID が欠落している場合の影響

インテグレーター向けガイダンス

エラー処理: 概要

チェーンルールと依存関係ルール

アカウントの障害がレコード オペレーションに与える影響

エンドポイントへの影響

記録の失敗がセッション後のアクションに与える影響

エンドポイントへの影響

再試行とバックオフの動作

HTTP レベルの即時再試行（クイック再試行）

アダプターレベルの再試行（高速ネットワーク復旧）

インテグレーターにとって重要な理由

コマンドレベルの再試行（約 7 日間、14 回の試行）

再試行できないエラー

タイムアウトとネットワーク障害

この区別が重要な理由

ステータス コードとタイムアウト動作のマトリックス（例を含む）

結果の概要表

最小限の汎用 API 構成を使用した実際の例

インスタンス レベルの設定

レスポンスの形状

エンドポイント 1 - contact_find_endpoint

成功: 連絡先が見つかりました

連絡先が見つかりませんでした

代替の「見つかりません」パターン: これも有効

一時的な障害

エンドポイント 2 - contact_create_endpoint

作成に成功

2xx だが、構成されたロケーションに ID がない

エンドポイント 3 - case_create_endpoint

作成に成功

エンドポイント 4 - case_comment_endpoint

バリエーション: アカウント作成が無効

インスタンス設定の変更

case_create_endpoint の防御パターン

バリエーション: 検索のみのチケットフロー（レコード作成なし）

インスタンス設定の変更

推奨されるべき等性キーの実践

復元性に優れたエンドポイントの構築（べき等性と設計のヒント）

トラブルシューティングとオブザーバビリティ

カスタム CRM（汎用 API）でのエラー処理、再試行、呼び出しの順序

重要なニュアンス: `2xx` + ID 抽出エンドポイントに ID がない

アカウントの障害がレコードオペレーションに与える影響

ステータスコードとタイムアウト動作のマトリックス（例を含む）

インスタンスレベルの設定

エンドポイント 1 - `contact_find_endpoint`

エンドポイント 2 - `contact_create_endpoint`

エンドポイント 3 - `case_create_endpoint`

エンドポイント 4 - `case_comment_endpoint`

`case_create_endpoint` の防御パターン