연동 문서

걸이 부착

웹사이트에 고객 지원 위젯을 통합하려면 단 한 줄의 코드만 추가하면 됩니다.

임베딩 코드 가져오기

로그인한 뒤 채널 설정 → 임베딩 코드 에 접속하여, 자신만의 코드를 복사하세요:

<script>
  window.$aicrs = window.$aicrs || { q: [] };
</script>
<script async src="https://고객의_도메인/widget/loader.js" data-wk="고객의 widget_key"></script>

이 코드를 웹사이트의 각 페이지에 </body> 태그 이전에 붙여넣으세요. 위젯은 페이지 오른쪽 하단에 채팅 버블 형태로 표시되며, 방문자가 클릭하면 상담이 시작됩니다.

도메인 허용 목록

위젯 도용을 방지하기 위해, 위젯은 등록된 도메인에서만 작동합니다. 채널 설정 → 도메인 허용 목록 에 웹사이트의 도메인을 추가하세요 (여러 도메인을 등록할 수 있음). 등록되지 않은 도메인에서는 위젯이 무음 실패하며, 페이지에는 영향을 주지 않습니다.

widget_key 재설정

key가 유출되었을 경우를 대비해, 채널 설정에서 재설정이 가능합니다. 재설정 시 이전 key는 즉시 무효화되며, 웹사이트에 있는 임베딩 코드도 동기화하여 업데이트해야 합니다.

자주 묻는 질문

• 위젯이 표시되지 않나요? 현재 도메인이 허용 목록에 있는지, widget_key가 관리자 화면과 일치하는지, 계정이 서비스 기간 내에 있는지 확인하세요.
• 웹사이트 속도에 영향을 줄까요? 로더의 크기는 1KB 미만이며 비동기로 로드되므로, 페이지 렌더링을 방해하지 않습니다.

회원 연결 확인

사용자가 웹사이트에 로그인한 후, identify를 호출하여 회원 정보를 전달하면 고객 지원 시스템이 해당 브라우저의 세션을 해당 회원 명의로 합칩니다. — 상담원은 직접 회원 신분을 확인할 수 있으며, 여러 장치에서의 액세스도 동일한 방문자로 통합됩니다.

호출 방법

웹 페이지에서 사용자가 로그인한 후 호출하십시오:

$aicrs.identify({
  externalId: 'U10086',      // 필수, 귀하 시스템 내의 유저 고유 식별자
  name: '리 여사',             // 선택, 표시 이름
  phone: '138****0000',      // 선택
  email: 'user@example.com', // 선택
  hash: '서버에서 계산한 HMAC 서명',  // 필수, 위변조 방지
  custom: { vip: 'gold' }     // 선택, 추가 필드, 상담원 측에서 확인 가능
})

서명 알고리즘

hash는 반드시 귀하의 서버에서 계산해야 합니다 (widget_secret은 프론트엔드 코드에 나타나서는 안 됩니다):

hash = HMAC-SHA256(widget_secret, externalId) 의 16진수 소문자

widget_secret은 상점 뒷면 → 채널 설정 → 임베디드 코드에서 확인할 수 있으며, widget_key와 함께 재설정됩니다.

Node.js 예시:

const crypto = require('crypto')
const hash = crypto.createHmac('sha256', WIDGET_SECRET).update(externalId).digest('hex')

검증 결과

서명 검증에 성공한 방문자는 상담원 측에서 "확인됨" 아이콘으로 표시됩니다. 검증에 실패한 경우 identify 호출은 무시되고 익명 상태를 유지하며, 페이지 작동을 방해하는 오류는 발생하지 않습니다.

웹후크 이벤트 전송

시스템은 주요 비즈니스 이벤트 발생 시, 설정한 콜백 주소로 JSON 메시지를 푸시하여 고객 서비스 데이터를 자체 시스템에 동기화하는 데 도움을 드립니다.

설정

상인 관리자 → 데이터 및 시스템 → Webhook: 콜백 URL(HTTPS 필수)과 서명 키 secret을 입력하고, 구독할 이벤트 유형을 선택합니다. 저장 후 "테스트 이벤트 보내기"를 클릭하여 즉시 연동할 수 있습니다.

