Quickstart

You will obtain an API key from the developer portal, then send a single SMS to your own phone. By the end you will have a message_id and a pending status from the sandbox.

What you need first

• A sandbox api_key from the Bloonio dev portal → Lisoloo → Developer.
• The sandbox base URL copied from the dev portal — exported as BASE_URL in your shell. See Environments for the production URL and where the dashboard shows them.
• A phone number you can receive SMS on, in E.164 format (e.g. +243998857000).
• About five minutes.

Step 1 — Generate an API key

Open the developer portal in the Bloonio dashboard, switch to the API keys tab, and click Generate API key. The cleartext api_key is shown exactly once. Copy it into a secret store immediately — it is not recoverable from the database after the banner closes.

See API keys for the full management flow, including rotation and webhook configuration.

Step 2 — Send the SMS

The exact same call works from any language. Pick the tab matching your stack.

cURL

curl $BASE_URL/api/v1/lisoloo/sms-api/send \
  -X POST \
  -H "app-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+243998857000"],
    "message": "Hello from Lisoloo!",
    "sender_id": "MYAPP"
  }'

Python

import requests

API_URL = "$BASE_URL/api/v1/lisoloo/sms-api"
API_KEY = "YOUR_API_KEY"

response = requests.post(
    f"{API_URL}/send",
    headers={
        "app-key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "to": ["+243998857000"],
        "message": "Hello from Lisoloo!",
        "sender_id": "MYAPP",
    },
    timeout=10,
)
response.raise_for_status()

result = response.json()
print(f"Message ID: {result['data']['message_id']}")
print(f"Status:     {result['data']['status']}")

JavaScript

const API_URL = "$BASE_URL/api/v1/lisoloo/sms-api";
const API_KEY = "YOUR_API_KEY";

const response = await fetch(`${API_URL}/send`, {
  method: "POST",
  headers: {
    "app-key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: ["+243998857000"],
    message: "Hello from Lisoloo!",
    sender_id: "MYAPP",
  }),
});

if (!response.ok) {
  throw new Error(`SMS failed: ${response.status}`);
}

const { data } = await response.json();
console.log("Message ID:", data.message_id);
console.log("Status:    ", data.status);

PHP

<?php

$apiUrl = '$BASE_URL/api/v1/lisoloo/sms-api';
$apiKey = 'YOUR_API_KEY';

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => "$apiUrl/send",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "app-key: $apiKey",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'to'        => ['+243998857000'],
        'message'   => 'Hello from Lisoloo!',
        'sender_id' => 'MYAPP',
    ]),
]);

$response = curl_exec($ch);
$result   = json_decode($response, true);
curl_close($ch);

echo "Message ID: " . $result['data']['message_id'] . PHP_EOL;
echo "Status:     " . $result['data']['status']     . PHP_EOL;

You get back, on success:

{
  "status_code": 201,
  "data": {
    "message_id": "507f1f77bcf86cd799439011",
    "total_recipients": 1,
    "total_messages": 1,
    "total_cost": 0.02,
    "currency": "USD",
    "status": "pending",
    "sending_type": "immediate"
  }
}

Within a few seconds the message will move from pending to processing to sent to delivered. You can poll GET /status/{message_id} to see the transitions, or wait for the webhook to fire (if configured).

Step 3 — Check the status

cURL

curl $BASE_URL/api/v1/lisoloo/sms-api/status/507f1f77bcf86cd799439011 \
  -H "app-key: YOUR_API_KEY"

Python

message_id = result["data"]["message_id"]
status_resp = requests.get(
    f"{API_URL}/status/{message_id}",
    headers={"app-key": API_KEY},
    timeout=10,
)
print(status_resp.json())

JavaScript

const statusResp = await fetch(`${API_URL}/status/${data.message_id}`, {
  headers: { "app-key": API_KEY },
});
console.log(await statusResp.json());

PHP

$messageId = $result['data']['message_id'];

$ch = curl_init("$apiUrl/status/$messageId");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["app-key: $apiKey"],
]);
echo curl_exec($ch);
curl_close($ch);

What just happened

1. You authenticated to the gateway with the app-key header.
2. The gateway validated the key, computed the cost (1 SMS × 1 recipient × unit price), and queued the message.
3. The carrier connector picked it up, sent it through the network, and reported a delivery receipt back to the gateway.
4. The gateway emitted the receipt to your callback_url if you set one, or to the webhook configured on your API key.

Next steps

• Receive delivery receipts asynchronously. Configure a webhook on your API key. See Webhooks overview.
• Send to many recipients. The to array accepts up to 1 000 numbers in one call. See Send an instant SMS.
• Schedule the send. Set sending_type: "scheduled" and pass scheduled_dates. See Schedule an SMS.
• Handle errors. Read Errors and the error catalogue.