Integration Documentation

Overview

BongoNet uses a REST API-based approach to connect with MikroTik routers. The routers communicate with the BongoNet cloud server via HTTP/HTTPS requests to validate vouchers, check sessions, fetch portal configurations, and send heartbeat signals.

Key Point: No RADIUS server needed - Simple HTTP/HTTPS communication!

Connection Architecture

┌─────────────────┐         HTTP/HTTPS         ┌──────────────────┐
│  MikroTik Router│ ◄────────────────────────► │  BongoNet Cloud │
│  (RouterOS)     │    API Calls + Token Auth   │  Server (Node.js)│
└─────────────────┘                             └──────────────────┘
        │                                               │
        │ Router Scripts                                │ Database
        │ (RouterOS Scripts)                            │ (SQLite)

System Features

Hotspot Management

Complete hotspot configuration with captive portal

PPPoE Management

ISP-grade PPPoE customer management

Payment Integration

Mobile money payment processing

Real-time Monitoring

Monitor router performance and devices

Getting Started

Step 1: Create Your Account

1 Sign Up

Visit https://bongonet.co/signup and create your account

Enter your phone number
Set a secure password
Verify your account

Step 2: Add Your Router

2 Register Router

After logging in, go to Dashboard → Routers → Add Router

Enter router name (e.g., "Main Office Router")
Enter router's public IP address
Select router type (Hotspot or PPPoE)
Click "Add Router"

Important: Use the router's PUBLIC IP address, not the local IP (192.168.x.x). The router must be able to reach the BongoNet server at 193.181.214.135 or bongonet.co.

Step 3: Get Your API Token

3 Copy API Token

After adding the router, you'll receive a unique API token

Go to Dashboard → Routers → View Router Details
Copy the API Token (starts with bongo_)
Save this token securely - you'll need it for RouterOS script

Example Token: bongo_abc123xyz789def456ghi012jkl345mno678pqr901stu234vwx567

Step 4: Download RouterOS Script

4 Download Configuration

In the router details page, click "Download RouterOS Script"

The script will be customized for your router
It includes your API token and router ID
Script auto-detects router interfaces

Quick Setup via Terminal (Copy & Paste)

For faster integration, use the ready-made commands from your BongoNet dashboard. No need to manually add tokens - everything is pre-configured!

Prerequisites:

Router added in BongoNet dashboard
Router must have internet access
Access to RouterOS terminal (Winbox, WebFig, or SSH)

Method 1: Copy Script from Dashboard (Recommended)

1 Go to Router Details

Login to your BongoNet dashboard
Navigate to Dashboard → Routers
Click "View Details" on your router
Scroll to the "Router Configuration" section

2 Copy the Script

Click the "View Script (Copy-Paste)" button
A modal will open showing the complete RouterOS script
Click "Copy Script" button - the script is already configured with your router ID and API token!
No manual editing needed - just copy and paste!

The script from dashboard includes:

✅ Your router ID (pre-configured)
✅ Your API token (pre-configured)
✅ Server URL (pre-configured)
✅ All necessary RouterOS commands

3 Paste into RouterOS Terminal

Open RouterOS terminal (Winbox Terminal, WebFig Terminal, or SSH)
Paste the copied script
The script runs automatically! No need to manually execute it.

# Just paste the script from dashboard - it executes immediately!

Method 2: Download Script File

1 Download from Dashboard

In router details page, click "Download Configuration Script"
A .rsc file will be downloaded to your computer
The file is already configured with your router ID and API token

2 Upload to Router

Option A - Via Winbox:

Open Winbox and connect to your router
Go to Files → Click "Upload"
Select the downloaded .rsc file
Wait for upload to complete

Option B - Via Terminal:

Upload file via SCP/SFTP to router
Or use Winbox Files → Upload

3 Import the Script

After uploading, run this command in RouterOS terminal:

/import file-name=bongo-router-[YOUR_ROUTER_ID]-config.rsc

Note: Replace [YOUR_ROUTER_ID] with the actual filename from the downloaded file.

Step 4: Verify Installation

Check if script was created successfully:

/system script print where name~"bongo"

You should see the bongo-heartbeat script listed.

Step 5: Test Server Connectivity (Optional)

Verify router can reach BongoNet server:

/ping bongonet.co count=3

Expected: 3 successful pings. If this fails, check router's internet connection.

View Script Logs

Check script execution logs:

