상담 연결 메타 활용 (`extra`)

고객이 상담을 시작하는 입구(상담 연결 버튼·링크·챗봇)에 값을 심어 두면, 상담이 연결되는 순간 그 값이 웹훅 신호에 실려 옵니다. 별도 조회 없이 첫 신호에서 "이 고객이 어디서, 무엇을 보다가 들어왔는지"를 알 수 있습니다.

[상품 페이지 버튼 extra=goods_1024] → 고객이 상담 시작 → kind:"reference" 신호에 reference.extra = "goods_1024"

이런 데 씁니다

활용	심는 값 예	받은 뒤
유입 페이지·상품 식별	`goods_1024` · `page_refund`	상담사·AI 에이전트에게 문맥으로 먼저 보여 주기
캠페인·채널 추적	`cmp_2609_fall` · `qr_store_gangnam`	상담 유입 통계
라우팅	`team_billing` · `ai_first`	담당 팀 큐 또는 AI 에이전트로 분기
회원 매칭	`mt_8f3a…`(짧은 토큰)	여러분 서버에서 토큰 → 회원 조회
챗봇 문맥 이어받기	챗봇 블록에서 넘긴 값	챗봇에서 하던 일을 상담에서 이어서

값을 심는 방법

값은 카카오 상담 연결 파라미터 extra 로 심습니다. 톡브릿지에서 따로 설정할 것은 없습니다.

① 링크 (가장 간단)

https://bizmessage.kakao.com/chat/open/@채널ID?extra=goods_1024

웹 페이지 버튼·QR·메일 링크 어디든 걸 수 있습니다.
최대 50자 · 영문/숫자/밑줄(_)만 허용됩니다. 조건을 벗어나면 카카오가 빈 값으로 바꿉니다(goods-1024, page:refund 는 비게 됩니다).

② 상담 연결 버튼 (POST)

카카오 상담 연결 버튼 스크립트나 POST https://bizmessage.kakao.com/chat/open(form: uuid, extra)으로 연결하면 최대 1000자까지, 기호도 넣을 수 있습니다. 긴 문맥이 필요하면 이 방식을 쓰세요.

③ 카카오 i 오픈빌더 챗봇에서 상담으로 전환

챗봇의 「상담 연결」 버튼(오픈빌더 버튼 기능 플러그인 → 상담 연결)에는 extra 를 넣는 칸이 없습니다. 그래서 값은 챗봇으로 들어오는 입구 링크에 심습니다 — bot=true 로 챗봇을 먼저 띄우고, 고객이 챗봇에서 상담으로 넘어오면 그 값이 lastReference 로 옵니다.

https://bizmessage.kakao.com/chat/open/@채널ID?bot=true&extra=goods_1024

{ "kind": "reference", "lastReference": { "extra": "goods_1024", "bot": "true", "createdAt": "2026-09-29T11:38:25.856" } }

챗봇 경유 상담에는 reference 가 없고 lastReference 만 옵니다. 그래서 읽는 순서대로 lastReference.extra 까지 확인해야 합니다.
링크에 event=블록이벤트명 을 붙이면 챗봇의 해당 이벤트 블록이 실행되고, 그 이름이 lastReference.botEvent 로 옵니다.
bot=auto 는 진행 중인 상담이 있으면 챗봇 대신 상담으로 바로 이어 줍니다.

챗봇 쪽 설정은 카카오 문서를 따릅니다

챗봇 블록·상담 전환 설정 자체는 카카오 i 오픈빌더에서 합니다. 톡브릿지는 카카오가 보내 준 메타를 그대로, 필드를 나눠 전달합니다.

받는 방법

상담이 연결되면 kind: "reference" 신호에 메타가 실립니다. 값이 있을 때만 필드가 생깁니다.

{
  "brand": "mybrand", "userKey": "Ab3d_x9Kq2Lm", "kind": "reference", "seq": 44,
  "reference":     { "extra": "goods_1024" },
  "lastReference": { "extra": "bot_handoff_01", "bot": "auto", "botEvent": "consult_start", "createdAt": "2026-09-29T11:38:25.856" }
}

