연동 안내서

플럿 CS를 전화 ARS·콜봇, 콜센터, 사내 전산과 잇는 방법이에요. 모두 HTTPS와 JSON으로 주고받아요. 설정은 콘솔의 «연동» 화면에서 해요.

연결 대상방식방향
전화 ARS · 콜봇답변 API — 고객의 말을 글로 보내면 읽어 줄 답을 받아요ARS → 플럿 CS
콜센터통화 기록 등록, 대화 조회·답변, 웹훅양방향
사내 전산조회 연동 — AI가 전산의 조회 주소를 불러요
지식 등록, 웹훅
양방향
이메일 · 인스타그램/페이스북 DM채널 연결 — 전달 주소 하나, 메타 앱 웹훅 하나양방향
고객 · 영업공개 페이지(문의 폼·가격표·예약·프로필·문서) + 웹훅 이벤트플럿 CS → 고객·전산

인증

콘솔 «연동 → API 키»에서 키를 만들어요. 키 원문은 만들 때 한 번만 보여요. 모든 요청에 아래 헤더를 붙여요.

Authorization: Bearer pcs_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

키 하나당 분당 120회까지 부를 수 있어요. 넘으면 429를 돌려줘요. 오류 응답은 {"ok": false, "error": "코드", "message": "설명"} 꼴이에요.

전화 ARS · 콜봇 — 답변 API

ARS나 콜봇이 고객의 말을 글로 바꾼 뒤(음성 인식) 이 주소로 보내면, 등록한 지식과 전산 조회를 근거로 전화로 읽어 줄 답을 돌려줘요. 같은 통화의 요청은 같은 session_id로 보내야 앞의 대화를 이어서 이해해요.

POST/api/v1/answer

값필수설명
session_id예통화를 구분하는 값. ARS의 통화 ID를 그대로 쓰면 돼요. 80자 이내
text예고객이 한 말. 1,000자 이내
caller발신 전화번호. 전산 조회에 전화번호가 필요할 때 AI가 이 값을 써요
channelphone(기본) · chat · email · kakao · sms · api. phone이면 답을 말로 읽기 좋게 짧게 써요. 이메일·카카오 채널·문자는 고객사 시스템이 받은 글을 이 API로 넘기는 방식이에요(플럿 CS가 직접 수신하지는 않아요)
curl -X POST https://cs.teamplut.com/api/v1/answer \
  -H "Authorization: Bearer $PLUTCS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"call-20261008-0001","caller":"01012345678","text":"토요일에도 영업하나요"}'

응답

{
  "ok": true,
  "conversation_id": 1284,
  "answer": "네, 토요일은 오전 열 시부터 오후 세 시까지 영업해요.",
  "handoff": false,
  "transfer_to": null
}
값설명
answer고객에게 읽어 줄 문장. 이미 상담원이 맡은 대화이면 null일 수 있어요
handofftrue이면 AI가 답할 수 없는 문의예요. answer를 읽어 준 뒤 상담원에게 연결해 주세요
categoryAI가 분류한 문의 유형(주문배송·교환환불·결제·예약·계정·요금·이용방법·영업정보·불만·제휴·채용·기타)
transfer_tohandoff가 true일 때, 콘솔에 등록한 «상담원 연결 전화번호». 등록하지 않았으면 null

대화 조회(GET /api/v1/conversations)에는 priority(A·B·C), intent(구매의향·견적요청·예약·변경취소·불만·문의·인사·기타), evidence(근거 원문), customer_id가 함께 와요. 콜센터 화면에서 급한 건을 먼저 띄울 때 써요.

ARS 흐름 예시

음성 인식 장치가 없는 ARS는 그로스 이상 요금제에서 도입 시 함께 구축해요.

콜센터 — 통화 기록 등록

상담원이 받은 통화가 끝나면 요약과 대화 내용을 올려요. 상담함에 «전화» 기록으로 남아 채팅 문의와 한곳에서 볼 수 있어요.

