Guide to Integrating AlohubPhone SDK v3

Documentation for developers who want to integrate Alohub's WebRTC phone into their website/web application.

Table of Contents

Overview
Prerequisites Before Getting Started
SDK Installation
Basic Integration (5 minutes)
Widget Interface
Advanced Integration — Headless Mode
CRM Integration — Click-to-Call
Error Handling
Microphone & Access Permissions
Features During Calls
Multilingual Support
Build & Deployment
Frequently Asked Questions

1. Overview

What is AlohubPhone SDK v3?

AlohubPhone SDK v3 is a JavaScript library that allows embedding a WebRTC phone directly into a website. Employees can make and receive calls right in the browser without needing to install software.

Key Features

Feature	Description
1 JS file	Combines everything into a single file (~375KB, ~95KB gzip)
2 parameters	Just need `apiKey`+ `userName`
Security	SIP credentials are never exposed
Shadow DOM	Completely isolated CSS, does not affect the website
Cross-platform	WordPress, React, Vue, Angular, plain HTML, ...
6 languages	Vietnamese, English, 日本語, 한국어, 中文, ภาษาไทย

2. Prerequisites Before Getting Started

Alohub Account

You need to have:

✅ API Key — Contact Alohub to obtain an API Key
✅ userName — Alohub account username (e.g.: admin.alohub)

Technical Requirements

Requirement	Details
Browser	Chrome 60+, Firefox 55+, Edge 79+, Safari 11+, CocCoc
HTTPS	Required in production (localhost is exempt)
Microphone	Requires microphone access

Note: The SDK only works with Alohub's PBX. Cannot be used with other PBXs. Contact Alohub to register for a PBX.

3. SDK Installation

Method 1: CDN (recommended)

Add a script line to the HTML page:

<!-- Production -->
<script src="https://cdn.alohub.vn/sdk/v3/alohub-phone.prod.min.js"></script>

<!-- Development (server test) -->
<script src="https://cdn.alohub.vn/sdk/v3/alohub-phone.dev.min.js"></script>

Method 2: Self-host

Download the file alohub-phone.prod.min.js, place it in the static folder, add a script tag:

<script src="/assets/js/alohub-phone.prod.min.js"></script>

Difference Between Dev and Prod

File	Server	Purpose
`.dev.js`	`{{protocol}}://{{host}}:{{port}}`(dev)	Test, development
`.prod.js`	`{{protocol}}://{{host}}`(prod)	Production

4. Basic Integration (5 minutes)

Step 1: Add SDK to the page

Place the following code before the tag </body>:

<script src="https://cdn.alohub.vn/sdk/v3/alohub-phone.prod.min.js"></script>
<script>
  AlohubPhone.init({
    apiKey: 'YOUR_API_KEY',      // Thay bằng API key thật
    userName: 'your.username',    // Thay bằng username thật
  });
</script>

Step 2: Widget Automatically Appears

After adding the code, the phone widget appears in the bottom right corner of the webpage. The widget displays:

Header : Connection status (green dot = online) + extension number
Number input box : Enter the phone number to call + call button
Keypad : Press "Show Keypad" to display the full numpad

Step 3: Customize Interface + Error Handling

AlohubPhone.init({
  apiKey: 'YOUR_API_KEY',
  userName: 'your.username',

  // Giao diện
  theme: 'dark',               // 'light' (mặc định) hoặc 'dark'
  position: 'bottom-left',     // Vị trí widget (xem bảng bên dưới)
  language: 'vi',              // vi, en, ja, ko, zh, th

  // Hành vi
  autoAnswer: false,           // false = hiện popup khi có cuộc gọi đến
  debug: true,                 // true = hiện log trong console

  // Callbacks
  onReady: function(phone) {
    console.log('Sẵn sàng! Mic:', phone.getMicPermission());
  },
  onError: function(e) {
    console.error('[' + e.code + ']', e.message);
  },
  onAuthFailed: function(e) {
    console.error('Xác thực thất bại:', e.code, e.message);
  }
});

Widget Position

Value	Position
`bottom-right`	Bottom right corner (default)
`bottom-left`	Bottom left corner
`top-right`	Top right corner
`top-left`	Top left corner

5. Widget Interface

The SDK provides 5 screens that automatically switch according to the call status:

Screen	When	Displays
1. Dial	Default	Number input box + call button + "Show Keypad"
2. Dial + Keypad	Press "Show Keypad"	Numpad 0-9, *, # with letters ABC/DEF + delete button ⌫ + large Call button
3. Ringing	Outgoing call	Number being called + red "End" button
4. Incoming	Incoming call	Incoming number + red "Decline" / green "Accept" button
5. Answering	Answering	Number + timer + "End" + "Show Keypad" + "Transfer Call"

