메인 콘텐츠로 건너뛰기

지원 티켓 핸드오프

SDK 0.16.0부터 사용할 수 있습니다.
Moss 어시스턴트는 대화를 통해 지원 요청 내용을 수집하고, 티켓 초안을 작성해 사용자에게 검토용으로 보여줄 수 있습니다. 사용자가 확인하면 SDK는 승인된 티켓을 여러분의 애플리케이션에 넘기고, 애플리케이션이 자체 백엔드를 통해 티켓을 등록합니다. Moss는 여러분의 티켓팅 시스템 자격 증명을 보유하지 않으며, 요청자 신원은 여러분의 백엔드가 자체 세션에서 붙입니다 — Moss를 거치지 않습니다.
티켓 등록은 어시스턴트가 수집 기준으로 삼는 접수 양식을 포함해 Moss 대시보드에서 애플리케이션별로 설정됩니다. 애플리케이션에 활성화하려면 Moss에 문의하세요.

동작 방식

  1. 수집 — 어시스턴트가 설정된 접수 양식에 맞춰 검증하며 대화에서 티켓 필드를 수집합니다.
  2. 검토 — 위젯이 작성된 티켓을 채팅 내 미리보기 카드로 렌더링합니다. 사용자는 설명을 수정하고 확인하거나 취소할 수 있습니다.
  3. 핸드오프 — 확인 시 SDK가 초기화할 때 등록한 onSupportTicket 콜백을 호출하며, 확인된 티켓과 핸드오프 ID를 전달합니다.
  4. 등록 — 페이지가 두 값을 여러분의 세션 인증 채널을 통해 백엔드로 전달합니다. 백엔드가 요청자를 붙여 티켓을 등록합니다.
  5. 확인 — 콜백이 결과와 함께 resolve됩니다. 어시스턴트는 결과를 사용자에게 보여주며, 티켓 ID를 제공하면 함께 표시합니다.

콜백 등록

onSupportTicket 등록은 기능 지원 신호이기도 합니다. SDK가 세션 초기화 시 이를 보고하며, 백엔드는 콜백을 등록한 세션에만 티켓 등록을 제안합니다. 콜백을 등록하지 않은 페이지에는 완료할 수 없는 플로우가 제안되지 않습니다.
전송은 콜백이 담당합니다. 애플리케이션의 평소 세션 및 CSRF 방식을 그대로 사용하세요. SDK는 여러분의 쿠키를 건드리지 않습니다.

핸드오프

콜백은 SupportTicketHandoff를 전달받습니다: SupportTicketPayload는 Zendesk 티켓 생성 형태를 Zendesk 자체 표기법 그대로 사용하므로, 백엔드에서 변환 없이 요청자를 붙여 그대로 전송할 수 있습니다: 사용자가 지정하지 않은 필드는 빈 값이 아니라 아예 포함되지 않습니다 — Moss는 판단할 수 없는 값을 추측하는 대신 생략합니다.

결과 보고

콜백은 SupportTicketOutcome으로 resolve하세요:
ticketId는 티켓팅 시스템이 반환한 그대로 정수로 넘기거나 텍스트로 넘길 수 있으며, Moss는 이를 텍스트로 기록합니다. Number.MAX_SAFE_INTEGER를 넘는 숫자는 이미 반올림되었을 수 있으므로 Moss는 ID 없이 등록을 기록합니다. 그만큼 큰 ID는 텍스트로 넘기세요. 소수는 어떤 티켓도 가리키지 않으므로 같은 방식으로 버려집니다. 0.16.16 이전 SDK는 ticketId를 string으로 타입 지정하므로, 타입을 쓰는 호스트가 숫자를 반환하려면 해당 버전에서는 타입 캐스트가 필요합니다. 이 resolve 값은 접수 확인이 아니라 티켓의 최종 결과입니다.
  • { ok: true }는 티켓이 실제로 생성된 뒤에만, 백엔드가 티켓을 식별할 수 있다면 ticketId와 함께 반환하세요. 사용자에게 “대신 접수했습니다”라고 표시되는 근거는 이 값 하나뿐입니다.
  • 등록이 실패했거나 거부되었다면 { ok: false }로 반환하세요. errorCode와 errorDetail은 핸드오프 감사 기록에 남으며 사용자에게는 표시되지 않습니다. Moss 0.16.16부터는 둘 중 정수로 보낸 값은 텍스트로 기록되고, 텍스트가 아닌 그 밖의 값은 버려집니다.
  • SDK를 빨리 놓아주기 위해 미리 resolve하지 마세요. 15초가 지나도 대기 중이거나 reject된 콜백은 실패가 아니라 알 수 없음으로 처리됩니다. 백엔드가 실제로 등록했을 수도 있으므로, 카드는 확인 없이 요청이 전달되었다고 사용자에게 알립니다. 뒤늦은 resolve는 무시됩니다.

반복 제출

Moss 0.16.16부터는 백엔드의 결과가 기록되기 전에 사용자가 같은 카드를 다시 제출하면(예: 응답이 유실된 경우), Moss가 이를 받아들여 같은 handoffId로 onSupportTicket을 다시 호출합니다. handoffId로 중복을 제거하면 사용자에게는 티켓이 하나만 생깁니다. 처음 제출과 값이 다른 재제출은 거부되며 콜백에 도달하지 않습니다.
handoffId를 백엔드의 멱등성 키로 취급하세요. 같은 핸드오프가 두 번 도착하면 원래 결과를 반환하고, 한 번의 확인에 대해 두 번째 티켓을 절대 만들지 마세요.

역할 분담

다음 단계

설정

전체 SDK 설정 참조

인증

SDK 세션용 JWT 설정