연동·API 문서
THelp 접속 주소, 홈페이지 버튼 코드, 프로그램 실행 주소, 고객 접속 REST API와 CSV 형식을 정리한 연동 문서.
OVERVIEW
개요
| 항목 | 내용 |
|---|---|
| 대상 | 회사 홈페이지·고객센터 시스템·사내 도구에서 THelp 원격지원으로 고객을 연결하려는 개발자 |
| 방식 | ① 접속 주소(링크) ② 프로그램 실행 주소(URL 스킴) ③ 고객 접속 REST API(JSON over HTTPS) ④ 관리 화면 CSV 내보내기 |
| 기준 주소 | https://9090.co.kr (고객 접속), https://thelp.co.kr (관리) |
| 인증 | 고객 접속 API는 로그인·API 키가 없습니다(고객이 쓰는 공개 기능). 관리 데이터는 관리 공간 로그인 후 CSV로 받습니다. |
| 문서 기준 | 2026년 11월 서비스 기준. 필드는 추가될 수 있으니 모르는 필드는 무시하도록 만들어 주세요. |
관리 데이터(지원 내역·통계·계정)를 조회하는 API 키 방식 REST API는 아직 제공하지 않습니다. 필요하면 도입·이용 문의로 알려 주세요.
LINKS
접속 주소
가장 간단한 연동입니다. 아래 주소를 문자·메일·홈페이지에 넣으면 고객이 눌러서 바로 접속 화면으로 들어옵니다.
| 주소 | 열리는 화면 |
|---|---|
https://9090.co.kr/ | 공용 접속 화면. 고객이 4자리 접속 번호를 입력합니다. |
https://9090.co.kr/?code=1234 | 번호가 미리 채워진 공용 접속 화면. 연결은 고객이 직접 누릅니다. |
https://9090.co.kr/회사아이디 | 회사 전용 화면. 회사 로고·연락처와 (설정에 따라) 대기 중인 상담원 번호가 보입니다. 예전 형식 /c/회사주소 도 열립니다. |
https://9090.co.kr/메인아이디 | 그 회사 전체 상담원의 대기 번호 |
https://9090.co.kr/메인아이디_1 | 그 상담원의 대기 번호만 |
Android 휴대폰에서 열면 THelp 원격지원 앱 열기·설치 안내가 나옵니다. iPhone·iPad 앱은 출시 예정입니다.
EMBED
홈페이지 버튼
관리 화면 [전용 포털] → 회사 홈페이지에 연결하기에서 회사 주소가 들어간 코드를 바로 복사할 수 있습니다. 직접 만들 때는 아래 형식을 씁니다.
<a href="https://9090.co.kr/회사아이디" target="_blank" rel="noopener">원격지원 받기</a><a href="https://9090.co.kr/회사아이디" target="_blank" rel="noopener">
<img src="https://9090.co.kr/assets/thelp-remote-banner.svg" width="250" height="60" alt="원격지원 받기">
</a>URL SCHEME
프로그램 실행 주소
| 주소 | 설명 |
|---|---|
thelp://join?t=연결권 | 고객용 프로그램을 실행해 그 연결권으로 바로 연결합니다. 연결권은 아래 REST API의 launchUri 로 받습니다. 프로그램이 없으면 열리지 않으므로 다운로드 안내를 함께 보여 주세요. |
thelp-agent://open | 설치된 상담원 프로그램을 엽니다. 이미 켜져 있으면 그 창을 앞으로 가져옵니다. 관리 화면의 [상담원 프로그램 실행]이 이 주소를 씁니다. 주소의 값은 프로그램에 넘기지 않습니다. |
연결권은 2분 안에 한 번만 쓸 수 있습니다. 저장하거나 다른 사람에게 보내지 마세요.
REST API
고객 접속 REST API
9090.co.kr 고객 화면이 쓰는 API입니다. 요청·응답은 UTF-8 JSON이고, 실패해도 대부분 HTTP 200에 "ok": false 와 reason 을 돌려줍니다.
GET/api/support/config
지금 발급하는 접속 번호 자릿수를 알려 줍니다(입력칸 수를 맞출 때).
curl https://9090.co.kr/api/support/config{"ok": true, "codeDigits": 4}POST/api/support/redeem
고객이 입력한 접속 번호를 확인하고 연결권을 받습니다.
| 필드 | 형식 | 설명 |
|---|---|---|
code | 문자열 | 접속 번호. 숫자 4자리 또는 6자리, 0으로 시작하지 않음 |
curl -X POST https://9090.co.kr/api/support/redeem \
-H "Content-Type: application/json" \
-d '{"code":"1234"}'{
"ok": true,
"ticket": "…",
"launchUri": "thelp://join?t=…",
"agentName": "김상담",
"companyName": "한빛테크 원격지원",
"companyPhone": "02-000-0000",
"companyLogo": "/brand/hanbit-1a2b3c4d.png"
}{"ok": false, "reason": "invalid-code"}GET/api/support/company/{회사아이디}
회사 전용 화면 정보와 지금 고를 수 있는 대기 번호를 돌려줍니다. {회사아이디} 에는 회사 아이디(메인 아이디), 상담원 아이디, 회사 주소를 넣을 수 있습니다.
{
"ok": true,
"title": "한빛테크 원격지원",
"phone": "02-000-0000",
"logoPath": "/brand/hanbit-1a2b3c4d.png",
"accessMode": "both",
"brandColor": "",
"consentText": "",
"serviceHours": "",
"slots": [ {"number": 1, "pickKey": "…", "agentName": "김상담"} ],
"agentName": "김상담"
}| 필드 | 설명 |
|---|---|
accessMode | code(접속 번호만), number(상담원 번호 선택), both(둘 다). code 이면 slots 가 비어 있고 pick 을 쓸 수 없습니다. |
slots[].pickKey | 번호를 고를 때 보내는 값. 대기가 바뀌면 달라집니다. |
agentName | 상담원 아이디 주소로 조회했을 때만 있습니다. |
POST/api/support/company/{회사아이디}/pick
대기 번호를 골라 연결권을 받습니다. 다른 고객이 먼저 고르면 slot-unavailable 이 오니 목록을 다시 불러오세요.
curl -X POST https://9090.co.kr/api/support/company/hanbit/pick \
-H "Content-Type: application/json" \
-d '{"pickKey":"…"}'{
"ok": true,
"ticket": "…",
"code": "1234",
"launchUri": "thelp://join?t=…",
"agentName": "김상담",
"companyName": "한빛테크 원격지원",
"companyPhone": "02-000-0000",
"companyLogo": "/brand/hanbit-1a2b3c4d.png"
}code 는 고객용 프로그램이 아직 없는 고객이 프로그램을 받아 실행한 뒤 입력할 번호입니다. 번호를 고른 고객에게만 보여 주세요.
이 API에는 CORS 허용 헤더가 없습니다. 다른 도메인의 웹페이지 스크립트에서 직접 부르지 말고, 회사 서버에서 부르거나 접속 주소로 연결하세요.
ERRORS
응답 코드·제한
| HTTP | reason | 뜻과 처리 |
|---|---|---|
| 200 | invalid-code | 번호가 맞지 않거나 쓸 수 없음. 고객에게 번호를 다시 확인하게 합니다. |
| 200 | slot-unavailable | 고른 대기 번호를 다른 고객이 먼저 가져감. 목록을 다시 불러옵니다. |
| 400 | bad-request | JSON 형식이 아님 |
| 404 | not-found | 없는 회사 주소이거나 이용이 끝난 회사, 또는 접속 방식이 code 인 회사에 pick 요청 |
| 429 | rate-limited | 요청이 너무 많음. 잠시 뒤 다시 시도합니다. |
- 번호 확인(redeem)과 번호 고르기(pick)는 같은 IP에서 1분에 10번까지입니다. 틀린 번호가 많이 들어오면 잠시 막히고, 노출된 번호가 새 번호로 바뀝니다.
- 고객 접속 API 전체는 IP당 1분 30회(순간 10회 추가)로 제한됩니다.
- 연결권(
ticket)은 2분 안에 한 번만 쓸 수 있습니다.
EXPORT
CSV 내보내기
관리 공간에 로그인한 뒤 각 화면의 CSV 버튼으로 받습니다. UTF-8 CSV이며 시각은 UTC입니다. 엑셀에서 바로 열 수 있습니다.
| 화면 | 파일 | 열 |
|---|---|---|
| 지원 내역 | thelp-history-시작-종료.csv | 회사, 상담원, 상담원 아이디, 부서·팀, 시작·종료(UTC), 고객 PC명, 고객 IP, 운영체제, 엔진, 접속 방식, 소요 시간(초), 결과, 종료 사유, 상담 메모, 고객 만족도, 고객 의견, 해결 여부, 고객 이름·전화·이메일, 상담원 공인·사설 IP, 상담원 PC명 |
| 접속 기록 | thelp-logins-시작-종료.csv | 회사, 상담원, 상담원 아이디, 로그인·로그아웃(UTC), 접속 시간(초), 접속 IP, 프로그램, 운영체제, 종료 사유 |
| 이용 통계 | thelp-stats-시작-종료.csv | 월별·상담원별·회사별 지원 건수, 비율, 총·평균 이용 시간, 고객 만족도와 합계 |
| 계정·상담원 | thelp-accounts.csv | 회사, 이름, 아이디, 이메일, 역할, 계정·접속 상태, 마지막 접속, 접속 IP, 2단계 인증 등 |
| 감사 기록 | thelp-audit.csv | 시각(UTC), 회사, 수행자, 작업, 내용, 접속 IP, 브라우저 |
CSV를 받은 기록도 감사 기록에 남습니다. 고객 개인정보가 들어 있으니 보관과 삭제에 주의해 주세요.