요청 형식

각 푸시는 하나의 POST 요청입니다:

POST 귀하의 콜백 URL
Content-Type: application/json
X-AICRS-Event: 이벤트 유형
X-AICRS-Signature: HMAC-SHA256(secret, 요청 본문) 16진수 소문자

요청 본문 구조:

{
  "event": "message.created",
  "tenant_id": 129,
  "timestamp": 1784500000,
  "data": { "객체 스냅샷": "..." }
}

이벤트 유형

서명 검증 및 재시도

푸시를 받은 후에는 secret을 사용하여 원본 요청 본문으로 HMAC-SHA256을 계산하고, X-AICRS-Signature와 비교하세요. 일치하지 않으면 무시해야 합니다.

귀하의 인터페이스가 2xx를 반환하면 성공으로 간주됩니다. 실패 시 1분 / 5분 / 15분 간격으로 총 3회 재시도하며, 계속 실패하면 실패 상태로 설정됩니다. 관리자 뒷면의 투달 기록에서 실패 원인을 확인하고 수동으로 조사할 수 있습니다.

오픈 API

오픈 API는 귀하의 시스템에서 고객 지원 데이터를 읽고, 티켓을 생성하며, 상인 간의 격리를 제공합니다.

인증

상인 백오피스 → 데이터 및 시스템에서 API Key를 생성합니다(예: ak_로 시작하며, 생성 시점에만 평문으로 한 번 표시되므로, 주의 깊게 보관하시기 바랍니다. 재설정 시 이전 Key는 즉시 무효화됩니다).

모든 요청은 요청 헤더를 포함시켜야 합니다:

Authorization: Bearer ak_YOUR_KEY

요청 제한

각 Key는 60초 내 최대 120회 요청이 가능하며, 이 이상 초과 시 429를 반환합니다.

인터페이스 목록

예시:

curl -H "Authorization: Bearer ak_xxx" \
  "https://your-support-domain.com/api/open/v1/conversations?page=1"

설명

• 모든 응답은 JSON 형식이며, 목록 인터페이스는 page 페이징 파라미터를 지원합니다.
• 현재 버전에서는 API를 통해 방문자에게 메시지를 전송할 수 없습니다.
• 상인 계정이 비활성화되거나 서비스 기간이 만료되면 API 역시 함께 중지됩니다.

오류 코드 대응표

모든 인터페이스의 오류 응답은 JSON 구조로 통일됩니다:

{ "code": "오류 코드", "message": "중국어 안내" }

HTTP 상태 코드와 code의 대응 관계:

처리 권장 사항:

• 401/403: Key가 유효한지, 계정 서비스 상태를 확인하세요.
• 429: Retry-After 또는 백오프 전략에 따라 나중에 재시도하세요.
• 5xx: 등멱성 인터페이스는 안전하게 재시도 가능; 등멱성이 아닌 작업은 먼저 조회하여 확인한 후 재시도하세요.

CRM 오픈 인터페이스

고객 및 기회 데이터의 읽기/쓰기는 오픈 API(/api/open/v1, Bearer ak_ 키, 상인 관리자 측 "데이터 및 시스템 → API"에서 생성)를 통해 이루어집니다.

고객

중복 제거 규칙은 관리자 측과 동일합니다: external_id > 휴대전화 > 이메일, 일치하면 기존 고객으로 병합하고 중복 등록하지 않습니다.

제한: 각 Key는 60초당 120회, 초과 시 429를 반환합니다.

고객 이벤트 푸시

고객 라이프사이클 이벤트는 기존 Webhook 경로(상인 백오피스 "데이터 및 시스템 → Webhook" 구독)를 통해 전달되며, 서명 및 재시도 메커니즘은 메시지 이벤트와 동일합니다(X-AICRS-Signature HMAC-SHA256, 지수 백오프 재시도).

페이로드 형식: {"event":"customer.created","data":{...고객 객체...},"ts":1690000000}. 2xx를 반환하면 확인됩니다. 2xx가 아님 또는 타임아웃 발생 시 백오프 전략에 따라 재시도됩니다.