### HTTP API Request Examples

Source: https://docs.beem.africa/index

Examples of HTTP requests and responses for interacting with the Beem Africa SMS API. Includes success and error scenarios for different operations.

```http
HTTP/1.1 200 OK 
{
    "data": [
        {
            "id": "f6823619-5829-4ab3-85b2-39a3fb474d28",
            "sms_title": "Greetings",
            "message": "Hello",
            "created": "2020-03-10T19:03:13.000Z"
        }
    ],
    "pagination": {
        "totalItems": 1,
        "currentPage": 1,
        "pageSize": 25,
        "totalPages": 1,
        "startPage": 1,
        "endPage": 1,
        "startIndex": 0,
        "endIndex": 1,
        "pages": [
            1
        ]
    }
}
```

```http
HTTP/1.1 401 Unauthorized 
 {
  "code": 120,
  "message": "Invalid Authorization Parameters"
}
```

```http
HTTP/1.1 200 OK 
{
    "data": {
        "id": "03d4c39b-42a0-4ac6-ac9f-312dd2cfe902",
        "sms_title": "Greetings",
        "message": "Have a nice day!"
    }
}
```

```http
HTTP/1.1 401 Unauthorized 
 {
  "code": 120,
  "message": "Invalid Authorization Parameters"
}
```

```http
HTTP/1.1 200 OK 
{
  "data": {
      "successful": true, 
      "args": {
          "sms_title": "Greetings",
          "message": "Good Afternoon!", 
         }
    }
}
```

```http
HTTP/1.1 404 Not Found 
{
    "data": {
        "code": 123,
        "message": "Template Does Not Exist"
    }
}
```

```http
HTTP/1.1 200 OK 
{
    "data": {
        "code": 128,
        "message": "SMS Template Deleted Successfully"
    }
}
```

```http
HTTP/1.1 404 Not Found 
{
    "data": {
        "code": 123,
        "message": " SMS Template Does Not Exist"
    }
}
```

```http
HTTP/1.1 400 Bad Request 
{
    "data": {
        "code": 127,
        "message": "SMS Template Delete Failed"
    }
}
```

--------------------------------

### Beem Africa SMS API Send Endpoint Samples

Source: https://docs.beem.africa/index

This links to the root directory for send-related samples in the Beem Africa API GitHub repository. It may contain examples in various languages or general usage information.

```link
https://github.com/beemafrica/beem-sms-api-sample/tree/master/send
```

--------------------------------

### Check Beem Africa Vendor Balance using Node.js

Source: https://docs.beem.africa/index

This script uses the axios library to make a GET request to the Beem Africa vendors balance endpoint. It requires API keys for authentication and returns the current credit balance. Ensure 'axios' and 'btoa' are installed.

```javascript
const axios = require("axios");
const https = require("https");
var btoa = require("btoa");

const username = "<api_key>";
const password = "<secret_key>";
const content_type = "application/json";

function check_balance() {
  axios
    .get("https://apisms.beem.africa/public/v1/vendors/balance", {
      headers: {
        "Content-Type": content_type,
        Authorization: "Basic " + btoa(username + ":" + password),
      },
      httpsAgent: new https.Agent({
        rejectUnauthorized: false,
      }),
    })
    .then((response) => console.log(response, username + ":" + password))
    .catch((error) => console.error(error));
}

check_balance();
```

--------------------------------

### .NET SMS API Sample - Beem Africa

Source: https://docs.beem.africa/index

This links to a GitHub repository containing .NET code samples for integrating with the Beem Africa SMS API. Developers using C# or other .NET languages can find examples here.

```link
https://github.com/beemafrica/beem-sms-api-sample/tree/master/send/dotNet
```

--------------------------------

### Get Beem Africa SMS Delivery Reports using Node.js

Source: https://docs.beem.africa/index

This Node.js script uses the axios library to retrieve SMS delivery reports. It constructs a GET request with necessary headers and query parameters, including destination address and request ID. Ensure 'axios' and 'btoa' are installed.

```javascript
const axios = require("axios");
const https = require("https");
const btoa = require("btoa");

const url = "https://dlrapi.beem.africa/public/v1/delivery-reports";
const api_key = "<API_KEY>";
const secret_key = "<SECRET_KEY>";
const content_type = "application/json";

let payload = {
  headers: {
    "Content-Type": content_type,
    Authorization: "Basic " + btoa(api_key + ":" + secret_key),
  },
  params: {
    dest_addr: "<dest_addr>",
    request_id: "<request_id>",
  },
};

function getDeliveryReports() {
  axios
    .get(url, payload, {
      httpsAgent: new https.Agent({
        rejectUnauthorized: false,
      }),
    })
    .then((resp) => console.log(resp.data))
    .catch((err) => console.log(err.message));
}

getDeliveryReports();
```

--------------------------------

### Beem Africa SMS API Callback Example

