본문으로 이동

연동·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는 아직 제공하지 않습니다. 필요하면 도입·이용 문의로 알려 주세요.

EMBED

홈페이지 버튼

관리 화면 [전용 포털] → 회사 홈페이지에 연결하기에서 회사 주소가 들어간 코드를 바로 복사할 수 있습니다. 직접 만들 때는 아래 형식을 씁니다.

HTML · 텍스트 버튼
<a href="https://9090.co.kr/회사아이디" target="_blank" rel="noopener">원격지원 받기</a>
HTML · 배너 이미지
<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": "김상담"
}
필드설명
accessModecode(접속 번호만), 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

응답 코드·제한

HTTPreason뜻과 처리
200invalid-code번호가 맞지 않거나 쓸 수 없음. 고객에게 번호를 다시 확인하게 합니다.
200slot-unavailable고른 대기 번호를 다른 고객이 먼저 가져감. 목록을 다시 불러옵니다.
400bad-requestJSON 형식이 아님
404not-found없는 회사 주소이거나 이용이 끝난 회사, 또는 접속 방식이 code 인 회사에 pick 요청
429rate-limited요청이 너무 많음. 잠시 뒤 다시 시도합니다.

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를 받은 기록도 감사 기록에 남습니다. 고객 개인정보가 들어 있으니 보관과 삭제에 주의해 주세요.

우리 회사의 지원 흐름으로
THelp를 살펴보세요.

필요한 상담원 수와 지원 환경을 알려 주세요.

무료체험 신청

안내