開発者API

究極の開発者 API ガイド

このドキュメントは、Chirps AI プラットフォーム全体の公式の包括的な API リファレンスです。システム全体にわたって、開発者にとって安全なエンドポイントをすべて計画しました。ダッシュボードの機能の 100% をプログラムでヘッドレスで複製できます。

Developer API

1. 認証とコア原則

ベースURL: https://chirps.cc

すべてのAPIエンドポイントは、AuthorizationヘッダーにChirps APIキーを必要とします。APIキーは、ダッシュボードの開発者セクションにあるAPIマネージャーから生成できます。

http

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

リクエスト例:

bash

curl -X GET https://chirps.cc/api/billing/usage \
  -H "Authorization: Bearer <YOUR_CHIRPS_API_KEY>" \
  -H "Content-Type: application/json"

標準的なエラー処理

ステータスコード	説明
`200 OK`	リクエストは成功しました。
`400 Bad Request`	JSONペイロードの検証に失敗しました。詳細配列が含まれます。
`401 Unauthorized`	トークンが不足しているか、期限切れです。
`402 Payment Required`	ワークスペースが請求制限に達しました。
`403 Forbidden`	ユーザーに必要なRBAC権限がありません。
`404 Not Found`	要求されたリソースは存在しません。
`500 Server Error`	予期せぬプラットフォームエラーです。

Developer API

2. アシスタントのライフサイクル（作成）

GET /api/assistants

アシスタントの一覧表示

APIキーのワークスペースに関連付けられたすべてのアシスタントのリストを取得します。

アシスタントの作成

POST /api/assistants

すべての基本設定を持つ新しいアシスタントを作成します。

json

{

  "businessName": "Acme Corp",
  "businessUrl": "https://acme.com",
  "knowledgeBaseType": "both",
  "knowledgeBaseUrl": "https://acme.com/help",
  "knowledgeBaseText": "Raw text content of a document...",
  "knowledgeBaseFileName": "company_handbook.pdf",
  "language": "en",
  "isMultiLanguage": false,
  "tonePersonality": "professional",
  "isCustomPersonality": false,
  "supportEmail": "[email protected]",
  "maxPages": 5,
  "maxDepth": 2,
  "welcomeMessageDelay": 2
}

パラメーター	型	必須	説明
`businessName`	String	はい	ビジネス名（2～100文字）。
`businessUrl`	String	はい	ビジネスウェブサイトの有効なURL（最大500文字）。
`knowledgeBaseType`	Enum	はい	次のいずれか: `"url"`、`"document"`、`"both"`、`"none"`。
`knowledgeBaseUrl`	String	いいえ	タイプが`"url"`または`"both"`の場合に指定する必要があります。
`knowledgeBaseText`	String	いいえ	タイプが`"document"`または`"both"`の場合の生テキスト。
`knowledgeBaseFileName`	String	いいえ	テキストを提供する場合は、アップロードされたファイルの名前。
`language`	String	はい	言語コード（例: `"en"`、`"es"`）。
`isMultiLanguage`	Boolean	いいえ	自動翻訳を有効にします。デフォルトは`false`です。
`tonePersonality`	String	はい	例: `"professional"`、`"friendly"`。最大100文字。
`isCustomPersonality`	Boolean	いいえ	カスタムトーンを有効にします。デフォルトは`false`です。
`customPersonalityDescription`	String	いいえ	カスタムトーンが有効な場合の指示（最大2000文字）。
`additionalInstructions`	String	いいえ	コアプロンプトの指示（最大10000文字）。
`supportEmail`	String	はい	エスカレーション用の有効なメールアドレス。
`maxPages`	Number	いいえ	クロールするページ数。最小1、最大100。デフォルトは`5`です。
`maxDepth`	Number	いいえ	クロール深度。最小1、最大20。デフォルトは`2`です。
`welcomeMessageDelay`	Number	いいえ	挨拶までの遅延時間（秒）。最小0、最大6。デフォルトは`2`です。

アシスタントの削除