Source: https://docs.beem.africa/index

This snippet demonstrates the endpoint for receiving outbound SMS callbacks from the Beem Africa API. It specifies the HTTP method and URL for the callback.

```http
POST http://www.example.com/out-bound-sms/callback
```

--------------------------------

### Get Beem Africa SMS Delivery Reports using PHP

Source: https://docs.beem.africa/index

This PHP script fetches SMS delivery reports from the Beem Africa API using cURL. It requires the destination address and request ID for the specific SMS. The script sends a GET request with basic authentication.

```php
<?php
$username = '<api_key>';
$password = '<secret_key>';

$URL = 'https://dlrapi.beem.africa/public/v1/delivery-reports';

$dest_addr = '<dest_addr>';
$request_id = '<request_id>';
$body = array('request_id' => $request_id,'dest_addr' => $dest_addr);

// Setup cURL
$ch = curl_init();
error_reporting(E_ALL);
ini_set('display_errors', 1);

$URL = $URL . '?' . http_build_query($body);

curl_setopt($ch, CURLOPT_URL, $URL);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt_array($ch, array(
    CURLOPT_HTTPGET => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array(
        'Authorization:Basic ' . base64_encode("$username:$password"),
        'Content-Type: application/json',
    ),
));

// Send the request
$response = curl_exec($ch);

// Check for errors
if ($response === false) {
    echo $response;

    die(curl_error($ch));
}
var_dump($response);
?>
```

--------------------------------

### GET /public/v1/vendors/balance - Check Balance

Source: https://docs.beem.africa/index

Retrieve the current account balance information.

```APIDOC
## GET /public/v1/vendors/balance

### Description
Check the current account balance.

### Method
GET

### Endpoint
`https://apisms.beem.africa/public/v1/vendors/balance`

### Parameters
#### Headers
- **api_key** (string) - Required - Basic Authentication Username.
- **secret_key** (string) - Required - Basic Authentication Password.
- **Content-Type** (string) - Optional - Specifies the request format (`application/json` or `application/xml`).

### Response
(Response structure not provided in the input text)

### Request Example (using curl)
```bash
curl -X GET \
  https://apisms.beem.africa/public/v1/vendors/balance \
  -H 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
  -H 'Content-Type: application/json'
```
```

--------------------------------

### Beem Africa API SMS Send Success Response

Source: https://docs.beem.africa/index

This is an example of a successful HTTP response from the Beem Africa SMS send API. It indicates that the message was submitted successfully, providing a request ID and counts of valid, invalid, and duplicate recipients.

```http
HTTP/1.1 200 OK 
{
    "successful": true,
    "request_id": 67,
    "code": 100,
    "message": "Message Submitted Successfully",
    "valid": 1,
    "invalid": 0,
    "duplicates": 0
  }

```

--------------------------------

### Beem Africa API SMS Send Error Response

Source: https://docs.beem.africa/index

This is an example of an error response from the Beem Africa SMS send API. It typically indicates a client-side issue, such as an invalid sender ID, and includes an error code and message.

```http
HTTP/1.1 400 Bad Request
 {
  "code": 111,
  "message": "Invalid Sender Id"
}

```

--------------------------------

### Java SMS API Sample - Beem Africa

Source: https://docs.beem.africa/index

This links to a GitHub repository containing Java code samples for interacting with the Beem Africa SMS API. It is intended for developers using Java who need to integrate SMS functionality.

```link
https://github.com/beemafrica/beem-sms-api-sample/tree/master/send/java
```

--------------------------------

### Callback Parameters API

Source: https://docs.beem.africa/index

This section outlines the parameters received in the callback from Beem Africa. It details the purpose and type of each field, including message content and billing information.

```APIDOC
## POST /callback

### Description
This endpoint receives callback information from Beem Africa regarding message delivery and related events.

### Method
POST

### Endpoint
/

### Parameters
#### Request Body
- **from** (String) - Required - Source Address (Subscribers Mobile / MSISDN number)
- **to** (String) - Required - Destination Address (Long Code, Short Code)
- **channel** (String) - Optional - Channel Name (Default: SMS)
- **timeUTC** (String) - Required - UTC Timestamp (Example: Wed, 14 Jun 2017 07:00:00 GMT)
- **transaction_id** (String) - Required - Beem Transaction Id
- **message** (Object) - Required - Message details
  - **text** (String) - Required - The text message to send
  - **media** (Object) - Optional - Media details (not fully supported)
    - **mediaUrl** (String) - Optional - URL for media content
  - **custom** (Object) - Optional - Custom fields
- **billing** (Object) - Optional - Billing information
  - **currency** (String) - Optional - Default Currency (Example: TZS)
  - **subscriber_price** (String) - Optional - Subscriber Price Value if user is charged for the SMS
  - **billing_price** (String) - Optional - Billing price

