Hướng dẫn tích hợp WebRTC phone

Tài liệu dành cho nhà phát triển muốn tích hợp điện thoại WebRTC của Alohub vào website/ứng dụng web.

Mục lục

1. Tổng quan

2. Yêu cầu trước khi bắt đầu

3. Cài đặt SDK

4. Tích hợp cơ bản (5 phút)

5. Giao diện Widget

6. Tích hợp nâng cao — Headless Mode

7. Tích hợp CRM — Click-to-Call

8. Xử lý lỗi

9. Microphone & Quyền truy cập

10. Các tính năng trong cuộc gọi

11. Đa ngôn ngữ

12. Build & Triển khai

13. Câu hỏi thường gặp

1. Tổng quan

AlohubPhone SDK v3 là gì?

AlohubPhone SDK v3 là thư viện JavaScript cho phép nhúng điện thoại WebRTC trực tiếp vào website. Nhân viên có thể gọi và nhận cuộc gọi ngay trên trình duyệt mà không cần cài phần mềm.

2. Yêu cầu trước khi bắt đầu

Tài khoản Alohub

Bạn cần có:

• ✅ API Key — Liên hệ Alohub để được cấp API Key

• ✅ userName — Tên đăng nhập tài khoản Alohub (ví dụ: admin.alohub)

Yêu cầu kỹ thuật

Lưu ý: SDK chỉ hoạt động với tổng đài Alohub. Không thể sử dụng với tổng đài khác. Liên hệ Alohub để đăng ký tổng đài.

3. Cài đặt SDK

Cách 1: CDN (khuyên dùng)

Thêm 1 dòng script vào trang HTML:

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

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

Cách 2: Tự host

Download file alohub-phone.prod.min.js, đặt vào thư mục static, thêm script tag:

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

Sự khác biệt giữa Dev và Prod

4. Tích hợp cơ bản (5 phút)

Bước 1: Thêm SDK vào trang

Đặt đoạn code sau trước thẻ </body>:

<script src="https://2.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>

Bước 2: Widget tự động xuất hiện

Sau khi thêm code, widget điện thoại xuất hiện ở góc dưới bên phải của trang web. Widget hiển thị:

• Header: Trạng thái kết nối (dot xanh lá = online) + số extension

• Ô nhập số: Nhập số điện thoại cần gọi + nút gọi

• Bàn phím: Bấm "Hiện bàn phím" để hiện numpad đầy đủ

Bước 3: Tùy chỉnh giao diện + xử lý lỗi

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);
  }
});

Vị trí widget

5. Giao diện Widget

SDK cung cấp 5 màn hình tự động chuyển đổi theo trạng thái cuộc gọi:

Trạng thái thanh header

6. Tích hợp nâng cao — Headless Mode

Khi bạn muốn tự thiết kế giao diện riêng, dùng headless: true. SDK sẽ không tạo UI nào cả, chỉ cung cấp API và 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);
    });
  }
});

So sánh 2 chế độ

7. Tích hợp CRM — 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. Xử lý lỗi

Luồng xử lý lỗi

SDK cung cấp 3 lớp bắt lỗi:

1. onAuthFailed(e) — Xác thực thất bại (trước khi SDK sẵn sàng): MISSING_API_KEY, MISSING_USERNAME, INVALID_API_KEY, DOMAIN_NOT_WHITELISTED

2. .catch(err) — SIP registration thất bại: REGISTRATION_FAILED, REGISTRATION_TIMEOUT

3. phone.on('error', fn) — Tất cả lỗi runtime: MIC_NOT_FOUND, MIC_DENIED, CALL_MEDIA_FAILED, CALL_NO_NUMBER, CALL_NOT_READY, ...

Code xử lý lỗi

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"
});

Bảng mã lỗi

SIP Error Codes phổ biến

9. Microphone & Quyền truy cập

SDK tự động xin quyền mic sau khi SIP registered. Nếu bị từ chối, có thể yêu cầu lại:

// 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!');
  }
});

Lưu ý: Nếu user đã bấm "Chặn" trên browser, requestMicPermission() sẽ bị từ chối ngay mà không hiện popup. User phải vào Settings > Site Settings > Microphone để bỏ chặn.

10. Các tính năng trong cuộc gọi

11. Đa ngôn ngữ

// 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 & Triển khai

Build từ 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)

Nếu website dùng CSP, thêm:

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

13. Câu hỏi thường gặp

Q: SDK có hoạt động với tổng đài khác không?

Không. SDK v3 chỉ hoạt động với tổng đài Alohub.

Q: Microphone bị từ chối thì sao?

Gọi phone.requestMicPermission() để yêu cầu lại. Nếu đã bị block, user phải vào browser Settings > Site Settings > Microphone > bỏ block.

Q: Có hỗ trợ React / Vue / Angular không?

Có. SDK là vanilla JS, hoạt động trên mọi framework. Dùng headless: true rồi tích hợp vào component.

Q: Cuộc gọi thất bại vì lý do gì?

Lắng nghe event failed — trả về sipCode và sipReason (ví dụ: 480 "Temporarily Unavailable").

Q: Làm sao logout?

phone.unregister() (chỉ SIP) | phone.disconnect() (hoàn toàn) | phone.destroy() (hủy + xóa UI).

Q: Dùng được trong iframe không?

Có, thêm allow="microphone" vào thẻ <iframe>.

Q: Có giới hạn số cuộc gọi đồng thời không?

Mỗi instance SDK hỗ trợ 1 cuộc gọi. Cuộc gọi đến khi đang gọi sẽ emit event callWaiting và tự động từ chối.

AlohubPhone SDK v3 — Liên hệ Alohub — [email protected]