BulkSMS DigitalServicesCenter API Documentation - v2

API Overview

Welcome to BulkSMS DigitalServicesCenter! Our SMS service enables businesses to reliably and easily send messages to clients. The platform supports delivery reports and status callbacks (DLRs), making it ideal for both live and testing environments.

• Base URL: https://bulksms.digitalservicescenter.rw/api/v2/sms/send
• Authentication: API Key, Username, and Password (POST only)
• DLR Support: Yes, supports callback via dlrurl
• Testing Limits: 15 SMS/day (testing mode)
• SMS Cost: 75 RWF per message

API Endpoints

1. Send SMS

Sends an SMS to one or more recipients.

POST Endpoint:

Parameters:

• api_key (string, required)
• username (string, required)
• password (string, required)
• recipients (string, required): Comma-separated list (e.g., 250782589800,250782589801)
• message (string, required)
• sender (string, optional): Sender ID (default from our adminstration)
• dlrurl (string, optional): Your DLR callback URL

Example Request:

{
  "api_key": "your_api_key",
  "username": "your_username",
  "password": "your_password",
  "recipients": "250782589800,250782589801",
  "message": "Test from BulkSMS!",
  "dlrurl": "https://yourdomain.com/dlr-handler"
}

Success Response:

{
  "status": "success",
  "totalmessages": 2,
  "totalcost": 150,
  "unit": "RWF",
  "response": [
    {
      "status": "sent",  
      "messageid": "118579716",
      "recipient": "250782589800",
      "message": "Test from BulkSMS!",
      "cost": 75
    },
    {
      "status": "failed",
      "messageid": "118579717",
      "recipient": "250782589801",
      "message": "Test from BulkSMS!",
      "cost": 75
    }
  ]
}

How to Work with Our API

Below are examples in various programming languages to help you integrate your system with BulkSMS DigitalServicesCenter.

1. PHP

<?php
$url = 'https://bulksms.digitalservicescenter.rw/api/v2/sms/send';
$data = [
    'api_key' => 'your_api_key',
    'username' => 'your_username',
    'password' => 'your_password',
    'recipients' => '250782589800,250782589801',
    'message' => 'Hello, this is a test message from BulkSMS DigitalServicesCenter!',
    'dlrurl' => 'https://yourdomain.com/dlr-handler'
];

$options = [
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/x-www-form-urlencoded\r\n",
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
?>
  

2. Node.js (using axios)

const axios = require('axios');

const data = {
  api_key: 'your_api_key',
  username: 'your_username',
  password: 'your_password',
  recipients: '250782589800,250782589801',
  message: 'Hello, this is a test message from BulkSMS DigitalServicesCenter!',
  dlrurl: 'https://yourdomain.com/dlr-handler'
};

axios.post('https://bulksms.digitalservicescenter.rw/api/v2/sms/send', data)
  .then(response => console.log(response.data))
  .catch(error => console.error(error));
  

3. Python (using requests)

import requests

url = 'https://bulksms.digitalservicescenter.rw/api/v2/sms/send'
payload = {
    'api_key': 'your_api_key',
    'username': 'your_username',
    'password': 'your_password',
    'recipients': '250782589800,250782589801',
    'message': 'Hello, this is a test message from BulkSMS DigitalServicesCenter!',
    'dlrurl': 'https://yourdomain.com/dlr-handler'
}

response = requests.post(url, data=payload)
print(response.json())
  

4. cURL (command-line)

curl -X POST https://bulksms.digitalservicescenter.rw/api/v2/sms/send \
  -d "api_key=your_api_key" \
  -d "username=your_username" \
  -d "password=your_password" \
  -d "recipients=250782589800,250782589801" \
  -d "message=Hello, this is a test message from BulkSMS DigitalServicesCenter!" \
  -d "dlrurl=https://yourdomain.com/dlr-handler"
  

Make sure to replace all placeholder values (like your_api_key) with your actual API credentials.

Delivery Reports (DLR)

Our system forwards delivery statuses to your custom callback URL via GET requests. To enable this, provide the dlrurl parameter when sending your message.

DLR Callback URL Format:

The callback URL you provide should expect requests structured as follows:

https://your-domain-base-url/api?dnis=$dnis$&username=SmsChannelUsername&password=SmsChannelPassword&command=deliver&dlvrMsgId=$messageID$&dlvrMsgStat=$status$

Note: Replace username and password with your authorization credentials configured in your system.

Final Status Codes Sent via Callback:

• D — Delivered (final status)
• U — Undelivered (final status)

Our system sends only these final statuses to your callback URL. Intermediate statuses such as P (processing) or Q (queued) are handled internally but not forwarded to avoid confusion.

Example DLR Callback Request:

https://your-domain-base-url/api?dnis=250782589800&username=SmsChannelUsername&password=SmsChannelPassword&command=deliver&dlvrMsgId=118579716&dlvrMsgStat=D

DLR Callback Behavior:

• All delivery reports are stored internally with timestamps.
• Only final statuses (D and U) trigger callbacks to your specified dlrurl.
• Callbacks are sent as GET requests including the parameters: dnis (recipient number), username, password, command, dlvrMsgId (message ID), and dlvrMsgStat (delivery status).
• Your callback handler should authenticate the request using the provided username and password and process the delivery status accordingly.

Error Responses

{
  "status": "error",
  "message": "Invalid API key or credentials"
}

{
  "status": "error",
  "message": "You have reached the daily SMS limit for testing mode."
}

{
  "status": "error",
  "message": "Invalid phone numbers: 0781234567"
}

{
  "status": "error",
  "message": "Failed to send SMS via external gateway",
  "http_code": 500
}

Frequently Asked Questions

1. How do I get my API key?

Contact us at contact@digitalservicescenter.rw to request your API credentials.

2. How do delivery reports work?

When you send an SMS and provide a dlrurl, our system will send a GET request to that URL only when the message status reaches a final state — Delivered (D) or Undelivered (U).

The callback request will include the following parameters in the query string:

• dnis: The recipient phone number
• username: Your SMS channel username for authentication
• password: Your SMS channel password for authentication
• command: The fixed value deliver indicating a delivery report
• dlvrMsgId: The unique ID of the message
• dlvrMsgStat: The final delivery status (D or U)

This setup allows you to track message delivery in real time and verify status securely using the authentication parameters.

3. Can I send to multiple numbers?

Yes! Separate multiple phone numbers with commas in the recipients field.

4. What happens if I'm in testing mode?

You can send up to 15 SMS messages per day in testing mode. Once the limit is reached, you need to wait until the next day or request live access.