/log print where message~"bongo"

This shows all log entries related to BongoNet integration.

Success Indicators:

Script imported without errors
Router appears as "Online" in BongoNet dashboard within 60 seconds
No error messages in logs
Heartbeat scheduler is running (check with: /system scheduler print)

Important:

Always use the script from your dashboard - it's pre-configured with your router ID and API token
No manual token editing needed - the dashboard provides ready-to-use commands
The script runs automatically when pasted into RouterOS terminal
If you need to update the script, re-download or re-copy from the dashboard

Router Setup

Prerequisites

Requirements:

MikroTik RouterOS version 6.0 or higher
Router must have internet access
Router must be able to reach bongonet.co or 193.181.214.135
DNS resolution working on router

Install RouterOS Script

1 Access Router

Login to your MikroTik router using Winbox or WebFig

2 Open Scripts

Navigate to System → Scripts

3 Paste Script

Click "+" to add new script
Name it: bongo-integration
Paste the downloaded script from BongoNet dashboard
Click "OK"

4 Run Script

Select the script
Click "Run Script"
Wait for script to complete (may take 1-2 minutes)
Check logs for any errors

Success Indicators:

Script runs without errors
Hotspot is configured (if hotspot router)
Router appears as "Online" in BongoNet dashboard
Heartbeat is received every 5-10 minutes

RouterOS Script Overview

The RouterOS script automatically performs the following:

1. Interface Detection

            # Auto-detect WAN interface
:local wanInterface
:foreach i in=[/interface find type=ether] do={
  :if ([/ip address find interface=$i] = "") do={
    :set wanInterface $i
  }
}

# Auto-detect WiFi interface
:local wifiInterface
:foreach i in=[/interface find type=wlan] do={
  :set wifiInterface $i
}
          

2. Hotspot Configuration (For Hotspot Routers)

            # Configure hotspot
/ip hotspot profile set [find name=default] html-directory=flash/hotspot
/ip hotspot set [find] interface=$wifiInterface disabled=no
/ip hotspot user profile set [find name=default] rate-limit="10M/5M"

# Set portal URL to BongoNet server
/ip hotspot profile set [find name=default] \
  hotspot-address=192.168.1.1 \
  http-cookie-lifetime=1d \
  html-directory=flash/hotspot
          

3. Heartbeat Script

The script includes a scheduler that sends heartbeat signals to BongoNet every 5-10 minutes:

            # Heartbeat script
:local apiToken "bongo_abc123xyz789..."
:local serverUrl "https://bongonet.co"
:local routerId "123"

/tool fetch url="$serverUrl/api/routers/$routerId/heartbeat" \
  http-method=post \
  http-header-field="X-Router-Token: $apiToken" \
  http-data="status=online&uptime=86400"
          

4. Session Check Script

For devices connecting to hotspot, the router checks if they have an active session:

            # Check device session
:local macAddress [/ip hotspot active get [find user=$user] mac-address]
:local apiToken "bongo_abc123xyz789..."
:local serverUrl "https://bongonet.co"

:local result [/tool fetch url="$serverUrl/api/vouchers/check-session" \
  http-method=post \
  http-data=("{\"token\":\"" . $apiToken . "\",\"mac_address\":\"" . $macAddress . "\"}") \
  as-value output=user]

:local hasAccess ($result->"data"->"has_access")

:if ($hasAccess = true) do={
  /ip hotspot user set [find name=$user] disabled=no
  :log info "Device $macAddress granted access"
} else={
  /ip hotspot user set [find name=$user] disabled=yes
  :log info "Device $macAddress denied - no session"
}
          

API Endpoints

All API calls require authentication using the X-Router-Token header.

Endpoint	Method	Purpose	Auth
`/api/routers/:id/heartbeat`	POST	Router status check	Token
`/api/vouchers/validate`	POST	Validate voucher code	Token
`/api/vouchers/check-session`	POST	Check device session	Token
`/api/portals/fetch`	GET	Get portal HTML	Token
`/api/routers/:id/devices`	GET	List connected devices	Token

Authentication

All requests must include the router's API token in the header:

X-Router-Token: bongo_abc123xyz789def456ghi012jkl345mno678pqr901stu234vwx567

Example: Heartbeat Request

            POST /api/routers/123/heartbeat
Headers:
  X-Router-Token: bongo_abc123xyz789...
Content-Type: application/x-www-form-urlencoded

