iNTELIGENCIA VIVAの上に構築する
公開APIは、開発者がワークスペースの上に構築したいあらゆるものの拡張ポイントです ― 会話を自社システムへルーティングする、顧客のERPに問い合わせるツールをAIエージェントに持たせる、連絡先をCRMへ同期する、あるいはライブイベントを自社ダッシュボードへストリーミングする、といったことです。RESTであり、v1としてバージョン管理され、製品のデータモデルにあるすべてのリソースがこれを通じて到達可能です。
認証
すべてのリクエストは、ワークスペースパネルから発行されたAPIキーで認証され、`Authorization: Bearer sk_live_...`として送信されます。
各キーは独自の設定可能な権限範囲を持ちます ― キーは読み取り専用アクセスに限定したり、特定のリソースに限定したり、あるいは同じワークスペースに発行された他のキーとは独立して、完全な読み書きアクセスを付与したりできます。
キーは作成された瞬間に一度だけ全体が表示されます。その後は所有者だけが再び見ることができ、どのキーも他のキーに影響を与えることなく、パネルから即座に無効化できます。
Authorization: Bearer sk_live_...リソース
基盤となるデータモデルのすべてのリソースがAPIを通じて利用できます:
| Workspace | 全般設定、既定言語、有効化されたチャネル。 |
| Contact | 書き込んでくる最終顧客の作成、検索、参照。 |
| Conversation | 会話の一覧表示、作成、終了、再割り当て。 |
| Message | 会話内でのメッセージの送信と読み取り。 |
| Department | チームとそのルーティングルールの管理。 |
| Agent | 人間のユーザー、役割、部署への所属の管理。 |
| AIAgent | AIエージェントの作成と設定: 指示、ナレッジベース、呼び出し可能なツール。 |
| KnowledgeSource | RAG用のドキュメントとURLのアップロードおよび管理。 |
| Channel | チャネルとその認証情報の設定。 |
| Webhook | HMACで署名された送信イベントの購読。 |
| APIKey | キーの発行と無効化。 |
Webhookイベント
`WebhookEndpoint`を以下のいずれかのイベントに購読させてください。すべての配信は、そのエンドポイントに紐づくシークレットを使ってHMACで署名されるため、内容を信頼する前にそれが私たちから来たものであることを検証できます:
| conversation.created | いずれかのチャネルで新しい会話が開始された。 |
| conversation.assigned | 会話が人間のエージェントまたは部署に割り当てられた。 |
| conversation.resolved | 会話が、AIによってまたは人間によって終了した。 |
| message.received | 連絡先から新しい受信メッセージが届いた。 |
| message.sent | AIまたはエージェントによって、連絡先へメッセージが送信された。 |
| handoff.requested | AIの確信度がワークスペースのしきい値を下回り、人間を要求した。 |
| ai_agent.tool_call | AIエージェントが、設定済みのツールの1つを呼び出した。あなた自身が登録したツールも含みます。 |
配信は失敗時に再試行され、厳密に1回だけの配信は保証されません ― Webhookハンドラーは冪等になるよう設計してください。配信と再試行の完全な仕様は、開発者API利用規約に記載されています。
リアルタイム・ストリーミング
Webhookの代わりに、またはWebhookに加えて、イベントをライブで消費する必要があるインテグレーションのために、すべてのワークスペースはWebSocketストリーミングエンドポイントを公開しています:
wss://api.inteligenciaviva.com/v1/workspaces/{id}/streamレート制限とフェアユース
APIアクセスは、あなたのワークスペースのプランに紐づいたレート制限の対象となります。制限を超えたリクエストにはHTTP 429と現在のレート制限ヘッダーが付されるため、正しくバックオフを実装できます。正確な制限と、APIの利用に関する完全に拘束力のある規約 ― 取得したデータについて何ができて何ができないかを含む ― は、Legalページからリンクされている開発者API利用規約に定められています。