TOPDESK

DOCUMENT(API)
document · api

외부 프로그램·스크립트와 TopDesk를
연동하기 위한 명령줄(API) 안내입니다.

Windows 클라이언트 CLI · 로컬 IPC

Command-Line Interface

실행 중인 TopDesk 클라이언트를 제어합니다
클라우드 REST가 아닌, 로컬 PC의 명령 인터페이스입니다

원격 연결 시작, 접속 비밀번호 설정, 연락처 이름 변경, 로컬 ID 조회 등을 UI 클릭 없이 스크립트에서 호출할 수 있습니다. 다운로드·설치 후 클라이언트가 실행 중이어야 합니다.

개요

제품TopDesk (Windows 클라이언트)
방식로컬 명령줄 → IPC (WM_COPYDATA)
실행 파일C:\Program Files (x86)\TopDesk\TopDesk.exe
대상 창제목 TopDesk Client (이미 실행 중이어야 함)
용도자동화, 관리 프로그램 연동, URL 핸들러
참고 버전클라이언트 1.2.2.5 기준
이 문서는 클라우드 REST API가 아닙니다. 명령은 같은 PC에서 동작 중인 TopDesk 프로세스로 전달됩니다. 계정·포털용 REST 문서가 추가되면 이 페이지에서 안내합니다.

지원 기능

  • TopDesk ID로 원격 연결 시작
  • topdesk:// URL 형식 연결
  • 접속 비밀번호 설정
  • 연결 기록에 표시 이름 변경
  • 로컬 TopDesk ID 요청

사전 조건

  • Windows에 TopDesk 설치
  • TopDesk Client 창이 이미 실행 중
  • 필요 시 전체 경로로 실행
"C:\Program Files (x86)\TopDesk\TopDesk.exe"

명령어 참고

명령 설명
--connect <id> 해당 TopDesk ID로 원격 연결을 시작합니다. (UI의 연결 버튼과 동일 흐름)
--connect topdesk://<id>/ URL 형식. 스킴·끝 슬래시를 제거한 뒤 동일하게 연결합니다.
--set-pass <password> 접속 비밀번호를 설정합니다. (공백은 처리 과정에서 제거될 수 있음)
--set-name <id> <name> 연결 기록에 저장된 해당 ID의 표시 이름을 갱신합니다.
--get-id 로컬 TopDesk ID를 요청합니다. (처리 시 설치 폴더 clientid.txt 등)
--help 사용 가능한 명령 안내를 출력합니다.

동작 방식

┌──────────────────────────┐   WM_COPYDATA    ┌────────────────────────────┐
│ TopDesk.exe --connect …  │ ───────────────► │ TopDesk Client 창          │
│ (짧은 CLI 프로세스)       │  connect:<id>    │ 제목: "TopDesk Client"     │
└──────────────────────────┘                  │ → ID 입력 후 연결 UI 실행  │
                                              └────────────────────────────┘
CLI내부 메시지
--connect 517427346connect:517427346
--connect topdesk://517427346/connect:517427346
--set-pass secretset-pass:secret
--set-name 517427346 "PC-02"set-name:517427346:PC-02
--get-idget-id:… → 응답 파일

예제

원격 연결 시작

"C:\Program Files (x86)\TopDesk\TopDesk.exe" --connect 517427346

클라이언트가 명령을 수락하면 표준 출력 예:

--connect success

URL 형식 연결

"C:\Program Files (x86)\TopDesk\TopDesk.exe" --connect topdesk://517427346/

비밀번호 설정

"C:\Program Files (x86)\TopDesk\TopDesk.exe" --set-pass YourPassword8+
비밀번호 정책(최소 길이 등)은 클라이언트 버전에 따릅니다. 적용 실패 시 트레이 알림·로그를 확인하세요.

연락처 이름 변경

"C:\Program Files (x86)\TopDesk\TopDesk.exe" --set-name 517427346 "2-노트북"

PowerShell 예시

$exe = 'C:\Program Files (x86)\TopDesk\TopDesk.exe'
$id  = '517427346'

# 클라이언트가 없으면 먼저 실행
if (-not (Get-Process -Name TopDesk -ErrorAction SilentlyContinue)) {
    Start-Process -FilePath $exe
    Start-Sleep -Seconds 3
}

& $exe --connect $id

응답 동작

상황동작
Client 창을 찾음명령 적용. 보통 --<cmd> success 출력
Client 창 없음적용되지 않음 (no-op). success 없음
--connect 수락연결 UI 흐름 시작. 세션 유지 성공을 보장하지 않음
인증·네트워크 실패세션 창이 잠시 열렸다 닫힐 수 있음. 클라이언트 로그 확인
표준 출력의 success는 “명령이 클라이언트에 전달됨”을 의미합니다. 원격 화면이 완전히 연결되었는지는 화면·로그로 확인하세요.

제한 사항

  • 실행 중인 UI 클라이언트 필요 — 순수 헤드리스 서버 모드는 지원하지 않습니다.
  • 대상 창 제목은 TopDesk Client 이어야 합니다.
  • 다중 테넌트 클라우드 API(라이선스 ID·API 키) 모델이 아닙니다.
  • 스크립트에서는 이름·경로에 ASCII/안전한 문자 사용을 권장합니다.
031-707-6954
mshop plus friend talk