nobox-ai/chat-sdk

Official PHP SDK and Real-time SignalR WebSocket Client for NoBox.Ai platform integration

dev-main 2026-07-29 04:26 UTC

Requires

• php: >=7.4
• ext-curl: *
• ext-json: *

MIT

• NoBox.Ai Team

• websocket
• sdk
• chat
• whatsapp
• webhook
• inbox
• nobox
• nobox-ai
• signalr

Published on Packagist.org on 2026-07-29 07:36 UTC

README

Contoh aplikasi chat web dan PHP SDK untuk integrasi NoBox.Ai menggunakan REST API, WebSocket SignalR, dan Webhook HMAC-SHA256.

🔗 Live Demo: https://nobox-chat-php.ubigdev.com/ | 📦 Packagist: https://packagist.org/packages/nobox-ai/chat-sdk

📸 Tampilan Aplikasi (Preview)

Project ini ditujukan sebagai referensi implementasi lengkap agar developer dapat memahami alur autentikasi, membaca daftar percakapan (chatroom), membaca riwayat pesan, mengirim pesan multimedia, menerima event real-time via WebSocket, dan memproses Webhook secara aman.

📦 Instalasi via Composer

Jika Anda menggunakan Composer (Laravel, CodeIgniter, Symfony, dll):

composer require nobox-ai/chat-sdk

Atau cukup menyalin file nobox_chat.php untuk proyek PHP Native tanpa Composer (require_once 'nobox_chat.php';).

🚀 Peruntukan Repository

• Demo Chat Berbasis Web: Aplikasi siap pakai untuk pengujian fitur chat secara langsung.
• Single-File PHP SDK: Library PHP ringan (nobox_chat.php) tanpa dependensi eksternal yang rumit.
• REST API & SignalR WebSocket Reference: Contoh pemanggilan endpoint REST API dan koneksi WebSocket SignalR.
• Secure Webhook Handler: Receiver webhook dengan validasi signature HMAC-SHA256.

✨ Fitur Utama

• 🔑 Autentikasi: Login ke NoBox.Ai untuk mendapatkan JWT/Bearer Token secara dinamis.
• 📋 Daftar Percakapan: Menampilkan daftar chatroom, channel, dan akun terhubung.
• 💬 Riwayat Pesan: Memuat riwayat chat berdasarkan room secara terstruktur.
• ✉️ Pengiriman Pesan Multi-Media: Send text, image, audio, video, file/document, sticker, dll.
• 📡 Real-time WebSocket SignalR: Membaca pesan masuk dan mengirim pesan instan via koneksi /messagehub.
• 🔍 Panel Debug Console: Memantau endpoint, status HTTP, payload request/response terformat yang lengkap, serta contoh snippet kode SDK PHP.
• 🔒 Webhook Event Handler: Verifikasi signature header X-Nobox-Signature-256 untuk keamanan data webhook.
• 📱 Responsive UI & Resizer: Tampilan modern, resizer panel interaktif, dan navigasi adaptive di desktop maupun mobile.

📁 Struktur Project

.
├── index.php                 # Demo aplikasi chat berbasis web (UI, Debug Console, Snippet)
├── nobox_chat.php            # Core PHP SDK Class (NoboxChat)
├── nobox_chat_webhook.php    # Endpoint handler contoh untuk Webhook receiver
├── nobox_chat_websocket.js  # Client JS wrapper untuk WebSocket SignalR
├── signalr.min.js            # Library SignalR Client official
├── docs/
│   └── images/
│       ├── Nobox-c.png       # Logo aplikasi
│       └── demo_preview.jpg  # Screenshot tampilan aplikasi
├── .gitlab-ci.yml
├── .gitignore
├── LICENSE
└── README.md

📄 Penjelasan File

File	Fungsi
index.php	Demo aplikasi chat berbasis web. Memuat UI, login, daftar percakapan, chat, upload file, debug panel, dan snippet integrasi.
nobox_chat.php	SDK PHP utama (NoboxChat). Mengangani autentikasi, cURL REST API, upload file, render script WebSocket, dan validasi signature webhook.
nobox_chat_websocket.js	Client JavaScript untuk koneksi SignalR WebSocket, join room, menerima pesan, ACK, dan kirim pesan real-time.
nobox_chat_webhook.php	Contoh endpoint webhook untuk menerima event HTTP POST dari NoBox.Ai secara aman.
signalr.min.js	Library SignalR JS client yang dibutuhkan oleh nobox_chat_websocket.js.

⚙️ Requirements