Header status bar

Dot	Status	When
🟢 Green	Online	SIP registered, ready to call
🟡 Yellow (blinking)	Connecting	Connecting WebSocket/SIP
🔴 Red	Offline	Disconnected / registration failed
🔵 Blue (blinking)	Calling	In a call

6. Advanced Integration — Headless Mode

When you want to design your own interface , use headless: true. The SDK will not create any UI, only provide APIs and events.

AlohubPhone.init({
  apiKey: 'YOUR_API_KEY',
  userName: 'your.username',
  headless: true,              // ← Không tạo UI widget

  onReady: function(phone) {
    // phone là instance SDK — điều khiển hoàn toàn bằng code
    console.log('Sẵn sàng!');

    phone.on('incoming', function(data) {
      showMyPopup('Cuộc gọi từ: ' + data.remoteNumber);
    });

    phone.on('answered', function(data) {
      showMyCallScreen(data.remoteNumber);
    });

    phone.on('ended', function(data) {
      hideMyCallScreen();
      saveCallLog(data);
    });

    phone.on('error', function(e) {
      showMyError(e.code, e.message);
    });
  }
});

Comparison of 2 Modes

	With Widget (default)	Headless
Interface	Widget automatically	You code it yourself
DTMF / Mute / Hold	Available on widget	`phone.sendDTMF()`, `phone.mute()`, ...
Events	Complete	Complete (same)
`phone.ui`	Available	`null`

7. CRM Integration — Click-to-Call

<!-- Nút gọi trong CRM -->
<button class="btn-call" data-phone="0901234567">📞 Gọi</button>

<script>
  var phone = null;

  AlohubPhone.init({
    apiKey: 'YOUR_API_KEY',
    userName: 'your.username',
    headless: true,
    onReady: function(p) {
      phone = p;

      // Ghi log cuộc gọi khi kết thúc
      phone.on('ended', function(data) {
        fetch('/api/call-logs', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            phone: data.remoteNumber,
            duration: data.duration,
            direction: data.direction
          })
        });
      });
    }
  });

  // Click-to-Call với extra SIP headers
  document.querySelectorAll('.btn-call').forEach(function(btn) {
    btn.addEventListener('click', function() {
      if (phone) phone.call(this.dataset.phone, {
        extraHeaders: ['X-CRM-INFO: lead|123']
      });
    });
  });
</script>

8. Error Handling

Error handling flow

The SDK provides 3 layers of error catching:

onAuthFailed(e) — Authentication failed (before SDK is ready): MISSING_API_KEY, MISSING_USERNAME, INVALID_API_KEY, DOMAIN_NOT_WHITELISTED
.catch(err) — SIP registration failed: REGISTRATION_FAILED, REGISTRATION_TIMEOUT
phone.on('error', fn) — All runtime errors: MIC_NOT_FOUND, MIC_DENIED, CALL_MEDIA_FAILED, CALL_NO_NUMBER, CALL_NOT_READY, ...

Error handling code

phone.on('error', function(e) {
  // e.code    — Mã lỗi chuẩn (AlohubPhone.ERROR.*)
  // e.type    — Nhóm: 'mic', 'call', 'dtmf', 'transfer'
  // e.message — Mô tả chi tiết

  switch (e.code) {
    case AlohubPhone.ERROR.MIC_NOT_FOUND:
      alert('Không tìm thấy microphone!');
      break;
    case AlohubPhone.ERROR.MIC_DENIED:
      alert('Microphone bị từ chối.');
      phone.requestMicPermission(); // Yêu cầu lại
      break;
    case AlohubPhone.ERROR.CALL_MEDIA_FAILED:
      alert('Lỗi microphone khi gọi.');
      break;
    case AlohubPhone.ERROR.CALL_NOT_READY:
      alert('Điện thoại chưa sẵn sàng.');
      break;
  }
});

// Cuộc gọi thất bại — có SIP code chi tiết
phone.on('failed', function(e) {
  console.log(e.sipCode, e.sipReason);
  // 480 "Temporarily Unavailable"
  // 486 "Busy Here"
});

Error code table

Error code	Group	Description
`MIC_NOT_FOUND`	mic	No microphone
`MIC_DENIED`	mic	Mic access denied
`CALL_MEDIA_FAILED`	mic	Mic error during call (JsSIP `getusermediafailed`)
`CALL_NO_NUMBER`	call	Missing phone number
`CALL_NOT_READY`	call	SIP not registered
`DTMF_INVALID`	dtmf	Invalid DTMF character
`TRANSFER_NO_CALL`	transfer	Transfer when no call
`API_CALL_FAILED`	api	Call via API failed

