Chat API 레퍼런스

인증

모든 요청은 X-API-Key 헤더(또는 api_key 파라미터)로 전송되는 워크스페이스 API 키로 인증됩니다. 키는 ck_live_... 형태입니다. 키는 비밀번호처럼 취급하세요 - 키를 가진 사람은 누구나 귀하의 워크스페이스에 청구되는 메시지를 보낼 수 있습니다. 설정 -> API 액세스에서 언제든지 키를 교체할 수 있으며, 이전 키는 즉시 작동을 멈춥니다.

메시지 전송

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

파라미터:

• message (문자열) - 방문자 메시지. files가 첨부되지 않은 경우 필수입니다.
• ticket_id (문자열, 선택) - 기존 대화를 이어갑니다. 생략하면 새 대화를 시작합니다.
• visitor_email / visitor_name (문자열, 선택) - 티켓에 연락처 정보를 첨부합니다.
• files (multipart, 선택) - 방문자 첨부 파일. 파일 업로드를 지원하는 플랜이 필요합니다.

응답

메시지가 저장되는 즉시 호출은 202 Accepted를 반환합니다. AI 응답은 비동기로 생성됩니다.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

대화를 계속하려면 다음 호출에서 data.ticket_id를 ticket_id로 다시 전달하세요. AI 응답을 받으려면 data.id를 키로 하는 채널을 WebSocket(ActionCable)으로 구독하세요 - 이는 임베디드 위젯이 사용하는 것과 동일한 방문자 해시입니다.

대화 읽기

동일한 X-API-Key로 티켓과 해당 메시지를 가져옵니다. 모든 읽기 엔드포인트는 워크스페이스로 범위가 제한되며 Business 플랜에서 사용할 수 있습니다.

• GET /api/v1/chat/tickets - 티켓을 최신순으로 나열합니다. 쿼리 파라미터: status, limit(최대 100), offset. tickets와 pagination을 반환합니다.
• GET /api/v1/chat/tickets/:id - 단일 티켓.
• GET /api/v1/chat/tickets/:id/messages - 티켓의 메시지를 순서대로 가져오며, 각 메시지에는 role, content, attachments가 포함됩니다.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

속도 제한 및 할당량

요청은 키당(그리고 IP당) 대략 분당 20회로 제한됩니다. 생성되는 각 응답은 플랜의 월별 메시지 허용량에서도 차감됩니다. 허용량이 소진되면 엔드포인트는 응답을 생성하지 않고 data.limit_reached: true와 함께 200을 반환합니다.

오류

• 401 - API 키가 제공되지 않았습니다.
• 404 - 키가 어떤 워크스페이스와도 일치하지 않습니다(예: 교체 후).
• 403 plan_upgrade_required - 워크스페이스가 Business 플랜이 아닙니다.
• 403 - 구독이 비활성 상태이거나, 위젯 설정에서 허용되지 않은 도메인에서 온 요청입니다.
• 422 - 메시지가 없습니다(그리고 첨부된 파일도 없습니다).