### Request Example
```json
{
   "from": "255701000000",
   "to": "255701000001",
   "channel": "sms",
   "timeUTC": "Wed, 14 Jun 2017 07:00:00 GMT" ,
   "transaction_id": "120a1039103910",
   "message": {
    "text": "Test message",
    "media": { "mediaUrl": "" },
    "custom": { },
  },
   "billing": {
   "currency":"TZS",
    "subscriber_price":"100.00",
    "billing_price":"100.00"
  }
}
```

### Response
#### Success Response (200)
- **transaction_id** (String) - The transaction ID received.
- **successful** (Boolean) - Indicates if the callback was processed successfully.

#### Response Example
```json
{
  "transaction_id": "120a1039103910",
  "successful": true
}
```
```

--------------------------------

### SMS Templates API

Source: https://docs.beem.africa/index

View all SMS templates associated with the vendor account.

```APIDOC
## GET /public/v1/sms-templates

### Description
This request allows a vendor to view all SMS templates through a GET request.

### Method
GET

### Endpoint
https://apisms.beem.africa/public/v1/sms-templates

### Response
This endpoint is expected to return a list of SMS templates. Specific response structure details are not provided in the source text.
```

--------------------------------

### Add SMS Templates

Source: https://docs.beem.africa/index

This endpoint allows a vendor to add a new SMS template using a POST request.

```APIDOC
## POST /public/v1/sms-templates

### Description
Allows a vendor to add a new SMS template.

### Method
POST

### Endpoint
https://apisms.beem.africa/public/v1/sms-templates

### Headers
- **api_key** (string) - Required - Basic Authentication Username
- **secret_key** (string) - Required - Basic Authentication Password
- **Content-Type** (string) - Required - application/json or application/xml

### Request Body
- **message** (string) - Required - Custom message body
- **sms_title** (string) - Required - Title of the message template

### Request Example
```json
{
  "sms_title": "Greetings",
  "message": "Have a nice day!"
}
```

### Response
#### Success Response (200)
- **data** (object)
  - **id** (string) - The ID of the newly created template.
  - **sms_title** (string) - The title of the template.
  - **message** (string) - The content of the template.

#### Response Example
```json
{
    "data": {
        "id": "03d4c39b-42a0-4ac6-ac9f-312dd2cfe902",
        "sms_title": "Greetings",
        "message": "Have a nice day!"
    }
}
```

#### Error Response (401)
- **code** (integer) - Error code.
- **message** (string) - Error message.

#### Error Response Example
```json
 {
  "code": 120,
  "message": "Invalid Authorization Parameters"
}
```
```

--------------------------------

### Add SMS Template Request

Source: https://docs.beem.africa/index

Demonstrates how to add a new SMS template using a POST request to the specified endpoint. Requires API key, secret key, and content type in headers, along with message and sms_title in the body.

```http
POST https://apisms.beem.africa/public/v1/sms-templates

Headers:
api_key: string (Basic Authentication Username)
secret_key: string (Basic Authentication Password)
Content-Type: application/json or application/xml

Body:
message: string (Custom message body)
sms_title: string (Title of the message template)
```

--------------------------------

### Send SMS using Python with Beem Africa API

Source: https://docs.beem.africa/index

This Python snippet uses the 'requests' library to send an SMS via the Beem Africa API. It requires the 'requests' package. The code defines the API endpoint, message data, and authentication credentials, then makes a POST request. It prints a success message or details of the failure.

```python
import requests
from requests.auth import HTTPBasicAuth

url = "https://apisms.beem.africa/v1/send"

data = {
    "source_addr": "INFO",
    "encoding": 0,
    "message": "SMS Test from Python API",
    "recipients": [
        {
            "recipient_id": 1,
            "dest_addr": "255655060606"
        }
    ]
}

username = "<api_key>"
password = "<secret-key>"

response = requests.post(url, json=data, auth=HTTPBasicAuth(username, password))

if response.status_code == 200:
    print("SMS sent successfully!")
else:
    print("SMS sending failed. Status code:", response.status_code)
    print("Response:", response.text)

```

--------------------------------

### User Account Balance API

Source: https://docs.beem.africa/index

This API endpoint allows you to retrieve your current credit balance on the BEEM Africa platform. It requires Basic Authentication with your API key and secret key.

```APIDOC
## GET /public/v1/vendors/balance

### Description
Retrieves the current credit balance for your account.

### Method
GET

### Endpoint
https://apisms.beem.africa/public/v1/vendors/balance

### Headers
- **Authorization** (string) - Required - Basic Authentication header with Base64 encoded "<api_key>:<secret_key>".
- **Content-Type** (string) - Required - application/json