• PHP: 7.4 atau lebih baru.
• PHP Extensions: curl dan json aktif.
• Web Server: Nginx (sangat direkomendasikan untuk performa tinggi & penanganan reverse proxy / WebSocket), atau Apache, Laragon, XAMPP.
• Browser: Browser modern yang mendukung WebSocket.
• Akun NoBox.Ai: Memiliki akses ke chatroom NoBox.Ai.
• Base URL Backend: Contoh https://id.nobox.ai/.

💻 Cara Menjalankan Secara Lokal

1. Clone Repository

git clone https://gitlab.ubig.co.id/erik/nobox-chat-php.git

Letakkan folder project di direktori web server (contoh Nginx: /var/www/nobox-chat-php atau XAMPP: C:\xampp\htdocs\nobox-chat-php).

2. Jalankan Web Server

Sangat direkomendasikan menggunakan Nginx bersama PHP-FPM untuk performa terbaik, atau aktifkan Apache dari XAMPP Control Panel.

💡 Contoh Konfigurasi Nginx (klik untuk membuka)

```nginx server { listen 80; server_name localhost; root /var/www/nobox-chat-php; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } } ```

3. Buka Aplikasi di Browser

Akses URL lokal:

http://localhost/nobox-chat-php/

Or access Live Demo: https://nobox-chat-php.ubigdev.com/

5. Login

Masukkan kredensial akun NoBox.Ai:

• Base URL Backend: https://id.nobox.ai/
• Username / Email: Email akun NoBox.Ai Anda
• Password: Password akun NoBox.Ai Anda

🔄 Alur Kerja Aplikasi

Login User
  │
  ├── Generate Token (AccountAPI/GenerateToken)
  │
  ├── Load Account & Channel
  │
  ├── Load Daftar Chatrooms
  │
  ├── Connect WebSocket SignalR (/messagehub)
  │
  └── User Memilih Room
        │
        ├── Load Riwayat Pesan (REST API)
        ├── Join Room (WebSocket)
        └── Kirim Pesan (REST API / WebSocket)

📖 Panduan Penggunaan PHP SDK (nobox_chat.php)

Inisialisasi SDK

<?php
require_once 'nobox_chat.php';

// Inisialisasi awal
$nobox = new NoboxChat();

// Login & dapatkan token
$result = $nobox->generateToken('[e-mail]', 'password');

if (!$result['IsError']) {
    $token = $result['Data'];
    echo 'Token Auth: ' . $token;
} else {
    echo 'Login Gagal: ' . $result['Error'];
}

Mengambil Daftar Percakapan & Riwayat Chat

<?php
// Jika menggunakan Composer: require_once 'vendor/autoload.php';
// Jika tanpa Composer:     require_once 'nobox_chat.php';

$token = 'TOKEN_ANDA';
$nobox = new NoboxChat($token, 'https://id.nobox.ai/');

// Ambil 20 percakapan terbaru
$chatrooms = $nobox->fetchChatrooms(20);

// Ambil pesan dari room tertentu
$roomId = 123456789;
$messages = $nobox->fetchMessages($roomId);

Mengirim Pesan via REST API

<?php
// Jika menggunakan Composer: require_once 'vendor/autoload.php';
// Jika tanpa Composer:     require_once 'nobox_chat.php';

$nobox = new NoboxChat('TOKEN_ANDA');

$response = $nobox->sendMessage(
    extId: '628123456789',   // ID eksternal / nomor WA penerima
    channelId: 1,            // ID Channel
    accountId: '123',        // ID Account pengirim
    text: 'Halo dari PHP SDK!',
    bodyType: 1              // 1 = Text
);

print_r($response);

Tipe Pesan (bodyType)

Kode	Tipe Pesan	Deskripsi / Format Payload
1	Text	Pesan teks biasa (body)
2	Audio	File suara / rekaman
3	Image	File gambar (JPEG, PNG, WebP)
4	Video	File video (MP4)
5	File / Document	File dokumen (PDF, DOCX, ZIP, dll)
6	Sticker	File stiker animasi / WebP
7	Location	Koordinat lokasi geografis
8	Contact	Kartu kontak VCard

🖼️ Pengiriman Pesan Media & Attachment (Gambar, Audio, Video, File/Dokumen)

Pengiriman pesan media selain teks biasa memerlukan 2 langkah:

1. Upload file (Base64) ke server NoBox.Ai menggunakan uploadBase64ToFile() untuk memperoleh metadata file (Filename & OriginalName).
2. Kirim pesan media dengan kode bodyType yang sesuai (misal 3 Gambar, 4 Video, 5 Dokumen) dan kirimkan JSON array metadata attachment.

