본문으로 건너뛰기

빠른 시작

키 발급부터 첫 메시지 발신까지 진행합니다.

GitHub 샘플 데모

GitHub 을 통해 Developer API 활용 샘플 데모를 제공합니다 — CLI·REST·웹훅을 실제로 엮은 실행 가능한 예제와 파트너용 공개 매뉴얼입니다. blumnai-playground.github.io/talk-bridge ↗ (상단 GitHub 아이콘과 같은 곳)

1. Base URL​

모든 파트너 API는 아래 도메인으로 호출합니다.

환경Base URL
운영(prod)https://api.talkbridge.io
노트

convbridge-api는 발신·설정·수신 내용조회·대화 이력 만 노출하는 전용 엣지입니다. 카카오 수신 내부 서버는 외부에 노출되지 않습니다.

환경과 호스트​

TalkBridge 는 실환경과 개발환경을 따로 운영하며, 각 환경은 역할별 호스트 3개로 이뤄집니다.

역할실환경개발환경
REST API(이 문서의 Base URL) · Docshttps://api.talkbridge.iohttps://api.talkbridge-dev.com
CLI 기본 엔드포인트 · 수신 스트림https://webhook.talkbridge.iohttps://webhook.talkbridge-dev.com
톡브릿지 센터(키 발급·talkbridge login)https://console.talkbridge.iohttps://console.talkbridge-dev.com
  • 키는 발급된 환경에 묶입니다 — 개발환경에서 발급한 blumnb- 키는 실환경에서 401 입니다(그 반대도 같습니다). CLI 도 채널별 바이너리(talkbridge / talkbridge-dev)가 각자의 환경을 바라봅니다.
  • 개발환경은 도입 검토·사전 테스트용으로 별도 안내에 따라 제공됩니다. 필요하면 지원으로 문의하세요. 일반 파트너는 실환경만으로 연동을 시작할 수 있습니다.

2. API Key 발급​

API Key는 톡브릿지 센터 → 연동 관리 → 개발자 모드에서 발급합니다. 키는 blumnb- 로 시작하며, 특정 브랜드(brandKey) 에 묶여 있습니다.

연동 키 3종 — 개발자 모드 「연동 키 안내」

API 연동에는 세 가지 키가 필요하며, 개발자 모드 상단의 「연동 키 안내」 카드에 모여 있습니다.

키역할어디에 쓰나
Brand Key상담이 오가는 브랜드(채널) 식별자API 요청의 brandKey · CLI --channel
Agent Key (blumnb-…)API 호출 인증Authorization: Bearer
서명 검증 키 (whsec_…)수신 웹훅의 위조 여부 검증웹훅 서명 검증

Brand Key 와 서명 검증 키는 언제든 다시 볼 수 있지만, Agent Key 평문은 발급 직후 한 번만 표시됩니다.

  • 발신·설정을 하려면 BrandWrite 스코프 키가 필요합니다.
  • 조회만 하려면 BrandRead 로 충분합니다.

자세한 내용은 인증 문서를 참고하세요.

3. 키 검증 (whoami)​

발급받은 키가 유효한지, 어떤 채널에 접근할 수 있는지 확인합니다.

curl https://api.talkbridge.io/api/agent/me \
  -H "Authorization: Bearer blumnb-xxxx-xxxx-xxxx"
{ "name": "My Brand Agent", "scope": "BrandWrite", "brands": ["mybrand"] }

brands 배열의 값이 발신·조회에 쓰는 brandKey 입니다(채널마다 하나 — 채널 종류·이름은 channels 에 함께 옵니다). 같은 값을 톡브릿지 센터 개발자 모드의 「연동 키 안내」 → Brand Key 에서도 확인할 수 있습니다. 이 응답만은 { ok, … } 봉투 없이 그대로 옵니다(인증).

4. 첫 발신​

진행 중인 상담 세션의 고객(userKey)에게 텍스트를 보냅니다.

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": "안녕하세요! 무엇을 도와드릴까요?"
  }'

성공 응답:

{ "ok": true, "code": "0", "message": null }
발신은 활성 세션에서만

카카오 상담톡은 활성 상담 세션에만 발신할 수 있습니다. userKey는 수신 웹훅으로 받은 값을 사용하세요. 세션이 없거나 만료되면 발신이 실패합니다(에러 코드).

5. 다음: 수신 받기​

발신은 REST로 직접 하지만, 수신은 웹훅으로 받습니다. 웹훅을 구성하고 서명을 검증하는 방법은 수신 웹훅 구성으로 이어집니다.