Yeastar Linkus SDK

🇹🇭 ภาษาไทย

Linkus SDK ของ Yeastar P-Series ช่วยให้นักพัฒนาฝัง Linkus softphone เข้าไปใน web/desktop/mobile app ของตัวเองได้ รองรับ 5 platform: Web, Windows, Android, iOS, macOS

ข้อกำหนด: ต้องใช้ Ultimate Plan (UP) เท่านั้น + Firmware 37.12.0.23 ขึ้นไป

---

Platform Overview

Platform	Package / ไฟล์	Tech	คำอธิบาย
Web Core	npm install ys-webrtc-sdk-core	JavaScript / WebRTC	Core call logic ไม่มี UI
Web UI	npm install ys-webrtc-sdk-ui	React + CSS	UI สำเร็จรูป พร้อมใช้งาน
Windows Core	npm install ys-webrtc-sdk-core	JavaScript / WebRTC	เหมือน Web แต่สำหรับ Electron/Windows app
Windows UI	npm install ys-webrtc-sdk-ui	React + CSS	UI สำเร็จรูปสำหรับ Windows
Android	AAR package	Kotlin/Java	Native Android SDK
iOS	CocoaPods / manual	Swift/ObjC	iOS 11+, Xcode 14.3+
macOS	CocoaPods / manual	Swift/ObjC	macOS 10.13+, Xcode 14.3+

---

การ Authentication (ทุก Platform)

ทุก platform ใช้ Linkus SDK login signature ในการ authenticate โดย flow เดียวกัน:

1. Enable Linkus SDK
   → PBX Web Portal: Integrations > Linkus SDK > เปิด toggle > Save
   → บันทึก AccessID และ AccessKey

2. ขอ Access Token (ทำบน third-party app server)
   POST {pbx_url}/openapi/v1.0/get_token
   Body: { "username": "<AccessID>", "password": "<AccessKey>" }
   → ได้ access_token (หมดอายุ 30 นาที)

3. ขอ Login Signature สำหรับ extension
   POST {pbx_url}/openapi/v1.0/sign/create?access_token={token}
   Body: { "username": "1000", "sign_type": "sdk", "expire_time": 0 }
   → ได้ sign (login signature สำหรับ extension นั้น)

4. ส่ง signature ไปยัง Linkus SDK client
   → SDK init({username: "1000", secret: "<sign>", pbxURL: "https://..."})

expire_time: 0 = signature ไม่มีวันหมดอายุ

---

Web SDK / Windows SDK

Web SDK และ Windows SDK ใช้ package เดียวกัน (ys-webrtc-sdk-core) โดยมีสถาปัตยกรรมแบบเดียวกัน

การ Initialize

import { init } from 'ys-webrtc-sdk-core';
 
init({
    username: '1000',           // extension number หรือ email
    secret: 'sdklogin_sign',    // login signature จาก sign/create
    pbxURL: 'https://192.168.1.1:8088'
}).then(operator => {
    const { phone, pbx, destroy } = operator;
    // phone = PhoneOperator (call features)
    // pbx   = PBXOperator (CDR, logout)
    // destroy = ทำลาย SDK instance
});

Module formats รองรับ: UMD, CJS, ESM, IIFE

PBXOperator — CDR + Logout

Method	คำอธิบาย
init()	Initialize (ใช้ภายใน SDK core)
on(eventName, listener)	Subscribe events
cdrQuery(params)	ดึง CDR records (page, size, status, sortBy, filter)
logout()	Logout
destroy()	ทำลาย PBXOperator object

PBXOperator Events:

Event	คำอธิบาย
runtimeError	ข้อผิดพลาด runtime (-106 Linkus disabled, -107 logged elsewhere, -110 not Ultimate)
cdrChange	CDR มีการเปลี่ยนแปลง → ต้อง call cdrQuery() เอง

PhoneOperator — Call Features

Method	Signature	คำอธิบาย
start()	start()	เริ่ม register SIP UA → สามารถโทรได้
call()	call(number, option?, transferId?)	โทรออก
reject()	reject(callId)	ปฏิเสธสาย
answer()	answer(callId, option?, allowNoneCamera?)	รับสาย
hangup()	hangup(callId)	วางสาย
hold()	hold(callId)	พักสาย
unhold()	unhold(callId)	รับสายคืน
mute()	mute(callId)	ปิดเสียง
unmute()	unmute(callId)	เปิดเสียง
dtmf()	dtmf(callId, dtmf)	ส่ง DTMF tone
blindTransfer()	blindTransfer(callId, number)	โอนสายแบบ blind
attendedTransfer()	attendedTransfer(callId, number)	โอนสายแบบ attended
startRecord()	startRecord(callId)	เริ่มบันทึกสาย
pauseRecord()	pauseRecord(callId)	หยุดบันทึกชั่วคราว
terminate()	terminate(callId, type)	สิ้นสุดสาย (hangup/reject/terminate)
audioToVideo()	audioToVideo(callId)	เปลี่ยนเป็น video call (Web/Windows เท่านั้น)
videoToAudio()	videoToAudio(callId)	เปลี่ยนกลับเป็น audio call
disconnect()	disconnect()	ยกเลิก SIP registration
destroy()	destroy()	ทำลาย PhoneOperator

PhoneOperator Events:

