API 레퍼런스
Asyntai REST API로 맞춤 통합을 구축하세요
유료 플랜 필요: API 접근은 Starter, Standard 및 Pro 플랜에서 사용할 수 있습니다. 요금제 보기
개요
Asyntai API를 사용하면 AI 기반 고객 지원을 모든 애플리케이션에 통합할 수 있습니다. 메시지를 보내고 웹사이트 콘텐츠와 지식 베이스에 기반한 지능형 응답을 받으세요.
인증
모든 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 |
string | 예 | AI에 보낼 사용자 메시지 |
session_id |
string | 아니오 | 대화의 고유 식별자입니다. 대화 기록을 유지하려면 동일한 session_id를 사용하세요. |
website_id |
integer | 아니오 | 특정 웹사이트 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"
GET /conversations/
특정 세션의 대화 기록을 조회합니다.
쿼리 매개변수
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
session_id |
string | 예 | 기록을 조회할 세션 ID |
limit |
integer | 아니오 | 반환할 최대 메시지 수 (기본값: 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"
}
]
}
예시 (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 |
integer | 아니오 | 반환할 최근 세션 수 (기본값: 20, 최대: 100) |
website_id |
string | 아니오 | 특정 웹사이트 ID로 세션을 필터링 |
source |
string | 아니오 | 세션 소스별 필터링: 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",
"website_domain": "example.com"
}
]
}
예시 (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
수집된 리드 조회 — 채팅 대화 중 방문자가 제출한 이메일 주소 및 전화번호.
쿼리 매개변수
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
limit |
integer | 아니오 | 반환할 리드 수 (기본값: 50, 최대: 100) |
website_id |
string | 아니오 | 특정 웹사이트 ID로 리드 필터링 |
응답
{
"success": true,
"leads": [
{
"session_id": "session_abc123def",
"email": "visitor@example.com",
"phone": "+1234567890",
"page_url": "https://example.com/pricing",
"started_at": "2024-01-15T10:30:00Z"
}
]
}
| 필드 | 유형 | 설명 |
|---|---|---|
session_id |
string | 채팅 세션 ID. 전체 채팅 기록을 보려면 /conversations/에 전달하세요. |
email |
문자열 또는 null | 방문자가 제공한 이메일 주소, 수집되지 않은 경우 null |
phone |
문자열 또는 null | 방문자가 제공한 전화번호, 수집되지 않은 경우 null |
page_url |
문자열 또는 null | 방문자가 채팅하고 있던 페이지 URL |
started_at |
string | 채팅 세션이 시작된 시점의 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": "you@example.com",
"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/.
일일 업로드 제한: 지식 베이스 업로드(텍스트, URL, 스프레드시트)는 플랜에 따른 일일 문자 수 제한이 적용됩니다. 이는 모든 지식 베이스 엔드포인트에서 하루에 업로드된 총 콘텐츠에 적용됩니다.
| 플랜 | 문자/일 |
|---|---|
| Starter | 100,000 |
| Standard | 500,000 |
| Pro | 2,000,000 |
GET /knowledge/
지식 베이스 항목을 나열합니다. AI 챗봇이 질문에 답변하는 데 사용하는 콘텐츠 소스입니다.
쿼리 매개변수
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
limit |
integer | 아니오 | 반환할 항목 수 (기본값: 50, 최대: 100) |
website_id |
string | 아니오 | 웹사이트 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 |
string | 예 | 이 지식 항목의 제목 |
content |
string | 예 | 텍스트 콘텐츠 (최소 10자) |
website_id |
string | 아니오 | 대상 웹사이트 (기본값: 기본 웹사이트) |
응답
{
"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 |
string | 예 | 콘텐츠를 가져올 URL |
website_id |
string | 아니오 | 대상 웹사이트 (기본값: 기본 웹사이트) |
응답
{
"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 |
file | 예 | .csv 또는 .xlsx 파일. 첫 번째 행은 열 헤더여야 합니다. 업로드당 최대 행 수: Starter 500, Standard 2,000, Pro 10,000. 초과 행은 잘립니다. |
website_id |
string | 아니오 | 대상 웹사이트 (기본값: 기본 웹사이트) |
응답
{
"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 "file=@products.csv"
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"
팁: 다음에서 웹훅을 관리할 수도 있습니다 API 설정 코드 작성 없이 페이지에서 관리할 수 있습니다.
GET /webhooks/
등록된 웹훅을 나열합니다.
응답
{
"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/
실시간 이벤트 알림을 받기 위한 새 웹훅을 등록합니다.
사용 가능한 이벤트
| 이벤트 | 설명 |
|---|---|
message.received |
방문자가 메시지를 보내고 응답을 받았습니다 |
conversation.started |
새 채팅 세션이 시작되었습니다 |
escalation.requested |
AI가 상담원에게 에스컬레이션을 요청했습니다 |
takeover.started |
상담원이 채팅 세션을 인계받았습니다 |
요청 본문
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
url |
string | 예 | 웹훅 POST 요청을 받을 HTTPS URL |
events |
array | 예 | 구독할 이벤트 목록 (위 표 참조) |
website_id |
string | 아니오 | 대상 웹사이트 (기본값: 기본 웹사이트) |
응답
{
"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"
}
}
웹훅 검증: 각 웹훅에는 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}/
웹훅을 삭제합니다. 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건 메시지
도움이 필요하신가요?
질문이 있거나 문제가 발생하면 hello@asyntai.com으로 문의하세요.