POST/api/v1/calls

{
  "call_id": "pbx-88213",
  "caller": "01012345678",
  "customer_name": "김하늘",
  "agent_name": "박상담",
  "summary": "배송지 변경 요청, 출고 전이라 변경 처리함",
  "transcript": [
    {"role": "customer", "text": "어제 주문한 거 주소를 바꾸고 싶어요"},
    {"role": "agent", "text": "주문번호 확인해 드릴게요"}
  ]
}

summary와 transcript 중 하나는 있어야 해요. 응답은 {"ok": true, "conversation_id": 1290}.

대화 조회 · 상담원 답변

콜센터 프로그램이나 전산 화면에서 플럿 CS의 문의를 직접 보고 답할 때 써요.

GET/api/v1/conversations?status=human&limit=50

status는 ai(AI 응대 중) · human(상담원 답변 필요) · closed(종료). 빼면 전부 줘요.

GET/api/v1/conversations/{id}

대화 한 건과 메시지 전체. 메시지의 role은 user(고객) · ai · agent(상담원) · system(안내)예요.

POST/api/v1/conversations/{id}/reply

{"text": "출고 전이라 주소를 바꿔 드렸어요.", "agent_name": "박상담"}

채팅 문의에 상담원 답변을 보내요. 고객의 대화창에 바로 보여요.

POST/api/v1/conversations/{id}/close

사내 전산 — 조회 연동

주문·배송·예약·계약 상태처럼 고객마다 다른 내용을 AI가 전산에서 확인하고 답하게 해요. 콘솔 «연동 → 전산 조회 연동»에 조회 주소를 등록하면, AI가 필요할 때 플럿 CS 서버에서 그 주소를 불러요.

항목설명
이름 · 설명AI가 설명을 보고 언제 이 조회를 쓸지 판단해요. «주문번호로 배송 상태와 도착 예정일을 확인한다»처럼 구체적으로 적어 주세요
주소https://로 시작. {order_no}처럼 중괄호로 값이 들어갈 자리를 표시해요
필요한 값최대 6개. 고객이 아직 말하지 않은 값은 AI가 먼저 물어봐요
인증 헤더전산이 요구하는 헤더 한 개(예: Authorization). 값은 암호화해서 보관해요

예: 주소를 https://erp.example.com/api/orders/{order_no}로 등록하고 고객이 «A-20391 어디쯤 왔어요?»라고 물으면, 플럿 CS가 아래처럼 불러요.

GET https://erp.example.com/api/orders/A-20391
Accept: application/json
Authorization: Bearer (등록한 값)

전산은 조회 결과를 JSON이나 글로 돌려주면 돼요. 형식은 자유예요. AI는 응답의 앞 3,000자를 읽고 그 안에 있는 내용만 안내해요.

{"order_no": "A-20391", "status": "배송중", "courier": "CJ대한통운", "eta": "2026-10-10"}

접수 예: 주소 https://erp.example.com/api/reservations를 POST로 등록하고 필요한 값을 name, phone, date, time으로 두면, 고객이 «내일 오후 3시 예약할게요»라고 할 때 AI가 이름과 전화번호를 물어본 뒤 아래처럼 보내요. 미리보기(/preview)의 병원·학원·쇼핑몰이 이 방식으로 실제로 접수해요.

POST https://erp.example.com/api/reservations
Content-Type: application/json

{"name": "홍길동", "phone": "010-1234-5678", "date": "2026-10-16", "time": "15:00"}

→ {"ok": true, "ref": "R1016-2831", "date": "2026-10-16", "time": "15:00"}

지켜 주세요

사내 전산 — 지식 등록

전산이나 홈페이지 관리 화면에 있는 안내문이 바뀔 때 자동으로 지식에 반영해요. ref가 같으면 덮어써요.

PUT/api/v1/knowledge/{ref}

{"title": "10월 배송 안내", "body": "10월 9일은 공휴일이라 출고가 없어요. …"}

