API 문서

REST API · 웹훅 · 위젯 자바스크립트 API

인증

관리자 화면 연동에서 소유자가 API 키를 만듭니다. 모든 요청에 키를 Authorization 헤더로 보내세요. 키는 만들 때 한 번만 보이고, 82talk에는 해시만 저장됩니다.

curl https://82talk.com/api/v1/conversations?status=open \
  -H "Authorization: Bearer t82_xxxxxxxxxxxxxxxx"

키는 그 회사(워크스페이스)의 데이터에만 접근합니다. 서버에서만 쓰고, 브라우저·앱 코드에 넣지 마세요.
요청 한도: 키당 분당 120회. 넘으면 429.
응답은 JSON입니다. 오류는 {"error": "설명"} 과 HTTP 상태(400·401·404·429)로 알려 드립니다.
시각은 모두 UTC ISO 8601 (2026-10-22T01:05:00Z).

엔드포인트

GET/api/v1/sites

등록한 사이트 목록.

GET/api/v1/conversations

상담 목록(최신순). 쿼리: status=open|closed, site_id, limit(1~100, 기본 50), before(다음 쪽: 응답의 next_before).

{
  "data": [{
    "id": 128, "site_id": 3, "site_name": "에이 쇼핑몰", "status": "open",
    "visitor_id": "9f05…", "visitor": { "name": "홍길동", "email": null, "phone": "010-1234-5678" },
    "last_message": "배송 언제 오나요?", "last_at": "2026-10-22T01:05:00Z", "unread": 1,
    "created_at": "2026-10-22T01:04:12Z"
  }],
  "next_before": null
}

GET/api/v1/conversations/:id

상담 하나와 메시지(최근 500개, 오래된 순). 메시지의 sender는 visitor 또는 agent, 첨부파일이 있으면 file에 이름·크기·형식이 담깁니다.

POST/api/v1/conversations/:id/messages

상담원으로 답장을 보냅니다. 방문자 채팅창과 관리자 화면에 바로 나타납니다. agent_name을 비우면 키를 만든 사람 이름으로 보냅니다.

curl -X POST https://82talk.com/api/v1/conversations/128/messages \
  -H "Authorization: Bearer t82_…" -H "Content-Type: application/json" \
  -d '{"body": "주문하신 상품은 오늘 출고됐어요!", "agent_name": "배송팀"}'

POST/api/v1/conversations/:id/close · /reopen

상담을 종료하거나 다시 엽니다.

GET/api/v1/visitors/:site_id/:visitor_id

방문자 정보: 이름·이메일·전화·회원 ID, 보던 페이지, 처음 들어온 곳, 방문·페이지뷰 수, 언어·위치, 팀 메모.

웹훅

연동 → 웹훅에 https 주소를 저장하면 아래 이벤트를 POST로 보내 드립니다. 응답은 5초 안에 2xx로 주세요. 실패해도 다시 보내지 않습니다.

이벤트	언제	data
`conversation.created`	방문자가 새 상담을 시작	conversation
`message.created`	방문자·상담원 메시지 (파일 포함)	conversation, message
`conversation.closed`	상담 종료	conversation
`conversation.reopened`	종료한 상담을 다시 엶	conversation
`ping`	관리자 화면의 [테스트 보내기]	message

모든 요청에는 X-82talk-Event, X-82talk-Timestamp(유닉스 초), X-82talk-Signature: sha256=… 헤더가 붙습니다. 서명은 HMAC-SHA256(비밀값, 타임스탬프 + "." + 본문)입니다. 반드시 확인하고, 5분보다 오래된 요청은 버리세요.

// Node.js (Express) — 본문은 받은 그대로(raw) 써야 서명이 맞습니다
import crypto from 'node:crypto';
app.post('/82talk/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-82talk-Timestamp');
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.T82_WEBHOOK_SECRET).update(`${ts}.${req.body}`).digest('hex');
  const given = req.get('X-82talk-Signature') || '';
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!fresh || given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) return res.sendStatus(401);
  const { event, data } = JSON.parse(req.body);
  // event === 'message.created' → data.message.body …
  res.sendStatus(200);
});

설치 코드를 넣은 페이지에서 Talk82()를 부를 수 있습니다. 설치 코드보다 먼저 불러도 됩니다.

<script>
  window.Talk82 = window.Talk82 || function () { (Talk82.q = Talk82.q || []).push(arguments) };
  // 로그인한 회원 정보를 넘기면 상담원 화면에 이름·이메일이 보이고, 연락처를 다시 묻지 않습니다
  Talk82('boot', { name: '홍길동', email: 'hong@example.com', memberId: 'u_1024' });
</script>

Talk82('open');   // 채팅창 열기
Talk82('close');  // 닫기
Talk82('hide');   // 상담 버튼 숨기기
Talk82('show');   // 다시 보이기