수신 내용 조회

수신 웹훅은 신호만 전달합니다(payload). kind: "message" 신호를 받으면, 실제 대화 내용은 조회 API로 가져옵니다.

이 문서의 범위

현재 문서화된 내용 모델은 TalkBridge의 표준 sink(예: Discord 연동)가 실제로 인바운드를 처리하는 방식에서 도출한 것입니다. 수신 처리가 고도화되면 이 문서도 함께 업데이트됩니다.

특정 고객의 최근 메시지

GET /api/agent/rooms/{userKey}/messages?brand=mybrand&max=20

• 인증: Authorization: Bearer blumnb-... (BrandRead 이상)
• max: 1~300(기본 100). 최신순으로 반환.

curl "https://api.talkbridge-dev.com/api/agent/rooms/user_ab12/messages?brand=mybrand&max=5" \
  -H "Authorization: Bearer blumnb-..."

{
  "ok": true,
  "brand": "mybrand",
  "userKey": "user_ab12",
  "messages": [
    {
      "seq": 42,
      "userKey": "user_ab12",
      "sessionId": "ses_...",
      "kind": "message",
      "text": "환불 문의드립니다",
      "timestampUnixMs": 1751850000000
    }
  ]
}

messages[] 항목:

필드	타입	설명
seq	number	저널 시퀀스(웹훅 신호의 seq와 대응)
userKey	string	고객 키
sessionId	string	세션 식별자
kind	string	message / reference / expired / agent / ended
text	string	메시지 본문
timestampUnixMs	number	수신 시각(ms)

신호 → 본문 매핑

message 신호를 받으면, 위 응답에서 첫 kind: "message" 항목의 text 가 방금 도착한 고객 메시지입니다(최신순 반환). 참조 sink도 정확히 이 방식으로 본문을 보강합니다.

상담방 목록

진행 중인 상담방(고객별) 요약을 조회합니다.

GET /api/agent/rooms?brand=mybrand&max=50

{
  "ok": true,
  "brand": "mybrand",
  "rooms": [
    {
      "userKey": "user_ab12",
      "lastSeq": 42,
      "lastText": "환불 문의드립니다",
      "lastKind": "message",
      "lastTimestampUnixMs": 1751850000000,
      "count": 7,
      "ended": false
    }
  ]
}

이미지 · 첨부

고객이 이미지를 보내면 본문(text)에 이미지 URL이 포함됩니다. 참조 sink는 본문에서 URL을 추출해 이미지로 렌더합니다. 즉 이미지도 message 이벤트 + 본문 조회로 처리하며, 본문 안의 URL 유무로 판별합니다.

이벤트별 처리 요약

kind	조회 필요?	처리
message	✅	본문 조회 → 텍스트/이미지 처리
reference	✗	"새 상담 연결" 로 처리
expired	✗	"세션 만료" 로 처리
ended	✗	"상담 종료" 로 처리
agent	✗	무시(자기 발신 echo)