DELETE/api/v1/knowledge/{ref}

홈페이지 전체를 한 번에 넣으려면 콘솔 «지식 → 자동 회사 지식 수집»에 주소를 넣으면 돼요. 수집기는 PlutCS-KB/1.0 이름으로 접속하고 robots.txt 를 지켜요.

이메일 · DM 채널

이메일 수신 · 발신

워크스페이스마다 공식 주소 워크스페이스키@wkbly.com이 있어요. 회사 메일(예: help@회사.co.kr)의 자동 전달 대상에 이 주소를 넣으면 들어온 메일이 «이메일» 채널 대화로 상담함에 쌓여요. 답장·견적서·예약 확인·안내 메일은 이 공식 주소(또는 아래 연결한 회사 도메인 주소)에서 나가고, 발신 도메인의 SPF·DKIM·DMARC 가 모두 정렬돼요.

자기 도메인 연결

하이웍스처럼 도메인은 회사가 그대로 갖고, DNS 레코드만 넣어 플럿 CS 가 그 이름으로 보내고(선택하면) 받게 해요. 콘솔 «연동 · 채널 → 자기 도메인 연결»에서 도메인과 앞부분(help 등)을 넣으면 그 도메인 전용 DKIM 2048비트 키를 만들어 암호화해 보관하고, 넣어야 할 레코드를 보여 줘요.

용도종류호스트값
소유 확인TXT_plutcs.회사.co.krplutcs-verify=토큰
SPFTXT회사.co.krv=spf1 include:_spf.wkbly.com -all (기존 SPF 가 있으면 include 만 끼워 넣기)
DKIMTXTplutcs._domainkey.회사.co.krv=DKIM1; k=rsa; p=공개키
DMARC(선택)TXT_dmarc.회사.co.krv=DMARC1; p=quarantine; adkim=s; aspf=s
수신(MX 위임 선택 시)MX회사.co.kr10 mail.wkbly.com

이메일 수신 세부

전달 또는 MX 로 들어온 메일의 처리 방식이에요.

인스타그램 · 페이스북 DM — 계정 연결

콘솔 «연동 · 채널 → 인스타그램 계정 연결»을 누르면 메타 로그인 창이 열려요. 허용하면 페이지·인스타그램 계정 목록이 뜨고, 고르면 토큰을 암호화해 저장하고 웹훅 구독까지 자동으로 해요. 두 가지 길이 있어요.

카카오톡 채널(오픈빌더 스킬)

콘솔 «연동 · 채널 → 카카오톡 채널 연결»에 보이는 스킬 서버 URL 을 카카오 i 오픈빌더의 스킬로 등록하고 폴백 블록에 연결하면, 고객 메시지(userRequest.utterance)가 플럿 CS 로 와서 AI 답이 5초 안에 돌아가요. 응답은 simpleText + quickReplies(예약·가격표·상담원 연결)예요. 카카오는 서버 발신(푸시)을 허용하지 않아 상담원 답장은 고객의 다음 메시지 때 함께 전달돼요. 상담톡(유료)은 별도.

페인트(paynt.io) 결제

«연동 · 채널 → 페인트 결제 연동»에 페인트 판매자 API 키(pk_live_…)와 웹훅 서명 키(whsec_…)를 넣고, 페인트 대시보드 웹훅 주소에 https://cs.teamplut.com/api/ch/paynt를 등록해요. 결제 요청 문서를 만들 때 «페인트 결제 링크 자동 생성»을 켜면 페인트의 POST /api/paynt/v1/links로 단건 결제 페이지가 만들어지고, order.paid 웹훅이 오면 문서가 «입금 확인»으로 바뀌어요(서명 X-Paynt-Signature 검증, ref=plutcs:문서토큰으로 대조).

공개 페이지

콘솔에서 만든 것을 고객에게 보여 주는 주소예요. 모두 ?c=채널이름을 붙이면 유입 분석에 채널별로 집계돼요(예: ?c=instagram).