### Request Example
```json
{
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Basic <base64_encoded_api_key:secret_key>"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the credit balance.
  - **credit_balance** (integer) - The available credit balance.

#### Error Response (401)
- **code** (integer) - Error code (e.g., 120).
- **message** (string) - Error message (e.g., "Invalid Authorization Parameters").

#### Response Example (Success)
```json
{
 "data": {
    "credit_balance": 100
}
}
```

#### Response Example (Error)
```json
{
  "code": 120,
  "message": "Invalid Authorization Parameters"
}
```
```

--------------------------------

### Handle Beem Africa Callback in Python (Flask)

Source: https://docs.beem.africa/index

This Python Flask application demonstrates how to handle Beem Africa callbacks. It defines a POST endpoint that accepts JSON data, extracts callback parameters, and returns a JSON response. It also includes an error handler for 500 server errors. Dependencies include Flask, requests, and pyodbc.

```python
from flask import Flask,request,jsonify,Response;
import json;
import requests;
import pyodbc;

app = Flask(__name__)
@app.route('/submit',methods=['POST'])
def dataEntry():
    data=request.get_json()
    source_addr=data['from']
    dest_addr=data['to']
    channel=data['channel']
    timestamp=data['timeUTC']
    id=data['transaction_id']
    message=data['message']
    billing=data['billing']

     res.json({
     id,
     Status,
     "successful": "true" 
            });

    @app.errorhandler(500)
def server_error(e):
    errorName="Error"
    return Response(
        json.dumps(errorName),
        status=500,
    )

if __name__ == '__main__':
    app.run(debug=True)
```

--------------------------------

### Send SMS using Node.js with Beem Africa API

Source: https://docs.beem.africa/index

This Node.js snippet uses the 'axios' library to send an SMS message via the Beem Africa API. It requires 'axios' and 'btoa' packages. The function takes API keys, sender ID, and recipient details as input and outputs the API response or an error.

```javascript
const axios = require("axios");
const https = require("https");
var btoa = require("btoa");

const api_key = "<api_key>";
const secret_key = "<secret_key>";
const content_type = "application/json";
const source_addr ="<source_addr>";

function send_sms() {
  axios
    .post(
      "https://apisms.beem.africa/v1/send",
      {
        source_addr: source_addr,
        schedule_time: "",
        encoding: 0,
        message: "Hello World",
        recipients: [
          {
            recipient_id: 1,
            dest_addr: "255700000001",
          },
          {
            recipient_id: 2,
            dest_addr: "255700000002",
          },
        ],
      },
      {
        headers: {
          "Content-Type": content_type,
          Authorization: "Basic " + btoa(api_key + ":" + secret_key),
        },
        httpsAgent: new https.Agent({
          rejectUnauthorized: false,
        }),
      }
    )
    .then((response) => console.log(response, api_key + ":" + secret_key))
    .catch((error) => console.error(error.response.data));
}

send_sms();

```

--------------------------------

### Handle Beem Africa Callback in Node.js

Source: https://docs.beem.africa/index

This Node.js code snippet demonstrates how to set up an Express server to receive and process callback data from Beem Africa. It parses the incoming JSON request body and sends a success response. Dependencies include express.

```javascript
const express = require("express");
const app = express();
app.use(express.urlencoded({ extended: false }));
app.use(express.json());

app.post("/", (req, res) => {
let { source_addr, dest_addr, channel, timeUtc, transaction_id, message, billing } = req.body;

 res.json({
         transaction_id,
         successful: true 
        });
});

app.listen(3000, () => console.log("app running on port 3000"));
```

--------------------------------

### Check Beem Africa Vendor Balance using PHP

Source: https://docs.beem.africa/index

This PHP script utilizes cURL to query the Beem Africa vendors balance endpoint. It sends an authorization header with base64 encoded credentials and returns the account balance. Ensure correct API keys are provided.

```php
<?php
$username='<api_key>';
$password = '<secret_key>';

$Url ='https://apisms.beem.africa/public/v1/vendors/balance';

$ch = curl_init($Url);
error_reporting(E_ALL);
ini_set('display_errors', 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt_array($ch, array(
    CURLOPT_HTTPGET => TRUE,
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_HTTPHEADER => array(
        'Authorization:Basic ' . base64_encode("$username:$password"),
        'Content-Type: application/json'
    ),
));
// Send the request
$response = curl_exec($ch);

if($response === FALSE){
        echo $response;

    die(curl_error($ch));
}
var_dump($response);
?>
```

--------------------------------

### POST /v1/send - Send SMS

Source: https://docs.beem.africa/index

This endpoint allows you to send SMS messages to one or more recipients. It supports various programming languages for integration.

```APIDOC
## POST /v1/send

### Description
Send SMS messages to one or more recipients.

### Method
POST

### Endpoint
`https://apisms.beem.africa/v1/send`

