개발자

Wisebird API: 고객 채팅을 내 시스템에 연결해요

내 시스템과 연결하기 위한 REST API, Webhook, MCP

전체 설명 읽기

Wisebird 개발자 API는 채팅 조회, 검색, 메시지 전송, 태그와 비즈니스 멤버 관리를 위한 REST API와 Webhook이에요. 비즈니스별 API key와 Bearer 인증을 쓰고, Idempotency-Key, test event가 있는 서명된 Webhook, Try it 방식의 sandbox, MCP, 여러 비즈니스를 관리하는 partner API를 지원해요

API를 시작하려면 무엇이 필요한가요

  1. 비즈니스별 API key 생성앱의 비즈니스 설정에서 만들고 바로 복사해 두세요. key 전체는 한 번만 보여요
  2. Bearer 방식으로 key 전송모든 요청의 Authorization header에 넣고 query string에는 넣지 말며 HTTPS를 사용해요
  3. 먼저 sandbox에서 테스트앱의 Try it 모드로 테스트 비즈니스에 요청을 보낸 뒤 실제 비즈니스 key를 써요

예시 · 채팅 목록 조회

curl https://wisebird.cloud/external/v1/conversations?status=open&limit=20 \
  -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx"

어떤 endpoint가 있나요

모든 endpoint는 하나의 host 아래에 있고 JSON을 반환해요. schema가 포함된 전체 문서는 앱에 있어요

그룹Method와 path무엇에 쓰나요
ConversationsGET /external/v1/conversations채팅 목록, 상태·채널·태그·담당자별 필터
GET /external/v1/conversations/{id}채팅 한 건의 상세, 메시지와 고객 카드 포함
GET /external/v1/conversations/search메시지, 고객 이름 또는 전화번호로 채팅을 검색해요
POST /external/v1/conversations/{id}/messages고객에게 메시지 전송, text, image, video, audio, file 지원
TagsGET, POST /external/v1/tags태그 읽기와 생성, 채팅에 태그 추가나 제거
MembersGET /external/v1/members팀원 목록과 역할, 채팅 배정에 사용
WebhooksGET, POST /external/v1/webhooksendpoint 등록, 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":"영수증이에요"}'
  • Idempotency-Key메시지별 고유 값이에요. 같은 key로 다시 보내면 같은 결과를 받고 고객에게 중복 전송되지 않아요
  • 채널별 제한파일 형식과 크기는 채널에 따라 달라요
  • Messenger비즈니스가 먼저 보내는 메시지에는 24시간 제한이 있어요

Webhook은 무엇을 알리고 서명은 어떻게 검증하나요

endpoint를 등록하고 event를 선택한 뒤 test event를 보내면 바로 테스트돼요. 실제 채팅을 기다릴 필요 없어요

Eventv1v2발생 시점
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를 막아요

MCP, sandbox, partner API

  • Try it 방식 Sandbox앱의 개발자 페이지에서 테스트 비즈니스로 요청을 보내 바로 결과를 보여 주며 실제 고객에게는 영향이 없어요
  • MCP외부 AI 도구가 같은 API key 권한으로 Wisebird를 tool로 호출하게 해요
  • partner API파트너용으로 key 하나로 여러 비즈니스를 관리하고 통합 지갑의 크레딧을 써요
  • 권한과 log모든 요청이 activity log에 기록되고 설정 페이지에서 key를 바로 취소할 수 있어요

예시 · partner API로 관리할 비즈니스 지정

curl https://wisebird.cloud/external/v1/conversations?status=open \
  -H "Authorization: Bearer wb_partner_xxxxxxxxxxxxxxxx" \
  -H "X-Wisebird-Business: biz_42"

관련 페이지

파트너 프로그램

다중 비즈니스 관리, 통합 크레딧 지갑, 중앙 플랜

자세히 보기

CRM / 파이프라인

LINE 그룹, Telegram, Discord 또는 내 webhook으로 알림 규칙

알림 보기

자주 묻는 질문

Wisebird API key는 어디서 만드나요

앱의 비즈니스 설정 페이지에서 만들어요. key는 생성 시 한 번만 전체가 표시되니 바로 복사해 보관하세요. 잃어버리면 폐기하고 새로 만들면 돼요

API key를 query string으로 보낼 수 있나요

안 돼요. key는 HTTPS로 Authorization header에 Bearer 방식으로만 보내요. URL은 log에 기록되기 쉬워서 query string의 key는 거부돼요

실수로 메시지를 중복 전송하면 어떻게 되나요

Idempotency-Key header에 메시지별 고유값을 넣으세요. 같은 key로 다시 보내면 같은 결과를 받고 고객에게 중복 발송되지 않아요. retry에 적합해요

Webhook이 정말 Wisebird에서 온 것인지 어떻게 확인하나요

모든 event에는 endpoint의 secret으로 계산한 서명이 header에 있어요. 원본 body로 계산해 처리 전에 비교하세요. test event를 보내 테스트할 수 있어요

실제 고객에 영향 없이 테스트할 sandbox가 있나요

있어요. 앱 개발자 페이지의 Try it 모드로 테스트 비즈니스에 요청을 보내면 실제 고객에게는 가지 않아요. 실제 서명이 담긴 Webhook test event도 보낼 수 있어요

Wisebird에서 MCP는 어디에 쓰나요

외부 AI 도구가 채팅 검색, 고객 카드 조회, 메시지 전송 같은 Wisebird 기능을 같은 API key 권한으로 tool로 호출하게 해요

무료 패키지에서 첫 API key를 만들 수 있어요

가입하고 채널을 연동한 뒤 sandbox에서 첫 요청을 보내보세요