상담톡 연동 흐름

상담톡은 카카오톡 채널로 고객과 1:1 상담 메시지를 주고받는 채널입니다. 처음 연동할 때는 아래 순서로 진행합니다. 각 단계의 요청·응답 규격은 상담톡 API 레퍼런스에서 확인하세요.

이런 경우에 잘 맞습니다

상담톡은 메시지를 웹훅으로 받고 API로 보내는 구조라, 상담 화면을 카카오 관리자센터가 아니라 우리 시스템 안에 둘 수 있습니다.

• CRM과 연결하고 싶을 때 — 고객 메시지가 웹훅으로 들어오므로 userKey를 CRM 고객 정보와 묶어 두면, 상담원이 고객 이력·주문 정보를 보면서 같은 화면에서 답할 수 있습니다.
• 자체 상담 시스템을 만들 때 — 상담 배정, 대기열, 상담원별 처리 현황, 응답 템플릿처럼 우리 업무에 맞는 기능을 직접 붙일 수 있습니다. 메시지 송수신은 API가 맡습니다.
• 상담 내역을 직접 보관해야 할 때 — 주고받은 메시지가 모두 우리 서버를 거치므로 원하는 형태로 저장하고 검색·통계에 쓸 수 있습니다.
• 봇과 상담원을 함께 운영할 때 — 봇이 먼저 응대하다 상담원에게 넘기거나, 상담이 끝나면 다시 봇으로 돌려보낼 수 있습니다.
• 웹·앱에서 바로 상담을 열고 싶을 때 — 상담 연결 버튼에 주문번호 같은 메타 정보를 실어 보내면, 상담원이 어떤 화면에서 문의가 왔는지 알고 시작할 수 있습니다.

1. 상담톡 등록

발신프로필을 상담톡에 등록합니다. 웹훅 URL, 상담톡·채팅 활성화 여부를 이때 함께 정합니다.

• 상담톡 등록 POST /api/comm/v1/account/kakao/sender/cstalk
• 등록한 뒤 웹훅 URL 등을 바꾸려면 상담톡 수정 PUT /api/comm/v1/account/kakao/sender/cstalk/{senderKey}을 씁니다. 발신프로필 키는 바꿀 수 없습니다.

2. 상담톡 이용 활성화

상담톡 이용 활성화로 채널의 상담톡을 켭니다.

• 활성화하면 상담 내역 유실을 막기 위해 해당 카카오톡 채널의 채팅 기능이 꺼집니다.
• 다른 허브사에서 넘어오는 경우, 기존 허브사의 상담톡을 먼저 비활성화해야 합니다. 그 사이에는 상담 메시지를 받을 수 없으니 Sandbox 연동과 테스트를 미리 끝내 두세요.

3. 웹훅으로 상담 메시지 받기

사용자가 보낸 메시지, 세션 종료, 읽음 정보, 발송 결과 등은 등록한 웹훅 URL로 들어옵니다. 수신 규격은 상담메시지 수신하기 (Webhook)를 참고하세요.

• HTTP 200과 규격에 맞는 응답을 돌려줘야 정상 처리됩니다. 실패하면 최대 3회까지 다시 보냅니다.
• 같은 이벤트가 다시 올 수 있으므로 msgKey 기준으로 중복을 걸러 주세요.
• 이벤트가 발생한 순서대로 도착하지 않을 수 있습니다.

4. 상담 메시지 보내기

고객 메시지를 받아 상담 세션이 열려 있을 때만 상담원 메시지를 보낼 수 있습니다. 세션은 마지막 고객 메시지를 받은 뒤 30일간 유지되고, 고객 메시지가 올 때마다 연장됩니다.

• 텍스트·이미지·파일은 Plain 메시지 발송, 버튼·카드형 등은 Rich 메시지 발송을 씁니다.
• 고객은 userKey로 구분합니다. 같은 사용자라도 카카오톡 채널이 다르면 다른 키입니다.

5. 상담 종료

상담이 끝나면 상담 종료로 세션을 닫습니다. 봇과 함께 운영한다면 상담 종료 및 봇 전환으로 대화를 봇에 넘길 수 있습니다.

다음 단계