발신 API

상담사/AI가 고객에게 메시지를 보내거나, 상담을 종료·차단하는 API입니다. 모두 BrandWrite 스코프가 필요합니다.

공통:

Base URL: https://api.talkbridge-dev.com
헤더: Authorization: Bearer blumnb-..., Content-Type: application/json
응답 봉투: { "ok": boolean, "code": string, "message": string } — 자세한 코드는 에러 코드

텍스트 발신

POST /api/agent/send

필드	타입	필수	설명
`brandKey`	string	✅	브랜드(채널) 키
`userKey`	string	✅	대상 고객 키
`text`	string	✅	보낼 텍스트

curl -X POST https://api.talkbridge-dev.com/api/agent/send \
  -H "Authorization: Bearer blumnb-..." -H "Content-Type: application/json" \
  -d '{ "brandKey": "mybrand", "userKey": "user_ab12", "text": "안녕하세요" }'

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

리치 메시지 발신

버튼·리스트·이미지 카드 등 카카오 리치 말풍선을 보냅니다.

POST /api/agent/send/rich

필드	타입	필수	설명
`brandKey`	string	✅	브랜드 키
`userKey`	string	✅	대상 고객 키
`rich`	string	✅	카카오 리치 규격 JSON을 문자열로 담은 값

노트

rich는 JSON 객체를 문자열로 직렬화해 보냅니다. 잘못된 JSON이면 400 BAD_RICH 로 거부됩니다.

상담 종료

진행 중인 상담 세션을 상담사가 능동 종료합니다. 선택적 종료 인사말을 먼저 보낸 뒤 종료합니다.

POST /api/agent/end

필드	타입	필수	설명
`brandKey`	string	✅	브랜드 키
`userKey`	string	✅	대상 고객 키
`greeting`	string		종료 전 보낼 인사말(선택)

종료 + 봇 전환

상담을 종료하면서 봇 시나리오로 핸드오프합니다.

POST /api/agent/end-with-bot

필드	타입	필수	설명
`brandKey`	string	✅	브랜드 키
`userKey`	string	✅	대상 고객 키
`botEvent`	string		전환할 봇 이벤트(선택)

고객 차단 / 해제

POST /api/agent/block
POST /api/agent/unblock

필드	타입	필수	설명
`brandKey`	string	✅	브랜드 키
`userKey`	string	✅	대상 고객 키

첨부 업로드

발신에 붙일 이미지/파일을 먼저 업로드해 URL·키를 확보합니다.

POST /api/agent/upload/image     # multipart: brand, file, imageType?
POST /api/agent/upload/file      # multipart: brand, file, fileType(file|audio|video)

이미지 업로드 예시:

curl -X POST https://api.talkbridge-dev.com/api/agent/upload/image \
  -H "Authorization: Bearer blumnb-..." \
  -F "brand=mybrand" -F "file=@photo.jpg"

{ "ok": true, "code": "0", "message": null, "url": "https://.../photo.jpg", "name": "photo.jpg", "size": 20481 }

반환된 url을 리치 메시지의 이미지 필드에 연결해 발신합니다.

self-echo 주의

발신이 성공하면 여러분의 수신 웹훅으로 kind: "agent" 신호가 되돌아옵니다(자기 발신의 echo). 무한 루프를 막으려면 웹훅 처리 시 kind == "agent" 이벤트를 걸러내세요. 자세한 내용은 수신 payload.

텍스트 발신​

리치 메시지 발신​

상담 종료​

종료 + 봇 전환​

고객 차단 / 해제​

첨부 업로드​