만들게 될 것
- 메신저 채널: 카카오, 네이버톡톡, 인스타그램 같은 채널이나 직접 만든 채팅 API 화면이에요.
- vox.ai 에이전트: 고객에게 먼저 답하고, 상담사가 필요하다고 판단하면
transfer도구를 호출해요. - 고객사 서버:
transfer요청을 받아 상담사에게 넘기고, 채팅 웹훅으로 새 메시지를 받아요. vox.ai API를 호출해요. - 상담 화면: 상담사가 대기 중인 채팅을 확인하고 이어받아 답장하는 고객사 화면이에요.
대시보드에서 먼저 해 보기
코드 없이 이어받기부터 해 보세요. 워크스페이스 멤버라면 누구나 할 수 있고, 모든 채널에서 같아요. 다른 상담사가 이미 맡은 채팅은 이어받을 수 없어요.1
진행 중인 채팅 열기
기록의 채팅 탭에서 상태를 진행 중으로 고르고 채팅을 누르세요.
2
이어받고 답장하기
상세 아래 입력칸에서 이어받기를 누르세요. 그 뒤 고객 메시지에는 AI가 답하지 않아요. 답장을 쓰고 보내기를 누르면 고객 메신저로 전달돼요. 채팅 API로 만든 채팅은 대화록에만 저장되니, 고객 화면에서 대화록을 다시 불러와 보여 주세요.
3
AI 응대로 복귀하거나 끝내기
AI 응대 복귀를 누르면 다음 고객 메시지부터 AI가 답해요. 상담을 마치려면 대화 종료를 누르세요.
응답 담당이 바뀌는 방식
채팅마다 현재 응대를 맡는 응답 담당이 정해져 있어요. 값은 채팅 조회 API의responder.type이고, agent는 AI 에이전트, operator는 상담사예요.
응답 담당이
operator인 동안 고객 메시지는 저장만 되고 AI가 답하지 않아요. 상담사가 맡은 채팅은 대화가 오래 없어도 자동으로 끝나지 않아요. 카카오처럼 채널이 상담을 끝내는 경우는 채널별로 다른 점을 보세요.
AI 에이전트가 상담사를 부르는 순서는 이래요.
이어받기가 AI 답변보다 먼저 끝나면 그 차례에 AI가 만든 답변과 도구 호출 기록은 저장되거나 전송되지 않아요. 그래서 고객에게 보일 연결 안내는 고객사 서버가 이어받은 직후 직접 보내야 해요.
직접 만들기
모든 요청은 고객사 서버에서 워크스페이스 API 키로 보내요. 주소는https://client-api.tryvox.co/v3예요.
transfer 도구 만들기
API 도구를 하나 만들어 에이전트에 연결하세요. 헤더의{{chat_id}}, {{chat_turn_id}}는 vox.ai가 현재 채팅과 처리 중인 고객 메시지 값으로 채워요. 아래 본문으로 도구 생성 API를 호출하거나, 대시보드 구축 > 도구에서 같은 값으로 만드세요.
auth_credentials에는 vox.ai API 키가 아니라 고객사 서버가 도구 요청을 확인할 별도의 비밀 값을 넣으세요.
프롬프트에 호출 조건 적기
에이전트 프롬프트에transfer를 호출할 조건을 적으세요.
도구 요청 받기
고객사 서버가 도구 요청을 받으면 이어받기, 대기 목록 등록, 연결 안내 순서로 처리한 뒤 응답하세요. 안내가 실패해도 대기 건은 남기고 실패를 대기 건에 표시하세요. 응답하기 전에 이어받아야 AI 답변과 연결 안내가 겹쳐 나가지 않아요. 같은 차례의 요청이 다시 와도 한 번만 처리되도록chat_turn_id로 키를 만드세요.
is_open_now(), enqueue_waiting_chat(), mark_notice_failed()는 고객사 상담 시간과 상담 화면 저장소에 맞게 직접 구현하세요. 상담 시간이 아닐 때처럼 이어받지 않고 응답하면 AI가 도구 결과를 보고 고객에게 안내해요.
채팅 웹훅 받기
상담 화면은 채팅 웹훅으로 새 메시지를 받아요. 설정 > 웹훅의 이벤트 구독에서 채팅 시작, 메시지 수신, 메시지 발신 결과, 채팅 종료를 켜세요. 채널이 쓰는 에이전트 버전에 채팅 웹훅 URL이 있으면 워크스페이스 웹훅 URL보다 우선해요. 상담 서버 주소인지 확인하세요.chat_started: 새 채팅이에요.chat.responder_type이agent면 AI 응대 중 목록에 올려 상담사가 먼저 이어받을 수 있게 하고,operator면 상담사 대기 목록에 올리세요.chat_message_received: 고객 메시지예요.chat.responder_type이operator면 상담사가 답할 메시지이니 대기 상태와 읽지 않음 표시를 갱신하세요.chat_message_sent: AI 답변, 상담사 답장, 안내의 발신 결과예요.message.role은 각각agent,operator,system이에요.status가failed면error.code를 상담사에게 보여 주세요.chat_ended: 채팅이 끝났어요. 목록에서 닫으세요.
responder_type은 웹훅을 보내는 시점의 값이에요. 메시지를 누가 썼는지는 message.role로 확인하세요. 이어받기 전 대화는 채팅 조회 API의 transcript로 불러오세요. 이어받기와 AI 응대 복귀에는 웹훅이 오지 않아요. 고객사 서버가 호출했을 때는 API 응답의 responder로 화면을 바로 갱신하세요.
상담사 답장 보내기
메시지 직접 전송 API에origin을 operator로 넣어 보내세요. 이어받은 채팅에만 보낼 수 있어요. 답장마다 새 client_idempotency_key를 쓰세요.
AI 응대 복귀나 채팅 끝내기
고객 용건을 해결했으면POST /v3/chats/{chat_id}/release로 AI 응대 복귀를 호출하고, 더 할 말이 없으면 POST /v3/chats/{chat_id}/end로 채팅을 끝내세요. 용건이 남은 채로 복귀하면 AI가 같은 내용을 다시 물어요.
복귀에도 Idempotency-Key 헤더가 필요해요. 채널이 AI 응답을 허용하지 않으면 복귀가 AGENT_RESPONSE_NOT_ALLOWED로 거절돼요. 이때는 상담사가 계속 답하세요.
상담사가 먼저 이어받기
AI가 부르지 않아도 상담사는 AI가 응대 중인 채팅을 언제든 이어받을 수 있어요. 상담 화면에서Idempotency-Key 헤더와 함께 POST /v3/chats/{chat_id}/takeover로 상담사 이어받기를 호출하세요. 대시보드에서 다른 상담사가 이미 맡은 채팅은 409 CHAT_RESPONDER_CONFLICT로 거절돼요. 진행 중인 채팅은 GET /v3/chats?status=active로 찾아요.
AI가 답을 만드는 중에 이어받으면 그 답은 고객에게 가지 않아요. 상담사가 맡았다고 알리려면 채널별로 다른 점에 따라 안내를 보내세요.
AI 응대 복귀 뒤 AI가 아는 것
복귀하면 AI는 새 맥락으로 시작해요. 상담사가 안내한 주문번호처럼 복귀 전에 오간 내용을 물으면 답하지 못해요.- AI가 이어서 쓰는 것: 채팅의 동적 변수, 고객 메모리
- AI가 읽지 못하는 것: 복귀 전의 대화 전부. 그전 대화, 상담사 답장, 상담사가 맡은 동안 온 고객 메시지가 모두 포함돼요
- AI가 답하는 때: 복귀 뒤 새로 온 고객 메시지부터예요. 상담사가 맡은 동안 온 메시지에는 답하지 않아요
채널별로 다른 점
이어받기, 상담사 답장, AI 응대 복귀는 모든 채널에서 같은 API를 써요. AI 응답 요청만 채팅 API 채널 전용이에요. 다른 채널의 고객 메시지는 각 채널에서 들어와요.
이어받은 뒤 보내는 연결 안내의
origin은 이어받기 응답의 channel이 navertalk나 wechat이면 operator, 그 밖에는 system이에요. 네이버톡톡과 위챗은 origin이 system인 안내에 처리 중인 고객 메시지를 지정해야 하기 때문이에요.
운영 전에 점검하기
- 아무도 이어받지 않을 때: 대기 시간이 길어지면 상담 화면에서 알리고, 안내를 보내거나 채팅을 끝내세요.
- 상담사 인증: 상담 화면과 그 화면이 부르는 고객사 서버 API에 직원 인증을 붙이세요.
- 두 상담사가 같은 채팅에 답할 때: 같은 API 키로 호출하면 vox.ai는 모두 같은 응답 담당으로 봐요. 담당 상담사 배정과 잠금은 고객사 서버에서 하세요.
- 웹훅 순서와 중복: 메시지는
message.message_at으로 정렬하고(event, message.id)로 중복을 거르세요. 5초 안에 2xx를 돌려주고, 놓친 메시지는 채팅 조회로 채우세요. 규칙은 전달 보장과 재시도에 있어요. - 서명 검증: 웹훅과 도구 요청이 vox.ai에서 왔는지 확인하세요. 웹훅은 요청 검증하기를 따르세요.
- 누가 답했는지 기록: 이어받기와 답장 요청에는 상담사를 구분하는 값이 없고, 대화록에는 응답 담당이 바뀐 기록이 남지 않아요. 상담사, 이어받은 시각, 답장 응답의
id를 고객사 DB에 남기세요. - 호출 한도: v3 API는 워크스페이스마다 기본 초당 5회, 분당 120회예요. 대기 목록은 조회를 반복하지 말고 웹훅으로 채우세요.
- 비용: 채팅 요금과 채널 요금은 요금에서 확인하세요.