Using connect metadata (extra)

If you plant a value at the entry point where a customer starts a consultation (a connect button, link or chatbot), that value arrives inside the webhook signal the moment the consultation connects. From the very first signal — with no extra lookup — you know where the customer came from and what they were looking at.

[Product page button extra=goods_1024] → customer starts a consultation → kind:"reference" signal with reference.extra = "goods_1024"

What it is for

Use	Example value	After you receive it
Identify the entry page or product	goods_1024 · page_refund	Show it to the human agent or AI agent as context up front
Campaign / channel tracking	cmp_2609_fall · qr_store_gangnam	Consultation entry statistics
Routing	team_billing · ai_first	Branch to a team queue or an AI agent
Member matching	mt_8f3a… (short token)	Look the token up on your server to find the member
Carry over chatbot context	A value passed from a chatbot block	Continue in the consultation what the chatbot was doing

How to plant a value

Plant the value with Kakao's consultation connect parameter extra. There is nothing to configure on the TalkBridge side.

① Link (simplest)

https://bizmessage.kakao.com/chat/open/@CHANNEL_ID?extra=goods_1024

• You can put it on any web page button, QR code or email link.
• Up to 50 characters · letters, digits and underscore (_) only. Anything else is replaced with an empty value by Kakao (goods-1024 and page:refund become empty).

② Connect button (POST)

With Kakao's consultation connect button script or POST https://bizmessage.kakao.com/chat/open (form: uuid, extra), you can send up to 1,000 characters, including symbols. Use this form when you need longer context.

③ Handoff from a Kakao i Open Builder chatbot

The chatbot's "connect to consultation" button (Open Builder button function Plugin → 상담 연결) has no field for extra. So plant the value on the entry link into the chatbot — open the chatbot first with bot=true, and when the customer moves from the chatbot to a consultation, the value arrives as lastReference.

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

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

• A consultation reached through the chatbot carries only lastReference, with no reference. That is why you must read down to lastReference.extra, following the order of reading.
• Adding event=BLOCK_EVENT_NAME to the link runs that event block in the chatbot, and the name arrives as lastReference.botEvent.
• bot=auto goes straight to the consultation instead of the chatbot if a consultation is already in progress.

Chatbot-side settings follow Kakao's documentation

Chatbot blocks and handoff settings are configured in Kakao i Open Builder. TalkBridge forwards the metadata Kakao sends as is, in separate fields.

How to receive it

When a consultation connects, the metadata rides on the kind: "reference" signal. Fields appear only when a value exists.

{
  "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" }
}

Field	Meaning
reference.extra	The value planted for this connection
lastReference.extra	The most recent value, which Kakao provides when there is none for this connection
lastReference.bot	How the consultation started — "true" via bot · "false" via consultation chat · "auto" via bot, but keep an ongoing consultation
lastReference.botEvent	The bot block event run when it started through the bot
lastReference.createdAt	When the last metadata was created (as Kakao sends it, as a string)

When the customer taps a button (BK/MD) during a consultation, the resulting kind: "message" signal carries a top-level extra.

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

Order of reading

1. If reference.extra is present, that is the entry point of this consultation.
2. Otherwise look at lastReference.extra (chatbot handoff, etc.). If createdAt is too old, you may discard it.
3. If neither is present, the consultation started without metadata (for example, directly from the channel chat room).

Keep the metadata as this consultation's context per userKey, until the next reference signal arrives.

Example — storing consultation context and routing (Node.js)

This assumes the signal has already passed signature verification.

// userKey → entry info for this consultation. In production, keep it in a DB/Redis.
const contexts = new Map();

function onSignal(evt) {
  if (evt.test) return;                      // skip connection-test signals
  if (evt.kind === 'agent') return;          // ignore your own send 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) {
    // A message sent with a button — an in-consultation action signal
    console.log('button message', 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 = {}) {
  // hand off to your consultation queue or AI agent
}

Design tips

caution

extra is untrusted input

A customer can change the extra of a link in the address bar. Do not use it as is for permission, amount or identity decisions; if it is a token, verify it on your server.

• Do not put personal information in it. Kakao's policy prohibits it. If you need to link a member, plant a short opaque token and look it up on your server.
• Agree on a short convention — e.g. {type}_{value} (goods_1024, team_billing). The same convention then works for both links (50 characters · letters/digits/underscore) and buttons (1,000 characters).
• Signals can be redelivered — deduplicate by (brand, seq).
• Overwrite a userKey's existing context on a new reference signal. Clean up the context on expired · ended.

Try it yourself

1. Open https://bizmessage.kakao.com/chat/open/@CHANNEL_ID?extra=test_01 on your phone.
2. When you start a consultation, a kind: "reference" signal with reference.extra = "test_01" arrives at your webhook.
3. If nothing arrives, check the connection status in Webhook Setup; if the value is empty, check the link constraints (50 characters · letters/digits/underscore).