필드	의미
`reference.extra`	이번 연결에 심은 값
`lastReference.extra`	이번 값이 없을 때 카카오가 알려 주는 가장 최근 값
`lastReference.bot`	상담 시작 방식 — `"true"` 봇으로 · `"false"` 상담톡으로 · `"auto"` 봇으로 하되 진행 중 상담이 있으면 유지
`lastReference.botEvent`	봇으로 시작했을 때 실행된 봇 블록 이벤트
`lastReference.createdAt`	마지막 메타가 만들어진 시각(카카오 표기 그대로, 문자열)

고객이 상담 중 버튼(BK/MD)을 눌러 보낸 메시지에는 kind: "message" 신호에 최상위 extra 가 붙습니다.

{ "brand": "mybrand", "userKey": "Ab3d_x9Kq2Lm", "kind": "message", "seq": 45, "extra": "btn_track_order" }

읽는 순서

reference.extra 가 있으면 그것이 이번 상담의 입구입니다.
없으면 lastReference.extra 를 봅니다(챗봇 전환 등). createdAt 이 너무 오래됐다면 버려도 됩니다.
둘 다 없으면 메타 없이 들어온 상담입니다(채널 대화방에서 바로 시작 등).

메타는 userKey 단위로 다음 reference 신호가 올 때까지 이번 상담의 문맥으로 보관하면 됩니다.

예제 — 상담 문맥 저장·라우팅 (Node.js)

서명 검증을 통과한 신호를 받는다고 가정합니다.

// userKey → 이번 상담의 입구 정보. 운영에서는 DB/Redis 에 두세요.
const contexts = new Map();

function onSignal(evt) {
  if (evt.test) return;                      // 연결 테스트 신호는 건너뛴다
  if (evt.kind === 'agent') return;          // 자기 발신 echo 는 무시

  if (evt.kind === 'reference') {
    const extra = evt.reference?.extra ?? evt.lastReference?.extra ?? null;
    contexts.set(evt.userKey, {
      extra,
      source: evt.reference?.extra ? 'connect' : evt.lastReference ? 'last' : 'none',
      bot: evt.lastReference?.bot ?? null,
      since: evt.seq,
    });
    route(evt.userKey, extra);
    return;
  }

  if (evt.kind === 'message' && evt.extra) {
    // 버튼으로 보낸 메시지 — 상담 중 행동 신호
    console.log('버튼 메시지', evt.userKey, evt.extra);
  }
}

function route(userKey, extra) {
  if (!extra) return assign(userKey, 'default');
  if (extra.startsWith('team_')) return assign(userKey, extra.slice(5)); // team_billing → billing
  if (extra.startsWith('goods_')) return assign(userKey, 'sales', { goodsId: extra.slice(6) });
  return assign(userKey, 'default', { extra });
}

function assign(userKey, queue, context = {}) {
  // 여러분의 상담 큐·AI 에이전트로 넘긴다
}

설계 팁

주의

extra 는 신뢰할 수 없는 입력입니다

링크의 extra 는 고객이 주소창에서 바꿀 수 있습니다. 권한·금액·본인 확인 판단에 그대로 쓰지 말고, 토큰이라면 여러분 서버에서 검증하세요.

개인정보를 넣지 마세요. 카카오 정책상 금지입니다. 회원을 이어야 한다면 짧은 불투명 토큰을 심고 여러분 서버에서 조회하세요.
짧은 규칙을 정해 두세요 — 예: {종류}_{값}(goods_1024, team_billing). 링크(50자·영문/숫자/밑줄)와 버튼(1000자) 양쪽에서 같은 규칙이 통합니다.
신호는 재전송될 수 있습니다 — (brand, seq) 로 멱등 처리하세요.
userKey 의 기존 문맥을 덮어쓰는 시점은 새 reference 신호입니다. expired·ended 에서 문맥을 정리하세요.

직접 확인하기

휴대폰에서 https://bizmessage.kakao.com/chat/open/@채널ID?extra=test_01 을 엽니다.
상담을 시작하면 여러분의 웹훅에 kind: "reference" · reference.extra = "test_01" 신호가 도착합니다.
오지 않으면 수신 웹훅 구성의 연결 상태를, 값이 비어 있으면 링크 제약(50자·영문/숫자/밑줄)을 확인하세요.

이런 데 씁니다​

값을 심는 방법​

① 링크 (가장 간단)​

② 상담 연결 버튼 (POST)​

③ 카카오 i 오픈빌더 챗봇에서 상담으로 전환​

받는 방법​

읽는 순서​

예제 — 상담 문맥 저장·라우팅 (Node.js)​

설계 팁​

직접 확인하기​