본문으로 건너뛰기

수신 payload

게이트웨이가 여러분의 URL로 보내는 요청의 형식입니다.

요청​

POST <내 웹훅 URL>
Content-Type: application/json
X-Bridge-Signature:   v0=<hex>
X-Bridge-Event:       <kind>
X-Bridge-Timestamp:   <unix seconds>
X-Bridge-Delivery-Id: <uuid>

바디 — "신호"​

{
  "brand":   "mybrand",
  "userKey": "Ab3d_x9Kq2Lm",
  "kind":    "message",
  "seq":     42
}
필드타입설명
brandstring브랜드(채널) 키
userKeystring상담 고객 키. 발신 API의 userKey와 동일한 상관키
kindstring이벤트 종류(아래 표)
seqnumber브랜드 저널의 단조증가 시퀀스. 순서·멱등 판단 기준
바디에 메시지 텍스트가 없습니다

payload는 "무슨 일이 있었다"는 신호이며 메시지 본문(text)을 포함하지 않습니다. 실제 대화 내용이 필요하면 수신 내용 조회 API로 가져오세요. 헤더 X-Bridge-Event는 바디의 kind와 동일합니다.

이벤트 종류 (kind)​

kind의미일반적 처리
message고객이 메시지를 보냄본문 조회 → 처리/답장
reference새 상담이 연결됨(세션 시작)세션 시작 처리
expired세션이 만료됨세션 종료 처리
ended상담이 종료됨세션 종료 처리
agent여러분(또는 상담사)의 발신이 반영됨(echo)보통 무시
deleted보낸 메시지가 삭제됨(발신 취소) — serial 로 어떤 발신인지 대조내 화면의 해당 말풍선을 삭제 표시
personal_info고객이 개인정보 제공에 동의함 — 값이 바디에 실려 옵니다(아래)즉시 보관
self-echo 필터링

kind: "agent" 는 여러분이 보낸 발신이 되돌아온 echo입니다. 답장 로직이 이 이벤트에 반응하면 무한 루프가 됩니다 — agent는 걸러내세요.

agent echo 는 두 번 옵니다​

발신 1건마다 kind: "agent" 신호가 두 번 도착합니다. 둘은 필드로 구분합니다 — seq 유무로 추정하지 마세요.

순서언제구분 필드내용
① 접수 신호발신 API 가 성공을 돌려준 직후phase: "accepted" · serialseq 없음. 발신 응답의 serial 과 같은 값 — 낙관적으로 그린 말풍선과 정확히 매칭할 수 있습니다
② 저널 항목약 1초 뒤, 브랜드 저널에 기록된 시점seq · serial다른 이벤트와 같은 형식. 멱등 키 (brand, seq) 에 포함됩니다. 여러 말풍선으로 나간 첨부 발신은 serials 에 전체 목록이 함께 옵니다
{ "brand": "mybrand", "userKey": "Ab3d_x9Kq2Lm", "kind": "agent", "phase": "accepted", "serial": "bw-1757400000000-a1b2" }
{ "brand": "mybrand", "userKey": "Ab3d_x9Kq2Lm", "kind": "agent", "seq": 43, "serial": "bw-1757400000000-a1b2" }

권장 처리: ①은 저장하지 않고 UI 확인(ack)에만 쓰고, ②는 seq 로 멱등 처리합니다. 둘 다 무시해도 상담 흐름에는 영향이 없습니다. ①에 serial 이 없을 수 있는 경우(옛 코어)도 phase 는 항상 있습니다.

메시지 삭제 (deleted)​

발신 취소(삭제)가 성공하면 kind: "deleted" 신호가 옵니다. serial 은 지운 발신의 serial 이라, 위 agent 신호나 발신 응답의 serial 과 대조하면 어떤 말풍선인지 알 수 있습니다.

{ "brand": "mybrand", "userKey": "Ab3d_x9Kq2Lm", "kind": "deleted", "seq": 45, "serial": "bw-1757400000000-a1b2" }