Event	คำอธิบาย
connected	เชื่อมต่อ SIP service สำเร็จ
registered	SIP UA registration สำเร็จ
incoming	มีสายเข้า
startSession	Call session เริ่มต้น
newRTCSession	RTC session ใหม่ถูกสร้าง
deleteSession	Call session ถูกลบ
recordPermissionsChange	สิทธิ์บันทึกสายเปลี่ยน
isRegisteredChange	สถานะ registration เปลี่ยน

Web UI / Windows UI (Pre-built)

import { init } from 'ys-webrtc-sdk-ui';
import 'ys-webrtc-sdk-ui/lib/ys-webrtc-sdk-ui.css';
 
const container = document.getElementById('container');
init(container, {
    username: '1000',
    secret: 'sdklogin_sign',
    pbxURL: 'https://192.168.1.1:8088'
}).then(data => {
    const { phone, pbx, destroy, on } = data;
});

UI Components ที่ได้: Dialpad, Incoming call popup, Call session window (hold/mute/transfer/record/DTMF)

---

Android SDK

• ติดตั้ง: เพิ่ม AAR file เข้า Android project
• Auth: เหมือนกัน — OpenAPI sign/create → ได้ login signature
• Features: make/answer/reject/hangup/hold/transfer/mute/record/DTMF
• Conference calls: รองรับ
• CDR: query ได้
• Push notifications: รองรับ FCM push notifications
• Requirement: Ultimate Plan

---

iOS SDK

• ติดตั้ง: CocoaPods หรือ manual
• Requirements: iOS 11+, Xcode 14.3+, APNs certificate สำหรับ push notifications
• Features: เหมือน Android (make/answer/reject/hangup/hold/transfer/mute/record/DTMF)
• Push: APNs (Apple Push Notification Service)
• Requirement: Ultimate Plan

---

macOS SDK

• ติดตั้ง: CocoaPods หรือ manual
• Requirements: macOS 10.13+, Xcode 14.3+
• Features: เหมือน iOS
• Requirement: Ultimate Plan

---

Error Codes สำคัญ

Code	Message	คำอธิบาย
-106	LINKUS_DISABLED	Linkus UC client ถูก disable
-107	LOGGED_IN_ELSEWHERE	Extension login จาก device อื่นอยู่แล้ว
-108	EXTENSION_DELETED	Extension ถูกลบ
-109	RE_LOGIN	Extension ต้อง login ใหม่
-110	SDK_PLAN_DISABLED	PBX plan ไม่ใช่ Ultimate Plan
-202	GET_AGREE_CHROME_USER_MEDIA_ROLE_ERROR	Browser ไม่ได้อนุญาต microphone/camera
-205	MAX_LIMIT_CALL	Concurrent calls เต็ม
-209	INVALID_NUMBER	หมายเลขไม่ถูกต้อง

---

ความเชื่อมโยง

• Yeastar P-Series — PBX ที่รองรับ Linkus SDK (P550/P560/P570)
• Yeastar P-Series API — ใช้ sign/create endpoint ในการขอ login signature
• Yeastar P-Series Features — Linkus UC client ที่ SDK เชื่อมต่อ
• OpenClaw — personal AI assistant ที่ใช้ pattern integration คล้ายกัน

---

🇬🇧 English

Linkus SDK from Yeastar P-Series allows developers to embed Linkus softphone functionality directly into third-party web, desktop, and mobile applications. Supports 5 platforms: Web, Windows, Android, iOS, and macOS.

Requirement: Ultimate Plan (UP) + Firmware 37.12.0.23 or later

---

Authentication Flow (All Platforms)

All platforms use the same Linkus SDK login signature flow:

1. Enable Linkus SDK in PBX: Integrations > Linkus SDK > Enable > Save
2. Get access token (on your app server):

   POST {pbx_url}/openapi/v1.0/get_token
   Body: { "username": "<AccessID>", "password": "<AccessKey>" }
   

3. Request login signature for an extension:

   POST {pbx_url}/openapi/v1.0/sign/create?access_token={token}
   Body: { "username": "1000", "sign_type": "sdk", "expire_time": 0 }
   → Returns: { "data": { "sign": "<login_signature>" } }
   

4. Initialize SDK on the client with the signature:

   init({ username: '1000', secret: '<sign>', pbxURL: 'https://...' })

---

Web / Windows SDK

Both use the same npm packages. Initialization returns:

• PBXOperator — CDR query (cdrQuery()), logout, events (runtimeError, cdrChange)
• PhoneOperator — All call features: start/call/answer/reject/hangup/hold/mute/transfer/record/DTMF/video
• destroy — Teardown the SDK instance

Core package: npm install ys-webrtc-sdk-core
UI package (pre-built): npm install ys-webrtc-sdk-ui

---

Mobile / Desktop SDKs

Platform	Requirements	Key Features
Android	Ultimate Plan, AAR package	Call features, CDR, push (FCM)
iOS	iOS 11+, Xcode 14.3+, APNs cert	Call features, CDR, push (APNs)
macOS	macOS 10.13+, Xcode 14.3+	Call features, CDR

All mobile/desktop SDKs use the same sign/create OpenAPI endpoint for authentication.

---

Related Pages

• Yeastar P-Series — Parent PBX platform
• Yeastar P-Series API — sign/create endpoint for SDK authentication
• Yeastar P-Series Features — Linkus UC client features