DELETE /api/assistants/:id

アシスタントを完全に削除し、そのすべてのナレッジノードと履歴を連鎖的に削除します。ペイロードは不要です。

Developer API

3. アシスタント分析と統計

アシスタントの作成と利用後すぐに、そのパフォーマンス指標をプログラムで取得できます。

GET /api/analytics/overview?assistantId=uuid&range=30

指定されたアシスタントの利用統計、総メッセージ数、獲得リード数、および一般的なエンゲージメント指標を取得します。range パラメータはオプションです（日数、最小7日、最大365日、デフォルト30日）。

期待されるレスポンス

json

{

  "totalConversations": 1245,
  "totalMessages": 8420,
  "totalLeads": 156,
  "totalBookings": 42,
  "satisfactionRate": 94,
  "avgMessagesPerSession": 6.7,
  "avgSessionsPerDay": 41.5,
  "liveNow": 3,
  "onlineNow": 12,
  "dailySeries": [
    {
      "date": "2026-07-15",
      "conversations": 45,
      "messages": 310,
      "leads": 5,
      "bookings": 2
    }
  ],
  "agentStats": [
    {
      "name": "Jane Doe",
      "messagesSent": 120,
      "csat": 98
    }
  ]
}

プロパティ	型	説明
`totalConversations`	数値	アシスタントが処理したチャットセッションの総数。
`totalMessages`	数値	すべての会話で送信されたメッセージ（ユーザー + AI）の総数。
`totalLeads`	数値	抽出されたユニークなリード（名前、メールアドレス、電話番号）の総数。
`totalBookings`	数値	正常に予約されたカレンダーアポイントメントの総数。
`satisfactionRate`	数値	総評価数に対する肯定的なフィードバック評価の割合（0-100）。
`avgMessagesPerSession`	数値	会話あたりの平均メッセージ交換数。
`avgSessionsPerDay`	数値	リクエストされた範囲内での1日あたりの平均会話数。
`liveNow`	数値	現在、人間のエージェントが引き継いでいるアクティブな会話の数。
`onlineNow`	数値	過去2分以内にAIと活発にチャットしているユーザーの数。
`dailySeries`	配列	日付ごとの `conversations`、`messages`、`leads`、`bookings` のカウントを含む日次オブジェクトの配列。
`agentStats`	配列	`messagesSent` および `csat`（顧客満足度スコア）を含む、人間のエージェントのパフォーマンス指標。

Developer API

4. ナレッジとトレーニング

アシスタントが作成されたら、「ナレッジノード」を介してその頭脳を管理します。各ノードは、データのチャンク（クロールされたURL、アップロードされたドキュメント、または手動のテキストスニペット）を表します。

ナレッジノードの管理

GET /api/assistants/:id/nodes - このアシスタントのすべてのナレッジノードを一覧表示します。

POST /api/assistants/:id/nodes - 新しいナレッジブロックを手動で挿入します。

json

{

  "title": "Return Policy",
  "refined_content": "We offer a 30-day return policy for all unused items...",
  "type": "text",
  "metadata": {}
}

PATCH /api/assistants/:id/nodes/:nodeId - 既存のノードのコンテンツを変更するか、そのアクティブ状態を切り替えます。

json

{

  "title": "Updated Return Policy",
  "refined_content": "We offer a 60-day return policy now...",
  "is_active": true
}

DELETE /api/assistants/:id/nodes/:nodeId - ナレッジブロックを完全に削除します。

POST /api/assistants/:id/nodes/:nodeId/re-crawl - スクレイパーにこのノードに関連付けられたURLを再クロールさせ、そのコンテンツを更新するよう強制します。ペイロード: {}。

AIトレーニング

POST /api/assistants/:id/train - すべてのis_activeナレッジノードをコンパイルし、AIオーケストレーターを使用して新しいマスターシステムプロンプトを動的に合成します。ペイロード: {}。

Developer API

5. ウィジェットの外観と設定

アシスタントバブルとチャットウィンドウのフロントエンドUIをカスタマイズします。