Common SIP Error Codes

SIP Code	Meaning
480	Temporarily Unavailable — Recipient not online
486	Busy Here — Busy
487	Request Terminated — Call canceled
603	Decline — Recipient declined
404	Not Found — Number does not exist

9. Microphone & Access Permissions

The SDK automatically requests mic permission after SIP registration. If denied, it can request again:

// Kiểm tra trạng thái (đồng bộ)
phone.getMicPermission();  // 'granted' | 'denied' | 'unknown'

// Yêu cầu lại (hiện popup browser)
phone.requestMicPermission().then(function(status) {
  console.log('Mic:', status); // 'granted' hoặc 'denied'
});

// Lắng nghe thay đổi
phone.on('micPermission', function(e) {
  if (e.status === 'denied') {
    alert('Vui lòng cho phép microphone!');
  }
});

Note: If the user has clicked "Block" on the browser, requestMicPermission()it will be denied immediately without showing a popup. The user must go to Settings > Site Settings > Microphone to unblock.

10. Features During Calls

Group	Method	Description
Call	`phone.call(num, opts?)`	Outgoing call (opts: `{extraHeaders: [...]}`)
	`phone.answer()`	Answer
	`phone.hangup()`	End / decline
DTMF	`phone.sendDTMF(tone)`	Send key presses (0-9, *, #, A-D)
Mic	`phone.mute() / unmute()`	Mute/unmute mic
Mic	`phone.toggleMute()`	Toggle status
Hold	`phone.hold() / unhold()`	Hold / resume
Hold	`phone.toggleHold()`	Toggle status
Transfer	`phone.transfer(target)`	Transfer call (blind transfer)
Status	`phone.isOnCall()`	On call?
	`phone.isMuted()`	Mic is off?
	`phone.isHeld()`	On hold?
	`phone.getCallInfo()`	Call details
Disconnect	`phone.unregister()`	Logout SIP (keep WebSocket)
	`phone.disconnect()`	Completely disconnect
	`phone.destroy()`	Cancel instance + remove UI + clear credentials

11. Multilingual Support

Code	Language	Interface Example
`vi`	Vietnamese (default)	Phone number, End, Answer
`en`	English	Phone Number, Hang Up, Answer
`ja`	日本語	電話番号, 終了, 応答
`ko`	한국어	전화번호, 종료, 받기
`zh`	中文	电话号码, 挂断, 接听
`th`	ภาษาไทย	หมายเลขโทรศัพท์, วางสาย, รับสาย

// Cài đặt khi khởi tạo
AlohubPhone.init({ apiKey: '...', userName: '...', language: 'en' });

// Đổi ngôn ngữ runtime
phone.ui.setLanguage('ja');

// Custom ngôn ngữ riêng (ví dụ tiếng Đức)
phone.ui.setLanguage({
  call: 'Anrufen',
  hangup: 'Auflegen',
  answer: 'Annehmen',
  reject: 'Ablehnen'
  // Các key thiếu sẽ fallback về tiếng Việt
});

12. Build & Deployment

Build from source

cd v3/
node build.js --dev       # → dist/alohub-phone.dev.js
node build.js --prod      # → dist/alohub-phone.prod.js
node build.js             # → cả hai

# Minify (cần cài terser)
npm install terser
node build.js             # → thêm dist/*.min.js

CSP (Content Security Policy)

If the website uses CSP, add:

Content-Security-Policy:
  connect-src wss://*.alohub.vn https://*.alohub.vn;
  media-src blob:;
  script-src 'self' https://cdn.alohub.vn;

13. Frequently Asked Questions

Q: Does the SDK work with other PBXs?

No. SDK v3 only works with Alohub IPCC.

Q: What if the microphone is denied?

Call phone.requestMicPermission()to request again. If blocked, the user must go to browser Settings > Site Settings > Microphone > unblock.

Q: Is there support for React / Vue / Angular?

Yes. The SDK is vanilla JS, works on any framework. Use headless: trueand then integrate into the component.

Q: Why did the call fail?

Listen to the failedevent — returns sipCodeand sipReason(e.g.: 480 "Temporarily Unavailable").

Q: How to logout?

phone.unregister()(only SIP) | phone.disconnect()(completely) | phone.destroy()(cancel + remove UI).

Q: Can it be used in an iframe?

Yes, add allow="microphone"to the <iframe>tag.

Q: Is there a limit on the number of simultaneous calls?

Each SDK instance supports 1 call. An incoming call while on a call will emit the callWaitingevent and automatically decline.

AlohubPhone SDK v3 — Contact Alohub — support@alohub.vn

ZNS API