カスタムインターフェースAPIのウォークスルー
Headless APIエンドポイントは、順番に呼び出されるように設計されています。 会話ライフサイクル内の各リクエストは、前のリクエストで返された識別子に依存します。 このガイドでは、リクエストを連結して完全な会話を管理し、中断を処理し、スキル確認およびランタイムコネクションイベントに応答する方法を示します。
プライベートベータ
Headless APIはプライベートベータ版であり、選ばれたお客様のみが利用できます。 詳しくはCustomer Success Managerにお問い合わせください。
会話ライフサイクルの概要
完全なGenie会話は、次の順序で進行します。
- 会話を作成して
conversation_idを取得します。 conversation_idを使用してメッセージを送信し、Genieの応答をストリーミングします。- スキル確認やランタイムコネクションリクエストなど、ストリーム中に発行されるServer-Sent Events（SSE）を処理します。
- ストリームがクローズする前に切断された場合は、メッセージまたはイベントを取得します。
セッション内の後続の各リクエストは、最初のリクエストで返されたconversation_idに依存します。 セッションの期間中、この値を保持する必要があります。
完全なリクエストチェーン
次の表は、会話セッションのAPI呼び出しの完全な順序をまとめたものです。これには、各リクエストが生成する識別子と、それが次に使用される場所が含まれます。
| ステップ | リクエスト | 生成するもの | 使用者 |
|---|---|---|---|
| 会話を作成 | POST /conversations | conversation_id | 後続の すべてのリクエスト |
| メッセージを送信して応答をストリーミング | POST /messages | genie_run_id | 再接続 エンドポイント |
| ファイルを添付（オプション） | POST /upload | file_id | POST /messages |
| SSE：スキル確認が必要 | POST /skill_approval/:call_id | 解像度 | Genieが再開 |
| SSE：ランタイムコネクション認証が必要 | POST/runtime_connection/:runtime_connection_attempt_id/link | 認証url | ユーザーに提示 |
| ストリームに再接続 | GET/genie-runs/:genie_run_id | 再開された SSE ストリーム | なし |
| 見逃したイベントを手動で取得 | GET / conversations/events | 見逃した イベント | なし |
| 会話履歴を取得 | GET /messages | メッセージ 履歴 | 表示 または監査 |
Headless APIリクエストをチェーン化する方法
Headless APIリクエストをチェーン化するには、次の手順を実行します。
会話を作成
会話を作成
メッセージを送信する前に、会話を作成する必要があります。 このリクエストは、セッション内の後続のすべてのリクエストに渡すconversation_idを返します。
次のリクエストを実行して会話を作成し、conversation_idを取得します。
POST /api/v1/genies/:genie_handle/chat/conversationsメッセージを送信して応答をストリーミング
メッセージを送信して応答をストリーミング
conversation_idを使用してメッセージを送信し、応答をストリーミングします。 Genieがリクエストを処理する際にリアルタイムSSEストリームを受信するには、streamをtrueに設定します。 切断後に再接続する必要がある場合は、応答で返されるgenie_run_idが必要です。
POST /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/messagesメッセージにファイルを添付
添付ファイルを含める予定の場合は、メッセージを送信する前にファイルをアップロードします。 アップロードによって返されたfile_idを、メッセージ送信リクエストのfile_idパラメータに渡します。
POST /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/uploadSSEイベントを処理
SSEイベントを処理
ストリームが開いている間、アプリケーションはイベントをリッスンして応答する必要があります。 一部のイベントでは、Genieが続行する前に即時のアクションが必要です。 その他のイベントは情報提供のみです。
スキル確認が必要
Genieがskill.confirmation_requiredイベントを発行すると、実行を一時停止し、アプリケーションがスキル呼び出しを承認または拒否するのを待ちます。 イベントペイロードにはcall_idが含まれています。 call_idを使用してスキルを承認または拒否します。
POST /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/skill_approval/:call_idランタイムコネクション認証が必要
Genieがruntime_connection.auth_requiredイベントを発行すると、スキルを実行する前にユーザーがコネクションを認証する必要があります。 イベントペイロードにはruntime_connection_attempt_idとauth_linkが含まれています。
runtime_connection_attempt_idを使用して、ユーザーに提示する認証リンクをリクエストします。
POST /api/v1/genies/:genie_handle/chat/runtime_connection/:runtime_connection_attempt_id/link応答はstatusフィールドを返します。 statusがauth_requiredの場合は、認証を完了するためにauth_link.urlをユーザーに提示します。 statusがauthorizedになるまでこのエンドポイントをポーリングします。これはコネクションが完了し、Genieが処理を再開したことを示します。その後、再開された返信をメッセージ履歴から読み取ります。
次のコマンドを使用してコネクションリクエストをキャンセルします。
POST /api/v1/genies/:genie_handle/chat/runtime_connection/:runtime_connection_attempt_id/reject切断から復旧
切断から復旧
Genieがprocessing.finishedを発行する前にSSEストリームが切断された場合は、次のいずれかの復旧方法を使用します。
ストリームに再接続
genie_run_idを使用して、Genie実行のSSEストリームを再度開きます。 見逃したイベントのみを再生するには、最後に正常に受信したイベントのIDをLast-Event-IDヘッダーに渡します。
GET /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/genie-runs/:genie_run_id見逃したイベントを手動で取得
ストリームに再接続できない場合のフォールバックとして、イベント取得エンドポイントを使用します。 イベントは24時間利用できます。 since_created_atパラメータを渡して、最後に正常に受信したイベントの後に発生したイベントのみを取得します。
GET /api/v1/genies/:genie_handle/chat/conversations/events?conversation_id=:conversation_id&since_created_at=:since_created_at会話履歴を取得
会話履歴を取得
会話がクローズした後、conversation_idを使用して会話の完全なメッセージ履歴を取得できます。 ユーザーが既存の会話に戻ったときに以前のメッセージを表示する場合、またはagent.messageイベントを受信する前にストリームがクローズした場合にGenieの最終応答を取得する場合は、次のエンドポイントを使用します。
GET /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/messagesLast updated: