파트너 프로그램
다중 비즈니스 관리, 통합 크레딧 지갑, 중앙 플랜
자세히 보기개발자
내 시스템과 연결하기 위한 REST API, Webhook, MCP
Wisebird 개발자 API는 채팅 조회, 검색, 메시지 전송, 태그와 비즈니스 멤버 관리를 위한 REST API와 Webhook이에요. 비즈니스별 API key와 Bearer 인증을 쓰고, Idempotency-Key, test event가 있는 서명된 Webhook, Try it 방식의 sandbox, MCP, 여러 비즈니스를 관리하는 partner API를 지원해요
예시 · 채팅 목록 조회
curl https://wisebird.cloud/external/v1/conversations?status=open&limit=20 \ -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx"
모든 endpoint는 하나의 host 아래에 있고 JSON을 반환해요. schema가 포함된 전체 문서는 앱에 있어요
| 그룹 | Method와 path | 무엇에 쓰나요 |
|---|---|---|
| Conversations | GET /external/v1/conversations | 채팅 목록, 상태·채널·태그·담당자별 필터 |
| GET /external/v1/conversations/{id} | 채팅 한 건의 상세, 메시지와 고객 카드 포함 | |
| GET /external/v1/conversations/search | 메시지, 고객 이름 또는 전화번호로 채팅을 검색해요 | |
| POST /external/v1/conversations/{id}/messages | 고객에게 메시지 전송, text, image, video, audio, file 지원 | |
| Tags | GET, POST /external/v1/tags | 태그 읽기와 생성, 채팅에 태그 추가나 제거 |
| Members | GET /external/v1/members | 팀원 목록과 역할, 채팅 배정에 사용 |
| Webhooks | GET, POST /external/v1/webhooks | endpoint 등록, event 선택, test event 전송 |
예시 · Idempotency-Key와 함께 메시지 전송
curl -X POST https://wisebird.cloud/external/v1/conversations/cnv_123/messages \
-H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: 7f3c2a1e-order-4512-confirm" \
-H "Content-Type: application/json" \
-d '{"type":"text","text":"주문 #4512 접수했어요. 영업일 기준 2일 안에 배송돼요."}'
# 첨부 파일 보내기: type을 image | video | audio | file 중 하나로 바꾸고 파일 url을 보내요
# -d '{"type":"image","url":"https://example.com/receipt.png","caption":"영수증이에요"}'
endpoint를 등록하고 event를 선택한 뒤 test event를 보내면 바로 테스트돼요. 실제 채팅을 기다릴 필요 없어요
| Event | v1 | v2 | 발생 시점 |
|---|---|---|---|
| message.received | 있음 | 있음 | 고객이 어느 채널로든 메시지를 보내요 |
| message.sent | 있음 | 있음 | AI나 팀이 발신 메시지를 보내면 payload에 발신자가 표시돼요 |
| conversation.handoff | 있음 | 있음 | AI가 이유와 요약과 함께 채팅을 팀에 인계해요 |
| conversation.assigned | 없음 | 있음 | 채팅이 팀원에게 배정됨 |
| conversation.tagged | 없음 | 있음 | 채팅에 태그가 추가되거나 제거됨 |
| lead.created | 없음 | 있음 | 리드 폼이나 AI가 새 리드를 파이프라인에 생성 |
| order.created | 없음 | 있음 | 채팅에서 판매나 주문이 기록돼요 |
v2는 payload에 event와 필드를 추가했어요. v1도 계속 쓸 수 있지만 새 엔드포인트는 v2를 권장해요
예시 · 내 endpoint가 받을 payload와 서명 header
POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Wisebird-Event: conversation.handoff
X-Wisebird-Signature: t=1760600000,v1=5f1c…e2a9
X-Wisebird-Delivery: evt_01HZX…
{"id":"evt_01HZX…","version":"v2","type":"conversation.handoff",
"business_id":"biz_42","created_at":"2026-10-16T09:30:00+07:00",
"data":{"conversation_id":"cnv_123","channel":"line","reason":"customer_requested_human",
"summary":"고객이 시술 전 염증성 여드름을 문의했어요. 의사 진단을 요청했어요"}}
# 서명 검증: HMAC-SHA256(secret, t + "." + raw_body) 그다음 v1과 constant-time으로 비교해요
# t가 현재 시각과 정한 범위 이상 차이 나면 거부해 replay를 막아요
예시 · partner API로 관리할 비즈니스 지정
curl https://wisebird.cloud/external/v1/conversations?status=open \ -H "Authorization: Bearer wb_partner_xxxxxxxxxxxxxxxx" \ -H "X-Wisebird-Business: biz_42"
앱의 비즈니스 설정 페이지에서 만들어요. key는 생성 시 한 번만 전체가 표시되니 바로 복사해 보관하세요. 잃어버리면 폐기하고 새로 만들면 돼요
안 돼요. key는 HTTPS로 Authorization header에 Bearer 방식으로만 보내요. URL은 log에 기록되기 쉬워서 query string의 key는 거부돼요
Idempotency-Key header에 메시지별 고유값을 넣으세요. 같은 key로 다시 보내면 같은 결과를 받고 고객에게 중복 발송되지 않아요. retry에 적합해요
모든 event에는 endpoint의 secret으로 계산한 서명이 header에 있어요. 원본 body로 계산해 처리 전에 비교하세요. test event를 보내 테스트할 수 있어요
있어요. 앱 개발자 페이지의 Try it 모드로 테스트 비즈니스에 요청을 보내면 실제 고객에게는 가지 않아요. 실제 서명이 담긴 Webhook test event도 보낼 수 있어요
외부 AI 도구가 채팅 검색, 고객 카드 조회, 메시지 전송 같은 Wisebird 기능을 같은 API key 권한으로 tool로 호출하게 해요
가입하고 채널을 연동한 뒤 sandbox에서 첫 요청을 보내보세요