지원 티켓 핸드오프

SDK 0.16.0부터 사용할 수 있습니다.

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

티켓 등록은 어시스턴트가 수집 기준으로 삼는 접수 양식을 포함해 Moss 대시보드에서 애플리케이션별로 설정됩니다. 애플리케이션에 활성화하려면 Moss에 문의하세요.

동작 방식

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

콜백 등록

onSupportTicket 등록은 기능 지원 신호이기도 합니다. SDK가 세션 초기화 시 이를 보고하며, 백엔드는 콜백을 등록한 세션에만 티켓 등록을 제안합니다. 콜백을 등록하지 않은 페이지에는 완료할 수 없는 플로우가 제안되지 않습니다.

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),

  onSupportTicket: async ({ handoffId, ticket }) => {
    const res = await fetch('/api/support/moss-handoff', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ handoffId, ticket }),
    });
    if (!res.ok) {
      return { ok: false, errorCode: `HTTP_${res.status}` };
    }
    const filed = await res.json();
    return { ok: true, ticketId: filed.ticketId, ticketUrl: filed.ticketUrl };
  },
}}>

전송은 콜백이 담당합니다. 애플리케이션의 평소 세션 및 CSRF 방식을 그대로 사용하세요. SDK는 여러분의 쿠키를 건드리지 않습니다.

핸드오프

콜백은 SupportTicketHandoff를 전달받습니다:

필드	타입	설명
`handoffId`	`string`	이 등록 결정을 식별합니다. 결과를 이 값에 대해 보고하고, 이 값으로 중복을 제거해 한 번의 확인이 두 개의 티켓이 되지 않도록 하세요.
`ticket`	`SupportTicketPayload`	사용자가 확인한 그대로 등록할 티켓입니다.

SupportTicketPayload는 Zendesk 티켓 생성 형태를 Zendesk 자체 표기법 그대로 사용하므로, 백엔드에서 변환 없이 요청자를 붙여 그대로 전송할 수 있습니다:

필드	타입	설명
`subject`	`string`	티켓 제목
`comment`	`{ html_body: string }`	HTML 형식의 티켓 설명
`tags`	`string[]`	선택적 태그
`ticket_form_id`	`number`	선택적 양식 ID
`custom_fields`	`Array<{ id: number; value: ... }>`	선택적 커스텀 필드 값

사용자가 지정하지 않은 필드는 빈 값이 아니라 아예 포함되지 않습니다 — Moss는 판단할 수 없는 값을 추측하는 대신 생략합니다.

결과 보고

콜백은 SupportTicketOutcome으로 resolve하세요:

type SupportTicketOutcome =
  | { ok: true; ticketId?: string; ticketUrl?: string }
  | { ok: false; errorCode?: string; errorDetail?: string };

이 resolve 값은 접수 확인이 아니라 티켓의 최종 결과입니다.

{ ok: true }는 티켓이 실제로 생성된 뒤에만, 백엔드가 티켓을 식별할 수 있다면 ticketId와 함께 반환하세요. 사용자에게 “대신 접수했습니다”라고 표시되는 근거는 이 값 하나뿐입니다.
등록이 실패했거나 거부되었다면 { ok: false }로 반환하세요. errorCode와 errorDetail은 핸드오프 감사 기록에 남으며 사용자에게는 표시되지 않습니다.
SDK를 빨리 놓아주기 위해 미리 resolve하지 마세요. 15초가 지나도 대기 중이거나 reject된 콜백은 실패가 아니라 알 수 없음으로 처리됩니다. 백엔드가 실제로 등록했을 수도 있으므로, 카드는 확인 없이 요청이 전달되었다고 사용자에게 알립니다. 뒤늦은 resolve는 무시됩니다.

handoffId를 백엔드의 멱등성 키로 취급하세요. 같은 핸드오프가 두 번 도착하면 원래 결과를 반환하고, 한 번의 확인에 대해 두 번째 티켓을 절대 만들지 마세요.

역할 분담

	Moss	여러분의 애플리케이션
필드 수집 및 검증	✓
사용자 검토 및 확인	✓
백엔드로의 전송		✓
요청자 신원		✓ (자체 세션에서)
티켓팅 시스템 자격 증명		✓ (서버 측, 여러분 소유)
등록 및 중복 제거		✓
사용자에게 결과 표시	✓

시작하기

SDK

대시보드

설정

보안

가이드

리소스

지원 티켓 핸드오프

지원 티켓 핸드오프

동작 방식

콜백 등록

핸드오프

결과 보고

역할 분담

다음 단계

설정

인증

​지원 티켓 핸드오프

​동작 방식

​콜백 등록

​핸드오프

​결과 보고

​역할 분담

​다음 단계

설정

인증

지원 티켓 핸드오프

동작 방식

콜백 등록

핸드오프

결과 보고

역할 분담

다음 단계