### Parameters
#### Request Body
- **source_addr** (string) - Required - The sender ID of the message.
- **schedule_time** (string) - Optional - The time to schedule the message delivery.
- **encoding** (integer) - Optional - The encoding type for the message (e.g., 0 for standard).
- **message** (string) - Required - The content of the SMS message.
- **recipients** (array) - Required - A list of recipients with their IDs and destination numbers.
  - **recipient_id** (integer) - Required - The ID of the recipient.
  - **dest_addr** (string) - Required - The destination phone number.

### Request Example (Node.js)
```javascript
const axios = require("axios");
const https = require("https");
var btoa = require("btoa");

const api_key = "<api_key>";
const secret_key = "<secret_key>";
const content_type = "application/json";
const source_addr ="<source_addr>";

function send_sms() {
  axios
    .post(
      "https://apisms.beem.africa/v1/send",
      {
        source_addr: source_addr,
        schedule_time: "",
        encoding: 0,
        message: "Hello World",
        recipients: [
          {
            recipient_id: 1,
            dest_addr: "255700000001",
          },
          {
            recipient_id: 2,
            dest_addr: "255700000002",
          },
        ],
      },
      {
        headers: {
          "Content-Type": content_type,
          Authorization: "Basic " + btoa(api_key + ":" + secret_key),
        },
        httpsAgent: new https.Agent({
          rejectUnauthorized: false,
        }),
      }
    )
    .then((response) => console.log(response, api_key + ":" + secret_key))
    .catch((error) => console.error(error.response.data));
}

send_sms();
```

### Request Example (PHP)
```php
<?php
$api_key='<api_key>';
$secret_key = '<secret_key>';

$postData = array(
    'source_addr' => 'INFO',
    'encoding'=>0,
    'schedule_time' => '',
    'message' => 'Hello World',
    'recipients' => [array('recipient_id' => '1','dest_addr'=>'255700000001'),array('recipient_id' => '2','dest_addr'=>'255700000011')]
);

$Url ='https://apisms.beem.africa/v1/send';

$ch = curl_init($Url);
error_reporting(E_ALL);
ini_set('display_errors', 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt_array($ch, array(
    CURLOPT_POST => TRUE,
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_HTTPHEADER => array(
        'Authorization:Basic ' . base64_encode("$api_key:$secret_key"),
        'Content-Type: application/json'
    ),
    CURLOPT_POSTFIELDS => json_encode($postData)
));

$response = curl_exec($ch);

if($response === FALSE){
        echo $response;

    die(curl_error($ch));
}
var_dump($response);
?>
```

### Request Example (Python)
```python
import requests
from requests.auth import HTTPBasicAuth

url = "https://apisms.beem.africa/v1/send"

data = {
    "source_addr": "INFO",
    "encoding": 0,
    "message": "SMS Test from Python API",
    "recipients": [
        {
            "recipient_id": 1,
            "dest_addr": "255655060606"
        }
    ]
}

username = "<api_key>"
password = "<secret-key>"

response = requests.post(url, json=data, auth=HTTPBasicAuth(username, password))

if response.status_code == 200:
    print("SMS sent successfully!")
else:
    print("SMS sending failed. Status code:", response.status_code)
    print("Response:", response.text)
```

### Additional Resources
- Java SDK: `https://github.com/beemafrica/beem-sms-api-sample/tree/master/send/java`
- .NET SDK: `https://github.com/beemafrica/beem-sms-api-sample/tree/master/send/dotNet`
- General Samples: `https://github.com/beemafrica/beem-sms-api-sample/tree/master/send`

### Response
#### Success Response (200)
- **successful** (boolean) - Indicates if the submission was successful.
- **request_id** (integer) - A unique identifier for the request.
- **code** (integer) - An API status code.
- **message** (string) - A human-readable message describing the status.
- **valid** (integer) - The number of valid recipients.
- **invalid** (integer) - The number of invalid recipients.
- **duplicates** (integer) - The number of duplicate recipients.

#### Response Example (Success)
```json
{
    "successful": true,
    "request_id": 67,
    "code": 100,
    "message": "Message Submitted Successfully",
    "valid": 1,
    "invalid": 0,
    "duplicates": 0
  }
```

#### Error Response (400)
- **code** (integer) - An API error code.
- **message** (string) - A human-readable message describing the error.

#### Response Example (Error)
```json
 {
  "code": 111,
  "message": "Invalid Sender Id"
}
```
```

--------------------------------

### Edit SMS Templates

Source: https://docs.beem.africa/index

This endpoint allows a vendor to edit an existing SMS template using a PUT request.

```APIDOC
## PUT /public/v1/sms-templates/{template_id}

### Description
Allows a vendor to edit an existing SMS template.

### Method
PUT

### Endpoint
https://apisms.beem.africa/public/v1/sms-templates/{template_id}

### Headers
- **api_key** (string) - Required - Basic Authentication Username
- **secret_key** (string) - Required - Basic Authentication Password
- **Content-Type** (string) - Required - application/json or application/xml