<?php
// Jika menggunakan Composer: require_once 'vendor/autoload.php';
// Jika tanpa Composer:     require_once 'nobox_chat.php';

$nobox = new NoboxChat('TOKEN_BEARER_ANDA');

// 1. Convert file lokal ke Base64 Data URI
$filePath = 'dokumen.pdf';
$fileData = base64_encode(file_get_contents($filePath));
$base64Data = 'data:application/pdf;base64,' . $fileData;

// 2. Upload file ke server NoBox.Ai
$uploadRes = $nobox->uploadBase64ToFile([
    'Media' => [
        'Filename' => 'dokumen.pdf',
        'Mimetype' => 'application/pdf',
        'Data' => $base64Data
    ]
]);

if (!$uploadRes['IsError']) {
    $uploadedFile = $uploadRes['Data']; // Array ['Filename' => 'xyz.pdf', 'OriginalName' => 'dokumen.pdf']

    // 3. Kirim Pesan Dokumen (bodyType: 5)
    $sendRes = $nobox->sendMessage(
        extId: '628123456789',
        channelId: 1,
        accountId: '123',
        text: '', // Body dapat dikosongkan untuk file
        bodyType: 5, // 5 = File / Document
        attachment: json_encode([$uploadedFile]) // Array JSON String
    );

    print_r($sendRes);
}

📡 Integrasi Real-time WebSocket (SignalR)

WebSocket digunakan untuk menerima pesan baru dan event realtime tanpa perlu polling.

Integrasi di Client Side (JavaScript)

<script src="signalr.min.js"></script>
<script src="nobox_chat_websocket.js"></script>
<script>
  (async function () {
    const client = new NoboxChatClient("https://id.nobox.ai/", "TOKEN_ANDA");

    // Listener pesan masuk
    client.onMessage(function (room, message) {
      console.log("Pesan masuk:", room, message);
    });

    // Listener status pengiriman (ACK)
    client.onAck(function (roomId, msgId, status) {
      console.log("Status Pesan (ACK):", status);
    });

    await client.connect();
    await client.joinRoom("ROOM_ID");
    
    // a) Kirim Pesan Teks Real-time via WebSocket
    await client.sendMessage("ROOM_ID", "Halo via WebSocket", "ACCOUNT_ID");

    // b) Kirim Pesan Media (Gambar/File) Real-time via WebSocket
    const fileObj = { Filename: "808940173950_1785.jpg", OriginalName: "foto.jpg" };
    const linkId = null;
    const bodyType = 3; // 3 = Image
    await client.sendMessage("ROOM_ID", "", "ACCOUNT_ID", linkId, JSON.stringify(fileObj), bodyType);
  })();
</script>

🔒 Konfigurasi & Validasi Webhook Receiver

Menerima callback event Webhook dari NoBox.Ai secara aman menggunakan verifikasi signature HMAC-SHA256:

<?php
require_once 'nobox_chat.php';

$WEBHOOK_SECRET = getenv('NOBOX_WEBHOOK_SECRET') ?: 'whsec_secret_key_anda';

// 1. Ambil raw payload dan signature header
$rawPayload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_NOBOX_SIGNATURE_256'] ?? $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';

// 2. Verifikasi keaslian signature HMAC-SHA256 (timing-safe)
$isValid = NoboxChat::verifyWebhookSignature($rawPayload, $signature, $WEBHOOK_SECRET);

if (!$isValid) {
    http_response_code(401);
    echo json_encode(['error' => 'Unauthorized: Signature invalid']);
    exit;
}

// 3. Olah payload event (contoh: simpan ke database)
$eventData = json_decode($rawPayload, true);
http_response_code(200);
echo json_encode(['status' => 'success']);

🛡️ Catatan Keamanan & Best Practices

• 🔒 Manajemen Kredensial: Simpan token, password, dan secret di Environment Variable (.env).
• 🛡️ Verifikasi Webhook: Selalu gunakan NoboxChat::verifyWebhookSignature untuk memverifikasi signature X-Nobox-Signature-256.
• 📡 Enkripsi SSL/TLS: Wajib menggunakan HTTPS untuk komunikasi Webhook dan SignalR WebSocket di lingkungan produksi.

📄 Lisensi

Project ini berlisensi MIT License.

🔗 Link & Repository

• Live Demo App: https://nobox-chat-php.ubigdev.com/
• GitLab Repository: https://gitlab.ubig.co.id/erik/nobox-chat-php