APIリファレンス
Asyntai REST APIでカスタム連携を構築
有料プランが必要: APIアクセスはStarter、Standard、およびProプランで利用可能です。 料金を見る
概要
The Asyntai API allows you to integrate AI-powered customer support into any application. Send messages and receive intelligent responses grounded in your website content and knowledge base.
認証
すべてのAPIリクエストにはAPIキーによる認証が必要です。APIキーはAPI設定ページから取得できます。
以下のいずれかの方法でAPIキーをリクエストに含めてください:
- Authorizationヘッダー(推奨):
Authorization: Bearer YOUR_API_KEY - X-API-Keyヘッダー:
X-API-Key: YOUR_API_KEY
APIキーは安全に保管してください。 キーを持っている人は誰でもAPIを通じてアカウントにアクセスできます。クライアントサイドのコードに公開しないでください。
ベースURL
https://asyntai.com/api/v1/
エンドポイント
POST /chat/
メッセージを送信してAI生成の回答を受け取る。
リクエストボディ
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
message |
文字列 | はい | AIに送信するユーザーのメッセージ |
session_id |
文字列 | いいえ | 会話の一意の識別子です。同じsession_idを使用して会話履歴を維持できます。 |
website_id |
整数 | いいえ | 特定のウェブサイトID。指定しない場合は、プライマリウェブサイトが使用されます。 |
レスポンス
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
例(cURL)
curl -X POST https://asyntai.com/api/v1/chat/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What are your business hours?", "session_id": "user_123"}'
例(Python)
import requests
response = requests.post(
"https://asyntai.com/api/v1/chat/",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"message": "What are your business hours?",
"session_id": "user_123"
}
)
data = response.json()
print(data["response"])
例(JavaScript)
const response = await fetch("https://asyntai.com/api/v1/chat/", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
message: "What are your business hours?",
session_id: "user_123"
})
});
const data = await response.json();
console.log(data.response);
GET /websites/
アカウントに関連するすべてのウェブサイトを一覧表示。
レスポンス
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
例(cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"
POST /websites/
Create a new AI agent. This does the same thing as adding a website in your dashboard: it makes the agent, reads your site, and writes the first draft of the AI instructions.
Use this to set up customers from your own software. You get back the widget ID and the code to put on the website.
リクエストボディ
| フィールド | タイプ | 説明 |
|---|---|---|
domain |
文字列 | Required. The website address, for example example.com |
name |
文字列 | Optional. A display name for the agent. Useful when one website has several agents. |
crawl |
boolean | Optional, true by default. Set it to false to create the agent without reading the website. Nothing is crawled and no instructions are written. |
force |
boolean | Optional, false by default. Set it to true to add a website you already have. The copy is stored with a number after it. |
レスポンス
{
"success": true,
"website": {
"id": 42,
"domain": "example.com",
"name": "Support agent",
"widget_id": "asyntai_ab12cd34ef56",
"is_primary": true,
"crawl_started": true,
"instructions_status": "generating",
"job_id": "8f2c1e90-..."
},
"embed_code": "<script>...</script>"
}
例(cURL)
curl -X POST https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain": "example.com", "name": "Support agent"}'
Reading a website takes a few minutes, so this call answers straight away. Check when the agent is ready with the next endpoint.
Errors
| Code | Meaning |
|---|---|
403 |
You have reached the number of websites your plan allows. The answer tells you the limit. |
409 |
Your account already has this website. Send force as true to add it again. |
GET /websites/{id}/
Get one website and see whether it is ready. Use this after you create an agent, to wait until the website has been read and the AI instructions are written.
レスポンス
{
"success": true,
"website": {
"id": 42,
"domain": "example.com",
"name": "Support agent",
"widget_id": "asyntai_ab12cd34ef56",
"is_primary": true,
"created_at": "2026-08-11T09:12:00+00:00",
"ready": true,
"instructions": {
"status": "completed",
"has_instructions": true,
"characters": 3421
},
"crawl": {
"job_id": "8f2c1e90-...",
"status": "completed",
"pages_crawled": 47,
"pages_found": 50,
"max_pages": 50,
"completed_at": "2026-08-11T09:15:31+00:00",
"error": ""
},
"knowledge_items": 47
},
"embed_code": "<script>...</script>"
}
The ready field is true when nothing is still running. A crawl that failed also counts as ready, because it has finished. Look at the crawl status to see what happened.
例(cURL)
curl https://asyntai.com/api/v1/websites/42/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET PATCH /websites/{id}/settings/
Read or change the chat widget settings for one website. These are the same settings you see on the Customize page: colours, the name of the assistant, the first message, lead capture, and everything else.
Reading the settings
A GET request returns every setting with its current value, plus a locked list. Locked shows the settings your plan cannot change, and which plans they need.
{
"success": true,
"settings": {
"ai_support_name": "AI Assistant",
"widget_color": "#6366f1",
"initial_message": "Hi, how can I help you?",
"hide_branding": false,
"...": "..."
},
"locked": {
"hide_branding": ["pro", "enterprise"],
"widget_style": ["pro", "enterprise"]
}
}
Changing the settings
A PATCH request changes only the settings you send. Everything you leave out stays as it is.
curl -X PATCH https://asyntai.com/api/v1/websites/42/settings/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ai_support_name": "Ava", "widget_color": "#0f172a", "use_emoji": true}'
{
"success": true,
"updated": ["ai_support_name", "use_emoji", "widget_color"],
"settings": { "...": "..." },
"locked": { "...": "..." }
}
Plans
Each setting needs its own plan, the same as in the dashboard. For example, hiding the Asyntai branding needs the Pro plan, and voice input needs Standard.
| Plan needed | 設定 | Examples |
|---|---|---|
| Any paid plan | 25 | widget_color, ai_support_name, initial_message |
| Starter以上 | 22 | profile_picture, conversation_starters_enabled |
| Standard以上 | 25 | speech_to_text_enabled, image_vision_enabled, escalation_enabled |
| Pro | 6 | hide_branding, widget_style |
If you send a setting your plan does not allow, the whole request is refused with code 403 and nothing is saved. The same happens if any value is wrong, for example a colour that is not a hex code. Your settings never end up half changed.
GET PUT /websites/{id}/instructions/
Read or replace the AI instructions for one website. These are the rules that tell the assistant who it is, what it may say, and what it must not say. They are the same instructions you edit in the dashboard.
Reading
{
"success": true,
"instructions": "You are the support agent for Acme Tools...",
"characters": 1979,
"version": 7,
"mode": "instructions",
"ask_questions": true,
"generation_status": "completed",
"being_edited_by": null
}
Replacing
A PUT request replaces the whole text, the same as saving in the dashboard. There is no append mode. To add a paragraph, read the instructions, add your text, then write it back.
curl -X PUT https://asyntai.com/api/v1/websites/42/instructions/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"instructions": "You are the support agent for Acme Tools...", "version": 7}'
リクエストボディ
| フィールド | タイプ | 説明 |
|---|---|---|
instructions |
文字列 | Required. The complete new text. It replaces everything that was there. |
version |
number | Optional but recommended. The version you read. If somebody changed the instructions since then, your write is refused instead of overwriting their work. |
mode |
文字列 | Optional. Either instructions or general. |
ask_questions |
boolean | Optional. Whether the assistant asks a follow-up question at the end of its answers. |
force |
boolean | Optional, false by default. Needed only when your new text is less than half the length of the current text. |
How your instructions are protected
Instructions can take hours to write, so a write can be refused to protect them:
| Code | Meaning |
|---|---|
400 |
Your new text is less than half the length of the current text. This catches a script that sends empty or cut-off text over instructions somebody spent hours on. Send force as true if you meant it. |
409 |
The instructions changed after you read them. Read them again, apply your change, then write. |
423 |
Somebody is editing the instructions in the dashboard right now. The answer tells you who. Try again in a couple of minutes. |
Every change also saves a copy of the previous text, so an earlier version can always be restored from the dashboard.
GET /conversations/
特定のセッションの会話履歴を取得。
クエリパラメータ
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
session_id |
文字列 | はい | 履歴を取得するセッションID |
limit |
整数 | いいえ | 返すメッセージの最大数(デフォルト: 50、最大: 100) |
レスポンス
{
"success": true,
"session_id": "user_123",
"messages": [
{
"role": "user",
"content": "What are your business hours?",
"timestamp": "2024-01-15T10:30:00Z"
},
{
"role": "assistant",
"content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"timestamp": "2024-01-15T10:30:01Z",
"sender_type": "ai",
"agent_name": null,
"response_time_ms": 1840.5
}
]
}
質問とその回答は 1 件のレコードに保存されるため、どちらも同じ timestamp を持ちます。応答の速さを測るために一方から他方を引かないでください。結果は必ずゼロになります。回答にかかった実際の時間をミリ秒で示す response_time_ms を使用してください。
sender_type は、チャットボットが回答した場合は ai、担当者がチャットを引き継いだ場合は human になります。agent_name にはその担当者の表示名が入ります。
例(cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
最近のチャットセッション一覧を取得します。セッションIDを確認し、/conversations/に渡して完全なメッセージ履歴を取得できます。
クエリパラメータ
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
limit |
整数 | いいえ | 返す最近のセッションの数(デフォルト: 20、最大: 100) |
website_id |
文字列 | いいえ | 特定のウェブサイトIDでセッションをフィルタリングします |
source |
文字列 | いいえ | セッションソースでフィルタリング: widget、api、whatsapp、instagram、messenger、gorgias、freshchat、zapier |
レスポンス
{
"success": true,
"sessions": [
{
"session_id": "session_abc123def",
"source": "widget",
"message_count": 5,
"first_message": "What are your business hours?",
"first_message_at": "2024-01-15T10:30:00Z",
"last_message_at": "2024-01-15T10:35:00Z",
"first_response_time_ms": 1840.5,
"first_human_response_at": null,
"started_at": "2024-01-15T10:29:58Z",
"ended_at": "2024-01-15T10:41:12Z",
"taken_over_at": null,
"website_domain": "example.com"
}
]
}
レポート用のタイムスタンプ項目
| フィールド | 説明 |
|---|---|
started_at |
訪問者がチャットを開いた時刻です。ウィジェットのセッションでのみ利用できます。API で作成したセッションはウィジェットを開かないためです。 |
first_message_at |
会話の最初のメッセージが保存された時刻です。 |
first_response_time_ms |
最初の回答にかかった時間をミリ秒で示します。初回応答時間にはこの値を使用してください。 |
first_human_response_at |
担当者が最初の返信を送信した時刻です。チャットボットが会話全体を処理した場合は null になります。 |
taken_over_at |
担当者がチャットボットからチャットを引き継いだ時刻です。 |
last_message_at |
会話の最後のメッセージが保存された時刻です。 |
ended_at |
訪問者がチャットを離れた時刻です。チャットには解決済みや終了という状態はありません。訪問者はいつでも戻って別の質問ができるためです。 |
すべてのタイムスタンプは UTC で、ISO 8601 形式です。タイムゾーンは変更できません。値はご自身のレポートツールで変換してください。
例(cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
収集したリードを取得 — チャット会話中に訪問者が送信したメールアドレスと電話番号。
クエリパラメータ
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
limit |
整数 | いいえ | 返すリード数(デフォルト: 50、最大: 100) |
website_id |
文字列 | いいえ | 特定のウェブサイトIDでリードをフィルタリング |
レスポンス
{
"success": true,
"leads": [
{
"session_id": "session_abc123def",
"email": "[email protected]",
"phone": "+1234567890",
"page_url": "https://example.com/pricing",
"started_at": "2024-01-15T10:30:00Z"
}
]
}
| フィールド | タイプ | 説明 |
|---|---|---|
session_id |
文字列 | チャットセッションID。完全なチャット履歴を表示するには、これを/conversations/に渡してください。 |
email |
文字列またはnull | 訪問者が提供したメールアドレス、収集されなかった場合はnull |
phone |
文字列またはnull | 訪問者が提供した電話番号、収集されなかった場合はnull |
page_url |
文字列またはnull | 訪問者がチャットしていたページのURL |
started_at |
文字列 | チャットセッション開始のISO 8601タイムスタンプ |
例(cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
例(Python)
import requests
response = requests.get(
"https://asyntai.com/api/v1/leads/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"limit": 20}
)
leads = response.json()["leads"]
for lead in leads:
print(f"{lead['email'] or ''} | {lead['phone'] or ''}")
GET /account/
アカウント情報と使用状況の統計を取得します。
レスポンス
{
"success": true,
"account": {
"email": "[email protected]",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
例(cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
複数のウェブサイトをお持ちですか? ナレッジベースのエンドポイントはプライマリウェブサイトがデフォルトです。複数のウェブサイトをお持ちの場合は、 website_id を渡して特定のウェブサイトを対象にします。ウェブサイトIDは次を使用して確認できます GET /websites/.
1日のアップロード上限: ナレッジベースのアップロード(テキスト、URL、スプレッドシート)には、プランに基づく1日の文字数制限があります。これはすべてのナレッジベースエンドポイントを通じてアップロードされた1日の合計コンテンツに適用されます。
| プラン | 文字/日 |
|---|---|
| Starter | 300,000 |
| Standard | 1,500,000 |
| Pro | 6,000,000 |
GET /knowledge/
ナレッジベースのエントリ一覧を取得します。これらはAIチャットボットが質問に回答するために使用するコンテンツソースです。
クエリパラメータ
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
limit |
整数 | いいえ | 返すエントリ数(デフォルト:50、最大:100) |
website_id |
文字列 | いいえ | ウェブサイトIDでフィルタ(デフォルトはプライマリウェブサイト) |
レスポンス
{
"success": true,
"entries": [
{
"id": "abc-123-def",
"type": "text",
"title": "Business Hours",
"description": "Manual text content (150 words)",
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "ghi-456-jkl",
"type": "url",
"title": "About Us - Example",
"description": "Content from https://example.com/about",
"created_at": "2024-01-14T09:00:00Z"
}
]
}
例(cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
ナレッジベースにカスタムテキストコンテンツを追加します。AIはこれを使用して訪問者の質問に回答します。
リクエストボディ
{
"title": "Return Policy",
"content": "We offer a 30-day return policy on all items. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
"website_id": "123"
}
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
title |
文字列 | はい | このナレッジエントリのタイトル |
content |
文字列 | はい | テキストコンテンツ(最小10文字) |
website_id |
文字列 | いいえ | 対象ウェブサイト(デフォルトはプライマリウェブサイト) |
レスポンス
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
例(cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/text/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Return Policy", "content": "We offer a 30-day return policy..."}'
POST /knowledge/url/
ナレッジベースにウェブページを追加します。コンテンツは自動的に取得・抽出されます。
リクエストボディ
{
"url": "https://example.com/faq",
"website_id": "123"
}
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
url |
文字列 | はい | コンテンツを取得するURL |
website_id |
文字列 | いいえ | 対象ウェブサイト(デフォルトはプライマリウェブサイト) |
レスポンス
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
例(cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/url/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/faq"}'
POST /knowledge/spreadsheet/
CSVまたはExcel(.xlsx)スプレッドシートをナレッジベースにアップロードします。各行が個別のナレッジエントリになり、商品カタログ、FAQリスト、料金表、ディレクトリに最適です。
リクエスト
multipart/form-data(ファイルアップロード)として送信してください。JSONではありません。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
file |
ファイル | はい | .csvまたは.xlsxファイルです。最初の行は列ヘッダーである必要があります。アップロードあたりの最大行数:Starter 500行、Standard 2,000行、Pro 10,000行。超過した行は切り捨てられます。 |
website_id |
文字列 | いいえ | 対象ウェブサイト(デフォルトはプライマリウェブサイト) |
レスポンス
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
例(cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "[email protected]"
GET /knowledge/{id}/
ナレッジベースの 1 件のエントリを、保存されているテキストとあわせて読み取ります。id の値は GET /knowledge/ のレスポンスから取得します。
コンテンツが返されるのは、お客様が追加したエントリです。テキスト、ファイル、スプレッドシート、単一の URL、動画が対象です。ウェブサイトのクロールは一覧に表示されますが、そのページは返されません。取得元がお客様自身の公開ウェブサイトであるためです。その場合、content は null になり、reason フィールドが理由を示します。
レスポンス
{
"success": true,
"id": "abc-123-def",
"type": "text",
"title": "Business Hours",
"description": "Manual text content (150 words)",
"created_at": "2024-01-15T10:30:00Z",
"chunks_count": 3,
"content": "We are open Monday to Friday, 9am to 5pm...",
"content_available": true,
"char_count": 43
}
例(cURL)
curl "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
DELETE /knowledge/{id}/
ナレッジベースのエントリを削除します。idはGET /knowledge/のレスポンスから取得できます。
レスポンス
{
"success": true,
"message": "Knowledge base entry deleted"
}
例(cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
ヒント: webhookは以下からも管理できます: API設定 ページからコードなしで管理できます。
GET /webhooks/
登録済みのwebhook一覧を取得します。
レスポンス
{
"success": true,
"webhooks": [
{
"id": "abc-123-def",
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"is_active": true,
"created_at": "2024-01-15T10:30:00Z"
}
]
}
例(cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
リアルタイムのイベント通知を受信するための新しいwebhookを登録します。
利用可能なイベント
| イベント | 説明 |
|---|---|
message.received |
訪問者がメッセージを送信し、応答を受信しました |
conversation.started |
新しいチャットセッションが開始されました |
escalation.requested |
AIがオペレーターへのエスカレーションをトリガーしました |
takeover.started |
オペレーターがチャットセッションを引き継ぎました |
リクエストボディ
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
url |
文字列 | はい | webhook POSTリクエストを受信するHTTPS URL |
events |
配列 | はい | サブスクライブするイベントのリスト(上記の表を参照) |
website_id |
文字列 | いいえ | 対象ウェブサイト(デフォルトはプライマリウェブサイト) |
レスポンス
{
"success": true,
"webhook": {
"id": "abc-123-def",
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"secret": "whsec_abc123...",
"created_at": "2024-01-15T10:30:00Z"
}
}
webhookの検証: 各webhookには secret secret(作成時のみ表示)が含まれます。URLへのすべてのPOSTには X-Webhook-Signature ヘッダー — シークレットキーで署名されたリクエストボディのHMAC-SHA256です。
例(cURL)
curl -X POST "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/webhook", "events": ["message.received"]}'
DELETE /webhooks/{id}/
webhookを削除します。idはGET /webhooks/のレスポンスから取得できます。
レスポンス
{
"success": true,
"message": "Webhook deleted"
}
例(cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
エラーレスポンス
すべてのエラーレスポンスは以下の形式に従います:
{
"success": false,
"error": "Error message describing what went wrong"
}
| ステータスコード | 説明 |
|---|---|
400 |
Bad Request - 無効なパラメータまたは必須フィールドの欠落 |
401 |
Unauthorized - 無効または欠落したAPIキー |
429 |
Too Many Requests - プランのメッセージ上限に達しました |
503 |
Service Unavailable - AIサービスが一時的に利用できません |
レート制限
APIの使用はサブスクリプションプランによって制限されます:
- Free: 100メッセージ/月
- Starter($39/月): 2,500メッセージ/月
- Standard($139/月): 15,000メッセージ/月
- Pro($449/月): 50,000メッセージ/月
お困りですか?
ご質問や問題がございましたら、[email protected]までお問い合わせください。