ウィジェットの外観を更新

PATCH /api/assistants/:id/widget-config

json

{

  "primaryColor": "#000000",
  "position": "bottom-right",
  "language": "en",
  "welcomeMessage": "Hi! How can I help you today?",
  "title": "Acme Support",
  "theme": "light",
  "fontFamily": "default",
  "bubbleStyle": "circle",
  "bubbleText": "Chat with us",
  "headerSubtitle": "We typically reply instantly",
  "inputPlaceholder": "Type your message...",
  "privacyPolicyUrl": "https://acme.com/privacy",
  "voiceEnabled": true,
  "voiceName": "Fenrir",
  "welcomeMessageDelay": 2,
  "fileUploadEnabled": true,
  "dictationEnabled": true,
  "copilotEnabled": true,
  "welcomeSuggestions": ["Pricing plans", "Contact sales"],
  "pageVisibility": {
    "mode": "all",
    "paths": []
  }
}

パラメーター	型	必須	説明
`primaryColor`	String	No	16進数カラーコード（例: `"#000000"`）。
`position`	Enum	No	`"bottom-right"`、`"bottom-left"`、`"top-right"`、`"top-left"`。
`language`	String	No	ウィジェットの言語コード（例: `"en"`、`"fr"`）。
`welcomeMessage`	String	No	最初の挨拶メッセージ。
`title`	String	No	ウィジェットヘッダーのタイトル。
`theme`	Enum	No	`"light"` または `"dark"`。
`fontFamily`	Enum	No	`"default"` (Inter) または `"inherit"`。
`bubbleStyle`	Enum	No	`"circle"`、`"bar"`、`"drawer"`、`"branded-circle"`、`"branded-bar"`、`"branded-drawer"`。
`bubbleText`	String	No	バブルの横に表示するテキスト（バー/ドロワースタイル用）。
`headerSubtitle`	String	No	ウィジェットヘッダーのサブタイトル。
`inputPlaceholder`	String	No	メッセージ入力のプレースホルダーテキスト。
`privacyPolicyUrl`	String	No	プライバシーポリシーへのURL。
`avatarUrl`	String	No	カスタムアバター画像へのURL。
`customLogoUrl`	String	No	カスタムヘッダーロゴ画像へのURL。
`voiceEnabled`	Boolean	No	音声通話を有効にします。
`voiceName`	String	No	音声応答の音声識別名。利用可能な音声は以下を参照してください。
`welcomeMessageDelay`	Number	No	挨拶までの遅延時間（秒単位）。
`fileUploadEnabled`	Boolean	No	ユーザーが添付ファイルをアップロードできるようにします。
`dictationEnabled`	Boolean	No	音声入力（音声認識）を有効にします。
`copilotEnabled`	Boolean	No	コパイロットの提案チップを有効にします。
`welcomeSuggestions`	Array	No	最初のクイック返信チップ用の文字列の配列。
`pageVisibility`	Object	No	ウィジェットが表示されるページを決定します（`mode`、`paths`）。
`rateLimitEnabled`	Boolean	No	チャットのレート制限を有効にします。デフォルトはtrueです。
`rateLimitMaxMessages`	Number	No	ウィンドウ内の最大メッセージ数。デフォルトは30です。
`rateLimitTimeWindow`	Number	No	時間枠（分単位）。デフォルトは60です。
`gdprDataMaskingEnabled`	Boolean	No	保存前にPIIをマスクします。デフォルトはfalseです。

利用可能な音声名

女性: Zephyr、Aoede、Kore、Leda、Callirrhoe、Despina、Erinome、Laomedeia、Achernar、Pulcherrima、Gacrux、Algenib、Sulafat
男性: Puck、Charon、Fenrir、Orus、Enceladus、Iapetus、Umbriel、Algieba、Autonoe、Rasalgethi、Alnilam

カスタムロゴ

POST /api/assistants/:id/widget-logo

形式: fileフィールドを持つmultipart/form-data。

Developer API

