> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viamoss.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 지원 티켓 핸드오프
> 어시스턴트가 작성한 지원 티켓을 애플리케이션이 직접 등록하도록 합니다
# 지원 티켓 핸드오프
SDK 0.16.0부터 사용할 수 있습니다.
Moss 어시스턴트는 대화를 통해 지원 요청 내용을 수집하고, 티켓 초안을 작성해
사용자에게 검토용으로 보여줄 수 있습니다. 사용자가 확인하면 SDK는 승인된 티켓을
**여러분의 애플리케이션**에 넘기고, 애플리케이션이 자체 백엔드를 통해 티켓을
등록합니다. Moss는 여러분의 티켓팅 시스템 자격 증명을 보유하지 않으며, 요청자
신원은 여러분의 백엔드가 자체 세션에서 붙입니다 — Moss를 거치지 않습니다.
티켓 등록은 어시스턴트가 수집 기준으로 삼는 접수 양식을 포함해 Moss
대시보드에서 애플리케이션별로 설정됩니다. 애플리케이션에 활성화하려면 Moss에
문의하세요.
## 동작 방식
1. **수집** — 어시스턴트가 설정된 접수 양식에 맞춰 검증하며 대화에서 티켓 필드를
수집합니다.
2. **검토** — 위젯이 작성된 티켓을 채팅 내 미리보기 카드로 렌더링합니다. 사용자는
설명을 수정하고 확인하거나 취소할 수 있습니다.
3. **핸드오프** — 확인 시 SDK가 초기화할 때 등록한 `onSupportTicket` 콜백을
호출하며, 확인된 티켓과 핸드오프 ID를 전달합니다.
4. **등록** — 페이지가 두 값을 여러분의 세션 인증 채널을 통해 백엔드로 전달합니다.
백엔드가 요청자를 붙여 티켓을 등록합니다.
5. **확인** — 콜백이 결과와 함께 resolve됩니다. 어시스턴트는 결과를 사용자에게
보여주며, 티켓 ID를 제공하면 함께 표시합니다.
## 콜백 등록
`onSupportTicket` 등록은 기능 지원 신호이기도 합니다. SDK가 세션 초기화 시 이를
보고하며, 백엔드는 콜백을 등록한 세션에만 티켓 등록을 제안합니다. 콜백을 등록하지
않은 페이지에는 완료할 수 없는 플로우가 제안되지 않습니다.
```tsx theme={null}
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하세요:
```ts theme={null}
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 설정 참조
SDK 세션용 JWT 설정