### Path Parameters
- **template_id** (string) - Required - The ID of the template to edit.

### Request Body
- **sms_title** (string) - Optional - The new title for the message template.
- **message** (string) - Optional - The new custom message body.

### Request Example
```json
{
  "sms_title": "Greetings",
  "message": "Good Afternoon!"
}
```

### Response
#### Success Response (200)
- **data** (object)
  - **successful** (boolean) - Indicates if the update was successful.
  - **args** (object) - Contains the updated template details.
    - **sms_title** (string) - The updated title.
    - **message** (string) - The updated message.

#### Response Example
```json
{
  "data": {
      "successful": true,
      "args": {
          "sms_title": "Greetings",
          "message": "Good Afternoon!"
         }
    }
}
```

#### Error Response (404)
- **data** (object)
  - **code** (integer) - Error code.
  - **message** (string) - Error message.

#### Error Response Example
```json
{
    "data": {
        "code": 123,
        "message": "Template Does Not Exist"
    }
}
```
```

--------------------------------

### Handle Beem Africa Callback in PHP

Source: https://docs.beem.africa/index

This PHP code snippet shows how to retrieve callback data from a Beem Africa URL, decode the JSON response, extract relevant fields, and return a JSON response indicating success. It utilizes file_get_contents and json_decode.

```php
<?php

$data = file_get_contents('https://www.callback.example');

$data = json_decode($data, true);
    $source_addr=$data['from'];
    $dest_addr=$data['to'];
    $channel=$data['channel'];
    $timestamp=$data['timeUTC'];
    $id=$data['transaction_id'];
    $message=$data['message'];
    $billing=$data['billing'];

$res= array ('transaction_id' => $id, 'successful'=> true);
   
$json = json_encode($res);
echo $json;
?>
```

--------------------------------

### Delivery Reports API

Source: https://docs.beem.africa/index

Retrieve delivery status for SMS messages using the destination address and request ID.

```APIDOC
## GET /public/v1/delivery-reports

### Description
This endpoint retrieves the delivery status of an SMS message.

### Method
GET

### Endpoint
https://dlrapi.beem.africa/public/v1/delivery-reports

### Query Parameters
- **dest_addr** (String) - Required - The mobile number to which the SMS was sent.
- **request_id** (String) - Required - The Beem API transaction ID for the SMS.

### Request Example
```
GET https://dlrapi.beem.africa/public/v1/delivery-reports?dest_addr=255700000002&request_id=31951
```

### Response
#### Success Response (200)
- **dest_addr** (String) - The destination mobile number.
- **status** (String) - The delivery status (UNDELIVERED, PENDING, DELIVERED).
- **request_id** (String) - The Beem API transaction ID.

#### Response Example
```json
[
    {
        "dest_addr": "255700000002",
        "status": "PENDING",
        "request_id": "31951"
    }
]
```

#### Error Response Examples
```json
HTTP/1.1 404 Not Found
{
    "error": "Invalid request_id or dest_addr"
}
```

```json
HTTP/1.1 401 Unauthorized
{
   "code": 120,
   "message": "Invalid Authentication Parameters"
}
```

```json
HTTP/1.1 400 Bad Request
{
   "error": "No authorization headers"
}
```
```

--------------------------------

### Edit SMS Template Request

Source: https://docs.beem.africa/index

Shows how to edit an existing SMS template via a PUT request. The request includes the template ID in the path and updated sms_title and message in the body. Requires authentication headers.

```http
PUT https://apisms.beem.africa/public/v1/sms-templates/{template_id}

Headers:
api_key: string (Basic Authentication Username)
secret_key: string (Basic Authentication Password)
Content-Type: application/json or application/xml

Path:
template_id: string (Template Id)

Body:
sms_title: string (Title of the message template)
message: string (Custom message body)
```

--------------------------------

### Sender Names API

Source: https://docs.beem.africa/index

Manage sender names for SMS messages, including viewing and requesting new sender IDs.

```APIDOC
## GET /public/v1/sender-names

### Description
This request allows a vendor to retrieve the list of all registered sender IDs.

### Method
GET

### Endpoint
https://apisms.beem.africa/public/v1/sender-names

### Headers
- **api_key** (string) - Required - Basic Authentication Username
- **secret_key** (string) - Required - Basic Authentication Password
- **Content-Type** (string) - Required - application/json or application/xml

### Query Parameters
- **q** (string) - Optional - Filter by senderid or sample_content
- **status** (string) - Optional - Filter by Status (active, inactive, pending)

### Response
#### Success Response (200)
- **data** (array) - List of sender names with their details.
  - **id** (string) - Sender ID unique identifier.
  - **senderid** (string) - The registered sender name.
  - **sample_content** (string) - Sample content describing the sender name's purpose.
  - **status** (string) - Status of the sender name (pending, active, inactive).
  - **created** (string) - Timestamp of creation.
