Quickstart

We will go from issuing a key to sending your first message.

Sample demos on GitHub

We provide Developer API sample demos on GitHub — runnable examples that wire the CLI, REST, and webhooks together, plus the public partner manual. blumnai-playground.github.io/talk-bridge ↗ (the same place as the GitHub icon in the top bar)

1. Base URL

All partner APIs are called on the domain below.

Environment	Base URL
운영(prod)	https://api.talkbridge.io

note

convbridge-api is a dedicated edge that exposes only outbound, settings, inbound content lookup, and conversation history. The internal Kakao inbound server is not exposed externally.

Environments and hosts

TalkBridge runs a production environment and a separate development environment, each made up of three hosts by role.

Role	Production	Development
REST API (the Base URL in these docs) · Docs	https://api.talkbridge.io	https://api.talkbridge-dev.com
CLI default endpoint · inbound stream	https://webhook.talkbridge.io	https://webhook.talkbridge-dev.com
TalkBridge Center (key issuance · talkbridge login)	https://console.talkbridge.io	https://console.talkbridge-dev.com

• Keys are bound to the environment that issued them — a blumnb- key issued in development gets 401 in production, and vice versa. The CLI likewise ships a binary per channel (talkbridge / talkbridge-dev), each pointing at its own environment.
• The development environment is provided for evaluation and pre-launch testing under a separate arrangement. Contact Support if you need it. Most partners can start integrating with production alone.

2. Issuing an API Key

API Keys are issued in TalkBridge Center → Integrations → Developer mode. A key starts with blumnb- and is bound to a specific brand (brandKey).

The three integration keys — "Integration keys" card in Developer mode

An API integration needs three keys. All three are gathered in the "Integration keys" card at the top of Developer mode.

Key	Role	Where it is used
Brand Key	Identifies the brand (channel) the consultations belong to	brandKey in API requests · --channel in the CLI
Agent Key (blumnb-…)	Authenticates API calls	Authorization: Bearer
Signature verification key (whsec_…)	Verifies that an inbound webhook is genuine	Webhook signature verification

The Brand Key and the signature verification key can be viewed again at any time, but the Agent Key plaintext is shown only once, right after it is issued.

• To send messages or change settings, you need a key with the BrandWrite scope.
• For read-only access, BrandRead is enough.

See the Authentication document for details.

3. Verifying the key (whoami)

Check that the issued key is valid and which channels it can access.

curl https://api.talkbridge.io/api/agent/me \
  -H "Authorization: Bearer blumnb-xxxx-xxxx-xxxx"

{ "name": "My Brand Agent", "scope": "BrandWrite", "brands": ["mybrand"] }

The values in the brands array are the brandKey you use for sending and lookups (one per channel — channel type and name come in channels). The same value is shown under "Integration keys" → Brand Key in Developer mode of TalkBridge Center. This response alone comes back without the { ok, … } envelope (Authentication).

4. Your first outbound message

Send a text message to a customer (userKey) in an active consultation session.

curl -X POST https://api.talkbridge.io/api/agent/send \
  -H "Authorization: Bearer blumnb-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "brandKey": "mybrand",
    "userKey": "Ab3d_x9Kq2Lm",
    "text": "Hello! How can I help you?"
  }'

Success response:

{ "ok": true, "code": "0", "message": null }

Outbound only works in an active session

Kakao SangdamTalk (Kakao's customer-consultation chat) only allows sending to an active consultation session. Use the userKey value received via the inbound webhook. If there is no session or it has expired, sending fails (error codes).

5. Next: receiving inbound messages

Sending is done directly over REST, but inbound messages arrive via webhook. How to configure the webhook and verify its signature continues in Configuring inbound webhooks.