Body:
  status=online&uptime=86400
          

Example: Session Check Request

            POST /api/vouchers/check-session
Headers:
  X-Router-Token: bongo_abc123xyz789...
Content-Type: application/json

Body:
{
  "token": "bongo_abc123xyz789...",
  "mac_address": "AA:BB:CC:DD:EE:FF"
}
          

Hotspot Configuration

How Hotspot Works

1. User connects to WiFi
   └─> Router shows captive portal

2. User selects bundle & mobile payment
   └─> Portal redirects to payment

3. User completes payment
   └─> Payment callback received

4. System creates session (status: 'pending')
   └─> Session stored in database

5. Router checks session (every 30 seconds)
   └─> POST /api/vouchers/check-session

6. System finds session
   └─> Returns {has_access: true}

7. Router grants internet access
   └─> Device can browse internet

8. Payment completes
   └─> Session upgraded to 'active'

Portal Configuration

Customize your captive portal in the BongoNet dashboard:

Go to Dashboard → Routers → View Router → Portal Settings
Upload your logo
Choose colors and fonts
Add welcome message
Configure bundle pricing

Bundle Management

Create internet bundles for your customers:

Go to Dashboard → Bundles → Add Bundle
Set bundle name (e.g., "1 Hour Package")
Set price in TZS
Set validity (minutes)
Set speed limit (e.g., "10M/5M" for 10Mbps down, 5Mbps up)

PPPoE Configuration

For ISP PPPoE Customers

BongoNet supports fixed internet (PPPoE) customer management:

Step 1: Configure PPPoE Server on Router

1 Enable PPPoE Server

In RouterOS, configure PPPoE server:

              /interface pppoe-server server add interface=ether1 service-name=bongo disabled=no
            

Step 2: Add PPPoE Customers

2 Create Customer Profiles

In BongoNet dashboard:

Go to Dashboard → Fixed Internet → Add Customer
Enter customer details (name, phone, address)
Set username and password
Select service plan
Router will automatically create PPPoE user

Step 3: Payment Integration

3 Customer Payments

Customers can pay via mobile money:

Customer receives payment link via SMS
Customer pays using mobile money
System automatically activates PPPoE connection
Router grants internet access

Note: The RouterOS script automatically handles PPPoE user creation and payment checking for fixed internet customers.

Troubleshooting

Router Not Connecting

Check Internet Connectivity

Test if router can reach BongoNet server:

              /ping 193.181.214.135
/ping bongonet.co
            

If ping fails, check router's internet connection and DNS settings.

Verify API Token

Ensure the API token in RouterOS script matches the token in BongoNet dashboard:

Go to Dashboard → Routers → View Router
Copy the API token
Compare with token in RouterOS script

Test API Call Manually

Test if router can communicate with server:

              /tool fetch url="https://bongonet.co/api/routers/123/heartbeat" \
  http-method=post \
  http-header-field="X-Router-Token: your-token-here" \
  http-data="status=test"
            

Check the result - should return success message.

Device Not Getting Internet After Payment

Check Session in Dashboard

Go to Dashboard → Devices
Look for the device's MAC address
Verify session status is "active"
Check if session hasn't expired

Check Router Logs

View router logs for session check attempts:

              /log print where message~"session"
/log print where message~"bongo"
            

Verify MAC Address

Ensure MAC address in session matches device MAC:

Check device MAC address (Settings → About Phone → MAC Address)
Compare with MAC in BongoNet dashboard
MAC addresses must match exactly

Script Errors

Common Issues:

JSON syntax errors in script
Missing variables or incorrect variable names
Interface detection fails (no WiFi or WAN interface found)
RouterOS version incompatible (need v6.0+)

Solution

Re-download the script from BongoNet dashboard
Script auto-detects everything and works with RouterOS v6.0+
Check router logs: /log print
Verify RouterOS version: /system resource print

Network Requirements

Router Must Have:

Internet access to reach BongoNet server
DNS resolution for bongonet.co or use IP 193.181.214.135
Firewall rules allowing HTTP/HTTPS outbound to server
RouterOS version 6.0 or higher

Server Information:

Public IP: 193.181.214.135
Domain: bongonet.co
Port: 443 (HTTPS) or 23000 (HTTP)

Need Help?

If you're still experiencing issues after following this guide:

Visit our Support page
Contact us at support@bongonet.co
Check router logs for detailed error messages
Verify all prerequisites are met