6. 連携とデプロイ

アシスタントの設定とトレーニングが完了したら、主に2つの方法でデプロイできます。

オプションA: ウェブ埋め込み (フロントエンド)

アシスタントを標準的なウェブサイト（WordPress、Shopify、Reactなど）に統合する最も簡単な方法です。埋め込みコードは完全に決定論的です。取得するためのエンドポイントは必要ありません。サイトの<head>にこれを追加するだけです。

json

<script src="https://chirps.cc/widget.js" data-assistant-id="YOUR_ASSISTANT_ID_HERE"></script>

オプションB: ヘッドレス連携 (バックエンド / CRM / ボット)

カスタムクライアント（Discordボット、Telegram連携、ネイティブiOSアプリなど）を構築している場合、ウェブ埋め込みは使用しません。代わりに、/api/chatエンドポイントと直接やり取りします。

POST /api/chat または /api/chat?stream=true

注: このエンドポイントは公開されており、Authorization: Bearer APIキーヘッダーは*不要*です。認証はassistantIdを介して暗黙的に処理されます。

json

{

  "assistantId": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "unique-session-id-for-user",
  "conversationId": "optional-uuid",
  "message": "Hello, I need help with my billing."
}

*(fileUploadEnabledがtrueの場合、添付ファイル用にfileフィールドを持つmultipart/form-dataもサポートします。)*

パラメーター	型	必須	説明
`assistantId`	String	はい	アシスタントのUUID。
`sessionId`	String	はい	ご自身で生成してください。チャット履歴をグループ化するための、ご自身のシステムからのユニークな識別子（例：DiscordユーザーID、TelegramチャットID、またはランダムなUUID）。
`message`	String	はい	メッセージのテキストコンテンツ（最大5000文字）。
`conversationId`	String	いいえ	会話のUUID（最初のリクエストで返されます）。
`id`	String	いいえ	重複排除を防ぐためのオプションのクライアント側メッセージID。

モード1: 標準JSONレスポンス (デフォルト)

/api/chatにPOSTリクエストを送信する（ストリームパラメーターなしで）と、完全なAI応答を待ち、標準のJSONオブジェクトを受け取ります。

json

{

  "message": "Here is the information you requested...",
  "conversationId": "uuid-of-conversation",
  "messageId": "uuid-of-message"
}

*(is_active_agent: trueが返された場合、人間がチャットを引き継いでおり、messageはnullになります。)*

モード2: サーバー送信イベントストリーミング (?stream=true)

URLに?stream=trueを追加すると、リアルタイムのサーバー送信イベント（SSE）ストリームを受信します。コードは以下の特定のイベントタイプをリッスンする必要があります。

`event: token`: {"text": "chunk"}を含みます。AIの応答テキストの各チャンクに対して発火します。
`event: status`: {"text": "Searching knowledge base..."}を含みます。バックエンドツールの実行状態を表します。
`event: done`: {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}を含みます。生成が完全に完了したときに発火します。
`event: error`: {"error": "Error message"}を含みます。レート制限またはエラーが発生した場合に発火します。

ライブ引き継ぎエンドポイント

GET /api/chat/sessions

過去のセッションを取得します。

POST /api/chat/toggle-agent

人間による引き継ぎのためにAIを一時停止します。ペイロード: { "sessionId": "..." }

POST /api/chat/agent-message

人間のメッセージを送信します。ペイロード: { "sessionId": "...", "message": "..." }

Developer API

7. 高度なアシスタント設定

PATCH /api/assistants/:id

コア設定の更新

アシスタントのコア設定、ペルソナ、およびスクレイピング範囲を変更します。

json

{

  "business_name": "Acme Corp",
  "business_url": "acme.com",
  "business_description": "We sell anvils.",
  "system_prompt": "You are a helpful assistant.",
  "language": "en",
  "tone_personality": "Friendly",
  "support_email": "[email protected]",
  "additional_instructions": "Never mention the Roadrunner.",
  "is_multi_language": true,
  "is_dev_mode": false,
  "is_active": true,
  "max_pages": 15,
  "max_depth": 2,
  "widget_config_merge": {
    "rateLimitEnabled": true
  }
}

