연동 안내서
플럿 CS를 전화 ARS·콜봇, 콜센터, 사내 전산과 잇는 방법이에요. 모두 HTTPS와 JSON으로 주고받아요. 설정은 콘솔의 «연동» 화면에서 해요.
| 연결 대상 | 방식 | 방향 |
|---|---|---|
| 전화 ARS · 콜봇 | 답변 API — 고객의 말을 글로 보내면 읽어 줄 답을 받아요 | ARS → 플럿 CS |
| 콜센터 | 통화 기록 등록, 대화 조회·답변, 웹훅 | 양방향 |
| 사내 전산 | 조회 연동 — AI가 전산의 조회 주소를 불러요 지식 등록, 웹훅 | 양방향 |
인증
콘솔 «연동 → 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 |
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"}지켜 주세요
- 읽기 전용 주소만 등록해 주세요. 취소·변경처럼 값을 바꾸는 일은 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 를 지켜요.
웹훅
콘솔 «연동 → 웹훅»에 받을 주소를 등록하면, 아래 일이 생길 때 플럿 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 |
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)