NoBox.Ai Chat Python SDK (nobox-chat-sdk)

Official Python Client SDK and Real-time Webhook Receiver Application for NoBox.Ai Omnichannel Platform Integration.

🔗 GitLab Repository: https://gitlab.ubig.co.id/erik/nobox-chat-python

🐍 Preview Aplikasi Demo & Interactive Console Inspector

Package ini menyediakan solusi Python SDK lengkap (dukungan Python 3.7+) yang dilengkapi dengan Service REST API, Webhook HMAC-SHA256 Verifier & Parser, serta Flask Web Application & Interactive Traffic Inspector bawaan untuk mempermudah debugging dan integrasi platform NoBox.Ai.

📦 Instalasi & Dependensi

Opsi A: Instalasi via PyPI / Pip

pip install nobox-chat-sdk

Atau instalasi langsung dari Git Repository:

pip install git+https://gitlab.ubig.co.id/erik/nobox-chat-python.git

Opsi B: Import Library di Kode Python

from nobox_chat import NoboxChat

# Inisialisasi SDK
nb = NoboxChat(base_url="https://id.nobox.ai/", app_name="NoBoxChatPython", app_version="1.0.0")

✨ Fitur Utama

• 🔑 Autentikasi Native Python: Login ke NoBox.Ai REST API untuk memperoleh Bearer Token secara otomatis.
• 📋 Chatrooms & Messages Manager: Service intuitif untuk mengambil daftar percakapan, channel, akun WhatsApp terhubung, serta riwayat pesan.
• 📤 Fast Message Dispatcher & Media Upload: Mengirim pesan teks dan konversi attachment base64 ke URL media secara langsung.
• 🔐 Webhook HMAC-SHA256 Verifier & Event Parser: Verifikasi keamanan signature X-Nobox-Signature-256 dan parsing event payload otomatis (TerimaPesan, TerimaAck, TerimaRead).
• 📊 AppInfo & Metadata Tracking: Melacak header metadata X-App-Name: NoBoxChatPython dan X-App-Version: 1.0.0 pada setiap request API.

📂 Struktur Repositori

nobox-chat-python/
├── setup.py                      # Konfigurasi PyPI Package Installer
├── requirements.txt              # Dependensi Python (requests, flask)
├── README.md                     # Dokumentasi Resmi Python SDK
├── nobox_chat.py                # Core Python SDK Library (`NoboxChat`)
├── app.py                        # Flask Web Application & Webhook Receiver
├── templates/
│   └── index.html                # Frontend Web UI Demo
└── static/                       # Custom CSS/JS Static Assets

📖 Panduan Penggunaan Python SDK (NoboxChat)

1. Autentikasi & Generate Token

from nobox_chat import NoboxChat

nb = NoboxChat()

# Login untuk mendapatkan Bearer token
result = nb.generate_token("user@example.com", "password")

if not result["IsError"]:
    token = result["Data"]
    print("Token Berhasil Didapatkan:", token)
else:
    print("Gagal Login:", result["Error"])

2. Mengambil Daftar Percakapan & Riwayat Chat

# 1. Ambil 20 Percakapan Teratas
chatrooms = nb.fetch_chatrooms(take=20)
print("Daftar Chatroom:", chatrooms["Data"])

# 2. Ambil Riwayat Pesan berdasarkan Room ID
messages = nb.fetch_messages(room_id="ROOM_ID_123", take=50)
print("Riwayat Pesan:", messages["Data"])

3. Mengirim Pesan Teks & Media via REST API

# 1. Mengirim Pesan Teks
send_res = nb.send_message(
    ext_id="628123456789",
    channel_id=1,
    account_id="744927678136325",
    text="Halo dari Python SDK NoBox.Ai!"
)

# 2. Upload Attachment Base64
with open("photo.jpg", "rb") as f:
    import base64
    b64_data = base64.b64encode(f.read()).decode("utf-8")

upload_res = nb.upload_base64_to_file({
    "media": {
        "filename": "photo.jpg",
        "mimetype": "image/jpeg",
        "data": b64_data
    }
})

4. Webhook Verification & Event Handler

from nobox_chat import NoboxChat

# Verifikasi & Parse Payload Webhook HMAC-SHA256
try:
    event_data = NoboxChat.handle_webhook(
        payload_body=raw_json_body,
        signature_header=request_headers.get("X-Nobox-Signature-256"),
        webhook_secret="YOUR_WEBHOOK_SECRET",
        throw_error=True
    )
    print("Webhook Valid! Event:", event_data)
except ValueError as e:
    print("Webhook Invalid:", str(e))

🌐 Menjalankan Flask Application Demo secara Lokal

Untuk menjalankan aplikasi demo Web UI & Webhook receiver lokal:

pip install -r requirements.txt
python app.py

Buka browser Anda di: http://localhost:5001 atau http://127.0.0.1:5001.

📄 Lisensi

Proyek ini dirilis di bawah lisensi MIT License.