*注: すべてのフィールドはオプションです。更新したいフィールドのみを送信してください。*

アシスタントの削除

DELETE /api/assistants/:id

アシスタントを完全に削除し、すべてのナレッジノード、会話、メッセージに削除をカスケードします。アシスタントが完全に設定されていなかった場合、月間作成クォータが返金されます。

Developer API

8. 電話機能と音声

GET /api/phone-numbers - 利用可能な番号を一覧表示します。

POST /api/phone-numbers/:id/assign - 番号をプロビジョニングします。 Payload: {}

POST /api/assistants/:id/outbound - 発信をトリガーします。 Payload: { "to": "+123...", "message": "..." }

Developer API

9. リード抽出

GET /api/leads?assistantId=uuid&page=1&limit=50&status=new - AIが会話中に抽出した、ページ分割された構造化リードを取得します。

GET /api/leads?id=leadId - 完全な会話トランスクリプトを含む、単一リードの詳細を取得します。

Developer API

10. 予約とカレンダー

GET /api/bookings?assistantId=uuid&start=ISO-8601&end=ISO-8601 - アシスタントによってスケジュールされたカレンダーの予定を取得します。日付でフィルタリングすることも可能です。

GET /api/bookings?id=bookingId - 会話のトランスクリプトを含む、単一の予約の詳細を取得します。

POST /api/bookings/cancel - アクティブな予約をキャンセルします。ペイロード: { "bookingId": "uuid" }

POST /api/bookings/reschedule - 予約を調整します。ペイロード: { "bookingId": "uuid", "newTime": "ISO-8601" }

Developer API

11. アカウントと請求の使用状況

GET /api/billing/usage

ワークスペースの請求サイクル使用状況、サブスクリプションプランの制限、およびアシスタントの総数を取得します。注: APIキーを使用する場合、リクエストは自動的にAPIキーのワークスペースにスコープされるため、teamIdを提供する必要はありません。

レスポンス (`200 OK`):

json

{

  "planName": "Pro",
  "periodStr": "2023-10-01",
  "assistantCount": 3,
  "usage": {
    "message_count": 1450,
    "harvest_count": 12,
    "recrawl_count": 5,
    "train_count": 2,
    "assistants_created_count": 1,
    "voice_minutes_used": 0,
    "sms_count": 0,
    "email_count": 0,
    "whatsapp_count": 0
  },
  "limits": {
    "messages": 5000,
    "assistants": 5,
    "training": 50,
    "recrawls": 20
  },
  "workspaceOwnerId": "uuid"
}

始める準備はできていますか?

アシスタントを起動する
10分以内に。

サインアップし、サイトでトレーニングし、アラートをカスタマイズし、Web サイトに埋め込みます。

無料のアシスタントを作成する価格を見る

究極の開発者 API ガイド

1. 認証とコア原則

標準的なエラー処理

2. アシスタントのライフサイクル（作成）

アシスタントの一覧表示

アシスタントの作成

アシスタントの削除

3. アシスタント分析と統計

期待されるレスポンス

4. ナレッジとトレーニング

ナレッジノードの管理

AIトレーニング

5. ウィジェットの外観と設定

ウィジェットの外観を更新

利用可能な音声名

カスタムロゴ

6. 連携とデプロイ

オプションA: ウェブ埋め込み (フロントエンド)

オプションB: ヘッドレス連携 (バックエンド / CRM / ボット)

モード1: 標準JSONレスポンス (デフォルト)

モード2: サーバー送信イベントストリーミング (?stream=true)

ライブ引き継ぎエンドポイント

7. 高度なアシスタント設定

コア設定の更新

アシスタントの削除

8. 電話機能と音声

9. リード抽出

10. 予約とカレンダー

11. アカウントと請求の使用状況

アシスタントを起動する10分以内に。

アシスタントを起動する
10分以内に。