- **pagination** (object) - Pagination details for the results.

#### Response Example
```json
{
   "data": [
        {
            "id": "c893d701-e1d8-4b00-8634-8c464e56ba11",
            "senderid": "testing",
            "sample_content": "123",
            "status": "pending",
            "created": "2021-07-08T14:07:56.000Z"
        }
    ],
    "pagination": {
        "totalItems": 1,
        "currentPage": 1,
        "pageSize": 25,
        "totalPages": 1,
        "startPage": 1,
        "endPage": 1,
        "startIndex": 0,
        "endIndex": 1,
        "pages": [
            1
        ]
    }
}
```

#### Error Response Example
```json
HTTP/1.1 401 Unauthorized
{
  "code": 120,
  "message": "Invalid Authorization Parameters"
}
```

## POST /public/v1/sender-names

### Description
This request allows a vendor to request a new sender name.

### Method
POST

### Endpoint
https://apisms.beem.africa/public/v1/sender-names

### Headers
- **api_key** (string) - Required - Basic Authentication Username
- **secret_key** (string) - Required - Basic Authentication Password
- **Content-Type** (string) - Required - application/json or application/xml

### Request Body
- **senderid** (string) - Required - Client Sender Name (Should not exceed 11 characters).
- **sample_content** (string) - Required - Sample content describing what the Sender Name is for (minimum of 15 characters).

### Request Example
```json
{
    "senderid": "Sample",
    "sample_content": "This is a sample content"
}
```

### Response
#### Success Response (200)
- **data** (object) - Details of the requested sender name.
  - **senderid** (string) - The requested sender name.
  - **sample_content** (string) - The sample content provided.
  - **id** (string) - Unique identifier for the sender name request.
  - **status** (string) - Status of the sender name request (e.g., pending).

#### Response Example
```json
{
    "data": {
        "senderid": "Sample",
        "sample_content": "This is a sample content",
        "id": "24e1ffaf-e399-4b15-983a-53539e4970bd",
        "status": "pending"
    }
}
```

#### Error Response Examples
```json
HTTP/1.1 401 Unauthorized
{
    "code": 120,
    "message": "Invalid Authentication Parameters"
}
```

```json
HTTP/1.1 409 Conflict
{
    "data": {
        "code": 124,
        "message": "Sender Name sample content should not exceed 170 characters"
    }
}
```

```json
HTTP/1.1 409 Conflict
{
    "data": {
        "code": 122,
        "message": "Senderid exist, please try another one"
    }
}
```

```json
HTTP/1.1 409 Conflict
{
    "data": {
        "code": 121,
        "message": "Sender Name Should Not Exceed 11 Characters and can have only numbers, letters and the following special characters . - and space"
    }
}
```
```

--------------------------------

### Send SMS Request in XML

Source: https://docs.beem.africa/index

This snippet shows how to format a request to send SMS messages using the Beem Africa API in XML. It includes sender ID, message content, and recipient details with unique IDs, mirroring the structure of the JSON request. Proper XML formatting is crucial for successful API calls.

```xml
<sms>
  <source_addr>INFO</source_addr>
  <schedule_time />
  <message>Hello world</message>
  <recipients>
      <recipient>
          <recipient_id>1</recipient_id>
          <dest_addr>255700000001</dest_addr>
      </recipient>
      <recipient>
          <recipient_id>2</recipient_id>
          <dest_addr>255600000002</dest_addr>
      </recipient>
  </recipients>
</sms>
```

--------------------------------

### Delivery Reports API

Source: https://docs.beem.africa/index

This API endpoint allows you to retrieve the delivery status of SMS messages. You need to provide the destination number and the request ID associated with the sent SMS.

```APIDOC
## GET /public/v1/delivery-reports

### Description
Retrieves the delivery status for a specific SMS message.

### Method
GET

### Endpoint
https://dlrapi.beem.africa/public/v1/delivery-reports

### Headers
- **Authorization** (string) - Required - Basic Authentication header with Base64 encoded "<api_key>:<secret_key>".
- **Content-Type** (string) - Required - application/json or application/xml, depending on the desired response format.

### Query Parameters
- **dest_addr** (string) - Required - The mobile number to which the SMS was sent.
- **request_id** (string) - Required - The unique request ID generated when the SMS was submitted.

### Request Example
```json
{
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Basic <base64_encoded_api_key:secret_key>"
  },
  "params": {
    "dest_addr": "<dest_addr>",
    "request_id": "<request_id>"
  }
}
```

### Response
Delivery status should be checked 5 minutes or later after an SMS has been submitted.

#### Success Response (200)
- The structure of the success response will depend on the content type requested. A typical JSON response might include delivery status details.