삭제를 요청한 쪽이 아니어도(예: 같은 브랜드를 쓰는 다른 상담 도구) 이 신호로 화면을 맞출 수 있습니다. 다른 이벤트와 같이 (brand, seq) 로 멱등 처리하세요. 삭제해도 상담 건수는 되돌아오지 않습니다.

개인정보 제공 동의 (personal_info)​

개인정보 제공 동의 요청에 고객이 동의하면 옵니다. 다른 신호와 달리 값이 바디에 실려 있습니다.

{
  "brand": "mybrand", "userKey": "Ab3d_x9Kq2Lm", "kind": "personal_info",
  "sessionId": "29153", "consentedAt": 1757400000000,
  "personalInfo": { "phoneNumber": "821012345678", "nickname": "고객닉네임" }
}
필드설명
sessionId동의가 일어난 카카오 상담 세션
consentedAt고객이 동의한 시각(Unix ms)
personalInfo.phoneNumber카카오계정 전화번호(국가번호 포함, 예: 8210…). 카카오에 등록되지 않았으면 빈 문자열
personalInfo.nickname카카오 프로필 닉네임. 등록되지 않았으면 빈 문자열
  • seq 가 없습니다. 브랜드 저널에 기록하지 않는 신호라 멱등 키 (brand, seq) 대신 X-Bridge-Delivery-Id 로 중복을 거르세요.
  • TalkBridge 는 이 값을 저장하지 않고 전달만 합니다. 수신 내용 조회에도 나오지 않고, 다시 받을 방법이 없습니다. 웹훅이 응답하지 않으면 잠시 재시도한 뒤 폐기합니다 — 받은 즉시 보관하세요.
  • 이 정보의 보관·이용·파기는 귀사가 책임집니다. 귀사 개인정보 처리방침에 수집 항목과 목적을 안내하세요.
  • 디스코드·슬랙 연동에는 "고객이 개인정보 제공에 동의했습니다" 알림만 가고 값은 가지 않습니다.

상담 연결 메타 (extra)​

상담 연결 버튼·링크나 챗봇 전환에 심은 값(extra)은 신호에 그대로 실려 옵니다. 값이 있을 때만 필드가 생깁니다.

kind필드내용
referencereference.extra이번 상담 연결에 심은 값
referencelastReference.{extra, bot, botEvent, createdAt}이번 값이 없을 때 카카오가 알려 주는 가장 최근 메타
messageextra고객이 버튼(BK/MD)을 눌러 보낸 메시지의 값
{ "brand": "mybrand", "userKey": "Ab3d_x9Kq2Lm", "kind": "reference", "seq": 44, "reference": { "extra": "goods_1024" } }

심는 방법·읽는 순서·라우팅 예제는 상담 연결 메타 활용을 보세요.

테스트 신호​

톡브릿지 센터 개발자 모드 「연결 테스트」의 수신 테스트는 실제 전달과 같은 헤더·같은 서명으로 아래 신호를 보냅니다.

{ "brand": "mybrand", "userKey": "tb-test-1a2b3c4d", "kind": "message", "seq": 0, "test": true }
  • test: true 는 테스트 신호에만 붙습니다. 실제 신호에는 이 필드가 없습니다.
  • userKey 는 가상 고객(tb-test- 로 시작)이라 본문 조회·답장이 되지 않습니다. 서명 검증과 2xx 응답까지만 확인하고, 저장·답장 로직은 건너뛰세요.
  • seq 는 항상 0 이라 멱등 키 (brand, seq) 에 걸릴 수 있습니다 — test: true 면 멱등 처리 전에 분기하세요.

상관 관계​

  • 수신 신호의 userKey = 답장 발신(POST /api/agent/send)의 userKey.
  • brand = 발신·조회의 brandKey.
  • 세션 단위 식별은 필요하지 않습니다 — userKey 하나로 대화를 잇습니다.