주소무엇
/me/{주소}비즈니스 프로필 — 채팅·문의 폼·가격표·예약·전화·SNS 버튼을 한 장에
/c/{주소}상담챗 — 전체 화면 채팅(홈페이지 없이도)
/f/{폼 주소}문의 폼. 응답은 POST /api/pub/form/{폼 주소}
/p/{주소}서비스 가격표
/b/{주소}예약 페이지. 가능한 시간은 GET /api/pub/book/{주소}
/d/{문서 토큰}견적서·제안서·계약서·거래명세서·결제 요청. 고객이 승인·보류·의견·서명·입금 알림을 남겨요. 색인되지 않아요
/api/pub/qr?u={우리 주소}위 주소들의 QR(SVG). 인쇄물·안내판용

홈페이지에 폼을 직접 넣고 싶으면 <iframe src="https://cs.teamplut.com/f/폼주소" style="width:100%;height:900px;border:0"></iframe> 로 넣어요.

웹훅

콘솔 «연동 → 웹훅»에 받을 주소를 등록하면, 아래 일이 생길 때 플럿 CS가 그 주소로 POST를 보내요. 콜센터 시스템에 콜백 건을 만들거나 전산에 상담 이력을 남길 때 써요.

이벤트언제data
conversation.handoffAI가 상담원에게 넘겼을 때conversation_id, channel, session_id, question, contact
conversation.contact고객이 연락처를 남겼을 때conversation_id, contact, name
conversation.closed상담이 종료됐을 때conversation_id, channel, session_id
conversation.sla상담원 답변 대기가 설정한 시간을 넘겼을 때conversation_id, channel, waiting_min, contact
lead.detectedAI가 구매 의향·견적 요청으로 판별했을 때(대화당 한 번)conversation_id, channel, intent, priority, evidence, contact
form.response문의 폼 응답이 들어왔을 때conversation_id, form, source, answers[], customer_id
booking.created예약이 접수됐을 때(페이지·채팅 AI·직접 입력 모두)booking_id, conversation_id, name, contact, date, time, topic, customer_id
document.approve document.decline document.comment document.sign document.paid고객이 문서 링크에서 결정했을 때document_id, kind(quote·proposal·contract·statement·payreq), no, total, comment, customer_id
ping콘솔에서 «시험 전송»을 눌렀을 때message
POST https://erp.example.com/hooks/plutcs
Content-Type: application/json
X-PlutCS-Event: conversation.handoff
X-PlutCS-Signature: sha256=3f1c…

{"event":"conversation.handoff","workspace":"w1a2b3…","created":"2026-10-08T05:12:44.120Z",
 "data":{"conversation_id":1284,"channel":"phone","session_id":"call-20261008-0001","question":"위약금이 얼마예요","contact":"01012345678"}}

서명 확인

요청 본문(받은 그대로의 바이트)을 콘솔에 보이는 «서명 비밀값»으로 HMAC-SHA256 한 값이 X-PlutCS-Signature의 sha256= 뒤 값과 같은지 확인해 주세요.

// Node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const mine = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === mine.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(mine));
}

5초 안에 2xx로 답해 주세요. 실패해도 다시 보내지 않으니, 놓치면 안 되는 건은 대화 조회로 status=human을 주기적으로 확인해 주세요. 최근 전송 결과는 콘솔에서 볼 수 있어요.

웹 채팅 위젯

콘솔 «설정 → 위젯 설치»의 코드를 홈페이지 </body> 바로 앞에 넣어요. 버튼 없이 직접 열고 닫으려면 PlutCS.open() · PlutCS.close()를 불러요.

<script src="https://cs.teamplut.com/w.js" data-key="워크스페이스 키" async></script>

도움이 필요하면

연동 개발은 도입 범위에 들어 있어요. 조회 주소가 없는 전산, 음성 인식이 없는 ARS도 도입 상담에서 방법을 같이 정해요. 도입 상담 신청 · 070-5276-7256 (평일 10:00~18:00)