연동 안내서
플럿 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가 이 값을 써요 | |
channel | phone(기본) · 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일 수 있어요 |
handoff | true이면 AI가 답할 수 없는 문의예요. answer를 읽어 준 뒤 상담원에게 연결해 주세요 |
category | AI가 분류한 문의 유형(주문배송·교환환불·결제·예약·계정·요금·이용방법·영업정보·불만·제휴·채용·기타) |
transfer_to | handoff가 true일 때, 콘솔에 등록한 «상담원 연결 전화번호». 등록하지 않았으면 null |
대화 조회(GET /api/v1/conversations)에는 priority(A·B·C), intent(구매의향·견적요청·예약·변경취소·불만·문의·인사·기타), evidence(근거 원문), customer_id가 함께 와요. 콜센터 화면에서 급한 건을 먼저 띄울 때 써요.
ARS 흐름 예시
- 인사말 → 고객 발화 녹음 → 음성 인식 →
/api/v1/answer호출 answer를 음성 합성으로 읽어 줌 →handoff가false면 다음 발화를 기다림handoff가true면transfer_to로 호 전환. 근무 시간 밖이면 회신 안내- 응답은 보통 1~5초 안에 와요. ARS 쪽 대기 시간은 10초 이상으로 잡아 주세요
음성 인식 장치가 없는 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"}
지켜 주세요
- 조회는
GET, 예약·접수·변경처럼 전산에 값을 남기는 일은POST로 등록해요. POST 연동은 필요한 값을 모두 받은 뒤 한 번만 부르고, 응답의 접수번호·날짜를 그대로 고객에게 안내해요. 접수가 안 될 때는 응답에ok:false와message(가능하면available목록)를 담아 주면 AI가 다른 선택지를 안내해요. 취소·환불처럼 돈이 걸린 변경은 상담원에게 넘기는 것을 권해요. - 채팅 고객은 본인 확인을 거치지 않은 사람이에요. 주문번호만으로 주소·전화번호 같은 민감한 정보가 나오지 않게, 조회 응답에는 안내에 필요한 항목만 담아 주세요. 필요하면 «주문번호 + 전화번호 뒷자리»처럼 값 두 개를 요구해 주세요.
- 응답은 6초 안에 와야 해요. 넘으면 AI는 조회에 실패했다고 안내하고 상담원에게 넘겨요.
- 사내망 안쪽 주소(10.x, 192.168.x 등)는 부를 수 없어요. 외부에서 접근할 수 없는 전산은 도입 시 연결 방법을 같이 정해요.
사내 전산 — 지식 등록
전산이나 홈페이지 관리 화면에 있는 안내문이 바뀔 때 자동으로 지식에 반영해요. 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.kr | plutcs-verify=토큰 |
| SPF | TXT | 회사.co.kr | v=spf1 include:_spf.wkbly.com -all (기존 SPF 가 있으면 include 만 끼워 넣기) |
| DKIM | TXT | plutcs._domainkey.회사.co.kr | v=DKIM1; k=rsa; p=공개키 |
| DMARC(선택) | TXT | _dmarc.회사.co.kr | v=DMARC1; p=quarantine; adkim=s; aspf=s |
| 수신(MX 위임 선택 시) | MX | 회사.co.kr | 10 mail.wkbly.com |
- «DNS 확인»을 누르면 네 가지를 실제 DNS 에서 조회해요. 소유 확인·SPF·DKIM 이 맞으면 연결되고, 그때부터 모든 고객 대상 메일이
help@회사.co.kr이름으로 나가요. 봉투 발신자(Return-Path)도 같은 주소라 SPF·DKIM 이 From 도메인과 엄격 정렬(DMARC strict)돼요. - 수신은 두 가지예요. 전달(권장): 회사 메일함을 그대로 두고 자동 전달 대상에 공식 주소를 넣어요. MX 위임: 그 도메인으로 오는 메일을 전부 플럿 CS 가 받아요. 다른 메일함을 쓰는 도메인이면
help.회사.co.kr같은 하위 도메인을 연결하세요. - DNS 는 하루 한 번 자동으로 다시 확인해요. SPF·DKIM 이 빠지면 그 도메인으로 보내는 걸 멈추고 공식 주소로 되돌린 뒤 알림을 보내요(인증 안 된 메일이 나가 평판을 깎는 일을 막아요).
- 받은 메일은 수신 서버가 DKIM 을 검증하고, 실패하거나 SPF 정렬이 안 된 메일은 «발신자 인증 실패» 표시와 함께 상담원에게만 넘기고 AI 가 자동 답장하지 않아요.
- 안내 메일(캠페인)에는
List-Unsubscribe·List-Unsubscribe-Post헤더가 붙어 지메일·아웃룩이 한 번에 수신거부 버튼을 보여 줘요. 수신거부는 즉시 반영돼요. - «배달 점검»은 지금 발신 주소의 SPF·DKIM·DMARC·MX·역방향 DNS 를 한눈에 보여 줘요.
이메일 수신 세부
전달 또는 MX 로 들어온 메일의 처리 방식이에요.
- 같은 보낸 사람의 메일은 14일 안에는 한 대화로 이어져요. 제목의 Re:/Fwd: 는 떼고, 인용된 원문은 잘라 내요.
- AI 자동 답장을 켜면 지식에 근거가 있을 때만 답장을 보내고(AI가 보냈다는 표시 포함), 근거가 없으면 «담당자가 확인해 답장드린다»는 접수 메일만 보내요. 자동 응답·대량 메일은 건너뛰어요.
- 상담원이 상담함에서 답하면 고객에게 메일로 나가요. 답장 주소는 수신 주소라 고객의 회신이 다시 상담함으로 들어와요.
- 첨부 파일은 받지 않아요. 글(text/plain 또는 html → 글)만 저장해요.
인스타그램 · 페이스북 DM — 계정 연결
콘솔 «연동 · 채널 → 인스타그램 계정 연결»을 누르면 메타 로그인 창이 열려요. 허용하면 페이지·인스타그램 계정 목록이 뜨고, 고르면 토큰을 암호화해 저장하고 웹훅 구독까지 자동으로 해요. 두 가지 길이 있어요.
- 인스타그램 직접 로그인(Instagram API): 페이스북 페이지 없이 인스타그램 비즈니스·크리에이터 계정으로 바로 연결. 토큰은 60일마다 자동 갱신.
- 페이스북 로그인(Graph API): 페이지와 페이지에 연결된 인스타그램 계정을 함께 연결. 메신저 DM 도 들어와요.
- 둘 다 플럿 CS 의 메타 개발자 앱이 메시지 권한(
instagram_manage_messages,pages_messaging) 심사를 통과해야 실제 DM 이 들어와요. 심사 전에는 테스터로 등록된 계정만 돼요. - 고급: 메타 앱이 다른 계정에 있으면 «토큰 직접 입력»으로 페이지 ID·토큰을 넣고, 그 앱의 웹훅 콜백 주소에
https://cs.teamplut.com/api/ch/meta와 콘솔의 검증 토큰을 넣어요. 구독 필드는messages. - 웹훅 본문은 앱 비밀로 서명(
X-Hub-Signature-256)을 확인해요. - DM이 오면 보낸 사람 단위로 대화가 만들어지고 AI가 먼저 답해요(지식 근거·전산·예약 도구 모두 사용). 상담원 답장은 Graph API
/{page-id}/messages로 나가요. - 메타 정책: 고객이 마지막으로 보낸 뒤 24시간 안에는 AI·상담원 모두 답하고, 24시간~7일은 상담원 답장만
HUMAN_AGENT태그로 나가요. 7일이 지나면 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.handoff | AI가 상담원에게 넘겼을 때 | 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.detected | AI가 구매 의향·견적 요청으로 판별했을 때(대화당 한 번) | 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)