#### Response Example (Success)
```json
{
 "data": {
    "delivery_status": "DELIVERED",
    "dest_addr": "<dest_addr>",
    "request_id": "<request_id>"
}
}
```
```

--------------------------------

### Send SMS Request

Source: https://docs.beem.africa/index

This endpoint is used for sending SMS messages. It requires the API key and secret key for authentication.

```http
POST https://apisms.beem.africa/v1/send
```

--------------------------------

### POST /v1/send

Source: https://docs.beem.africa/index

Send SMS messages to one or more recipients. Supports scheduling and custom encoding.

```APIDOC
## POST /v1/send

### Description
Send SMS messages to one or more recipients. Supports scheduling and custom encoding.

### Method
POST

### Endpoint
https://apisms.beem.africa/v1/send

### Parameters
#### Headers
- **api_key** (string) - Required - Basic Authentication Username
- **secret_key** (string) - Required - Basic Authentication Password
- **Content-Type** (string) - Required - application/json or application/xml

#### Request Body
- **source_addr** (string) - Required - Message source address or sender ID. Limited to 11 characters if text. Or valid mobile number in valid international number format with country code. No leading + sign. Has to be active on the sms portal.
- **schedule_time** (string) - Optional - Scheduled time of the message. GMT+0 timezone. Format (yyyy-mm-dd hh:mm)
- **message** (string) - Required - Content/message.
- **encoding** (number) - Optional - Message encoding type. Default value is 0.
- **recipients** (array) - Required - Array of destination objects.
  - **recipient_id** (string) - Required - Unique id per destination. This will be returned along with delivery reports. Can be any string value up to X Characters.
  - **dest_addr** (string) - Required - Destination mobile number in valid international number format with country code. No leading + sign. Example 255784825785

### Request Example
#### JSON
```json
{
    "source_addr": "YOUR ACTIVE SENDER ID",
    "schedule_time": "",
    "encoding": "0",
    "message": "Hello world",
    "recipients": [
        {
            "recipient_id": 1,
            "dest_addr": "255700000001"
        },
        {
            "recipient_id": 2,
            "dest_addr": "255700000002"
        }
    ]
}
```

#### XML
```xml
<sms>
  <source_addr>INFO</source_addr>
  <schedule_time />
  <message>Hello world</message>
  <recipients>
      <recipient>
          <recipient_id>1</recipient_id>
          <dest_addr>255700000001</dest_addr>
      </recipient>
      <recipient>
          <recipient_id>2</recipient_id>
          <dest_addr>255600000002</dest_addr>
      </recipient>
  </recipients>
</sms>
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the request.
- **message_id** (string) - A unique identifier for the sent message.
- **message_count** (integer) - The number of messages successfully processed.

#### Response Example
```json
{
  "status": "success",
  "message_id": "MSG123456789",
  "message_count": 2
}
```
```

--------------------------------

### View Beem Sender Names Success Response

Source: https://docs.beem.africa/index

This JSON response details a successful retrieval of registered sender names from the Beem API. It includes sender ID, sample content, status, and creation timestamp for each sender name, along with pagination information.

```json
HTTP/1.1 200 OK 
{
   "data": [
        {
            "id": "c893d701-e1d8-4b00-8634-8c464e56ba11",
            "senderid": "testing",
            "sample_content": "123",
            "status": "pending",
            "created": "2021-07-08T14:07:56.000Z"
        },
    ],
    "pagination": {
        "totalItems": 1,
        "currentPage": 1,
        "pageSize": 25,
        "totalPages": 1,
        "startPage": 1,
        "endPage": 1,
        "startIndex": 0,
        "endIndex": 1,
        "pages": [
            1
        ]
    }
}
```

--------------------------------

### Send SMS using PHP with Beem Africa API

Source: https://docs.beem.africa/index

This PHP snippet utilizes cURL to send an SMS message via the Beem Africa API. It requires basic PHP and cURL enabled. The code constructs the POST data, sets appropriate headers including Basic Authentication, and handles the response. It outputs the raw response or a cURL error.

```php
<?php
$api_key='<api_key>';
$secret_key = '<secret_key>';

$postData = array(
    'source_addr' => 'INFO',
    'encoding'=>0,
    'schedule_time' => '',
    'message' => 'Hello World',
    'recipients' => [array('recipient_id' => '1','dest_addr'=>'255700000001'),array('recipient_id' => '2','dest_addr'=>'255700000011')]
);

$Url ='https://apisms.beem.africa/v1/send';

$ch = curl_init($Url);
error_reporting(E_ALL);
ini_set('display_errors', 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt_array($ch, array(
    CURLOPT_POST => TRUE,
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_HTTPHEADER => array(
        'Authorization:Basic ' . base64_encode("$api_key:$secret_key"),
        'Content-Type: application/json'
    ),
    CURLOPT_POSTFIELDS => json_encode($postData)
));

$response = curl_exec($ch);

if($response === FALSE){
        echo $response;

    die(curl_error($ch));
}
var_dump($response);

```