Headless API ​

カスタムチャットインターフェースを使用すると、構築および制御する任意のアプリケーションにGenieを接続できます。 アプリケーションは、ユーザーをSlack、Microsoft Teams、またはWorkato GO経由でルーティングするのではなく、Headless APIと呼ばれるREST API経由でGenieと直接通信します。 カスタムチャットインターフェースには、会話を管理し、Genieメッセージを送受信するためのAPIエンドポイントが含まれています。 このAPIは、Genieの作成、設定、および保守を可能にするAgent Studio Developer APIとは別のものです。

Headless APIの前提条件 ​

Headless APIを使用する前に、以下を確認してください:

• Agent StudioにGenieがあること。
• API keyまたはOAuth 2.0（PKCE）資格情報のいずれかを使用してGenieクライアントを作成してアタッチすることを含め、Agent Studio UIからGenieのカスタムチャットインターフェイスを設定していること。 UIからではなくプログラムでクライアントをプロビジョニングする場合は、Developer APIのGenieクライアントを参照してください。
• ワークスペースでHeadless APIが有効になっていること。 Headless APIはプライベートベータです:カスタムチャットインターフェイスオプションがGenieのチャットインターフェイス設定に表示されない場合は、Customer Success Managerに連絡してアクセスをリクエストしてください。
• ビルダーロールに、Genie buildingの下のCustom chat interface権限があること。 ビルダーロールの設定の詳細については、コラボレーター権限を参照してください。

Headless APIのベースURL ​

Headless APIは、Agenticがサポートされているすべてのデータセンターで利用できます。 ベースURLは、アプリホストと同じデータセンターごとのスキームに従います。 例:

詳細については、データセンターの概要を参照してください。

認証 ​

Headless APIは次のアクセス方法をサポートしています。

APIキー:

Authorization: Bearer <api_key>
X-IDP-User-Id: <idp_user_id>

OAuth 2.0（PKCE）:

Authorization: Bearer <access_token>

認可方法の比較 ​

使用する認可方法を決定するには、次の認可方法の比較表とユースケース推奨表を参照してください。

シナリオ別の推奨認可方法 ​

OAuth 2.0 PKCE認証フロー ​

OAuthクライアントは、PKCEを使用した認可コードフローにより、Workato Identity（id.workato.com）を通じてエンドユーザーを認証します。 クライアントシークレットは不要です。 OAuth Genieクライアントを作成したときに返されるoauth_client_idを使用します。

この認可フローを使用するには、次の手順を完了する必要があります:

https://id.workato.com/oauth/authorize?response_type=code
  &client_id=<oauth_client_id>
  &redirect_uri=<your_redirect_url>
  &scope=openid profile email
  &state=<random_state>
  &code_challenge=<code_challenge>
  &code_challenge_method=S256

curl -X POST https://id.workato.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<oauth_client_id>" \
  -d "redirect_uri=<your_redirect_url>" \
  -d "code=<authorization_code>" \
  -d "code_verifier=<code_verifier>"

curl -X POST https://id.workato.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=<oauth_client_id>" \
  -d "refresh_token=<refresh_token>"

リダイレクトURLは、クライアントに登録されているoauth_redirect_urlと一致している必要があります。 前述の手順のコード交換は、ブラウザーで直接実行するのではなく、同一オリジンのバックエンドから実行します。 これにより、フローでクロスオリジン（CORS）の懸念がなくなり、トークン処理をサーバー側に維持できます。

クイックリファレンス ​

会話の一覧表示 ​

認証済みユーザーの会話のリストを取得します。 結果はcreated_atタイムスタンプの降順で一覧表示されます。

GET /api/v1/genies/:genie_handle/chat/conversations

URLパラメータ ​

クエリパラメータ ​

レスポンス ​

会話を作成 ​

Genieとの新しい会話を作成します。

POST /api/v1/genies/:genie_handle/chat/conversations

URLパラメータ ​

レスポンス ​

会話の取得 ​

会話の詳細と現在の状態を取得します。

GET /api/v1/genies/:genie_handle/chat/conversations/:conversation_id

URLパラメータ ​

レスポンス ​

メッセージの取得 ​

会話のメッセージ履歴を取得します。 結果はcreated_atタイムスタンプの降順で一覧表示されます。

GET /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/messages

URLパラメータ ​

クエリパラメーター ​

レスポンス ​

メッセージの送信 ​

ユーザーメッセージを送信し、Genieが処理して応答する際のイベントのリアルタイムストリームを受信します。

POST /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/messages

URLパラメータ ​

ペイロード ​

レスポンス ​

streamがfalseの場合、次の本文を含むHTTP 202を返します。

streamがtrueの場合、レスポンスはServer-Sent Eventsのストリームになります。 Genieが処理を終了するとストリームが閉じます。これはprocessing.finishedイベントで示されます。

ストリームへの再接続 ​

特定のGenie実行のSSEストリームを再度開きます。 切断後にイベントを復旧するにはこれを使用します。 最後に正常に受信したイベントのIDをLast-Event-IDヘッダーで渡します。

GET /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/genie-runs/:genie_run_id

URLパラメータ ​

ヘッダー ​

レスポンス ​

レスポンスはServer-Sent Eventsのストリームです。

イベントの取得 ​

最近のイベントを取得します。 切断後に取りこぼしたイベントを手動で取得するためのフォールバックとして使用します。 イベントは古い順に返され、24時間利用できます。

GET /api/v1/genies/:genie_handle/chat/conversations/events

URLパラメータ ​

クエリパラメータ ​

レスポンス ​

スキルの承認または拒否 ​

スキル確認リクエストを承認または拒否します。 Genieがskill.confirmation_requiredイベントを発行したときに使用します。

POST /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/skill_approval/:call_id

URLパラメータ ​

ペイロード ​

ランタイムコネクションリンクの取得 ​

ランタイムコネクションの認証リンクを取得します。 Genieがruntime_connection.auth_requiredイベントを発行したときに使用します。

POST /api/v1/genies/:genie_handle/chat/runtime_connection/:runtime_connection_attempt_id/link

URLパラメータ ​

レスポンス ​

ランタイムコネクションの拒否 ​

ランタイムコネクションリクエストを拒否します。

POST /api/v1/genies/:genie_handle/chat/runtime_connection/:runtime_connection_attempt_id/reject

URLパラメータ ​

ペイロード ​

ファイルのアップロード ​

後続のメッセージに添付するファイルをアップロードします。 メッセージの送信のfile_idパラメータで渡すfile_idを返します。 最大ファイルサイズは20 MBです。

POST /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/upload

URLパラメータ ​

ペイロード ​

レスポンス ​

SSEイベント ​

stream: trueを指定してメッセージを送信すると、Genieのレスポンスのライフサイクル全体をカバーするSSEストリームを含むレスポンスを取得できます。

イベントは24時間永続化され、イベントの取得エンドポイントを通じて取得できます。

ベースイベント形状 ​

すべてのイベントは次の基本フィールドを共有します。

イベントタイプ ​

制限事項 ​

Headless APIエンドポイントには次の制限があります。

• Action Boardはサポートされていません
• App Eventsはサポートされていません
• Genieは、アタッチされた単一のクライアントをサポートします。 クライアントとGenieの関係は1:1です。2つ目のクライアントをアタッチすると、409競合が返されます。 再ポイントするには、まず既存のクライアントをデタッチします。