빠른 시작

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

1. Base URL

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

환경	Base URL
개발(dev)	https://api.talkbridge-dev.com

노트

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

2. API Key 발급

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

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

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

3. 키 검증 (whoami)

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

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

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

brands 배열의 값이 발신·조회에 쓰는 brandKey 입니다.

4. 첫 발신

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

curl -X POST https://api.talkbridge-dev.com/api/agent/send \
  -H "Authorization: Bearer blumnb-xxxx-xxxx-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "brandKey": "mybrand",
    "userKey": "user_ab12cd34",
    "text": "안녕하세요! 무엇을 도와드릴까요?"
  }'

성공 응답:

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

발신은 활성 세션에서만

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

5. 다음: 수신 받기

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