API 레퍼런스

Asyntai REST API로 맞춤 통합을 구축하세요

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, 스프레드시트)는 플랜에 따른 일일 문자 수 제한이 적용됩니다. 이는 모든 지식 베이스 엔드포인트에서 하루에 업로드된 총 콘텐츠에 적용됩니다.

플랜 문자/일
Starter100,000
Standard500,000
Pro2,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}/

지식 베이스 항목을 삭제합니다. idGET /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}/

웹훅을 삭제합니다. idGET /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으로 문의하세요.