API Documentation

Reach the World

Enrich your application with easy-to-integrate, secure communication APIs offering channels your customers widely use and love.

<?php
// Send a message with Connect Media API
$username = 'your_username';
$password = 'your_password';
$sender = 'ConectMedia';
$to = '254712345678';
$message = "Hello from Connect Media!";

$url = "http://www.connectmedia.co.ke/user-board/?api";
$post = [
  'action' => 'send',
  'to' => $to,
  'username' => $username,
  'password' => $password, 
  'sender' => $sender,
  'message' => urlencode($message)
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$response = curl_exec($ch);
curl_close($ch);

echo json_decode($response, true)['message'];
?>
// Send a message with Connect Media API
const sendSMS = async () => {
  const apiUrl = 'http://www.connectmedia.co.ke/user-board/?api';
  
  const formData = new FormData();
  formData.append('username', 'your_username');
  formData.append('password', 'your_password');
  formData.append('action', 'send');
  formData.append('to', '254712345678');
  formData.append('sender', 'ConectMedia');
  formData.append('message', encodeURIComponent('Hello from Connect Media!'));
  
  try {
    const response = await fetch(apiUrl, {
      method: 'POST',
      body: formData
    });
    
    const result = await response.json();
    console.log('Response:', result.message);
  } catch (error) {
    console.error('Error:', error);
  }
};
import requests

def send_sms():
    api_url = 'http://www.connectmedia.co.ke/user-board/?api'
    
    payload = {
        'username': 'your_username',
        'password': 'your_password',
        'action': 'send',
        'to': '254712345678',
        'sender': 'ConectMedia',
        'message': 'Hello from Connect Media!'
    }
    
    try:
        response = requests.post(api_url, data=payload)
        result = response.json()
        
        print(f"Response: {result['message']}")
    except Exception as e:
        print(f"Error: {e}")

# Call the function
send_sms()

More than 1,000 organizations are using Connect Media

Easy Integration

Simple HTTP POST requests with clear parameters make integration quick and painless.

Global Reach

Send SMS messages to mobile numbers worldwide with excellent delivery rates.

Two-Way Messaging

Receive incoming messages from your customers for interactive communication.

Introduction

The Connect Media Bulk SMS API provides a simple and reliable way to send SMS messages programmatically. This API allows you to send messages, check your account balance, and retrieve message history.

All requests are submitted using the HTTP POST method to the API endpoint. The API returns responses in JSON format, making it easy to parse and process in any programming language.

Getting Started: Create an account with Connect Media to receive your API credentials. If you don't have an account yet, please contact our sales team.

Authentication

Authentication is performed by including your Connect Media username and password as parameters in every API request. These credentials verify your identity and ensure that only authorized users can access the API.

Security Note: Keep your credentials secure. Don't expose them in client-side code or public repositories. We recommend storing credentials in environment variables or a secure configuration system.
// Example of authentication parameters
$username = 'your_username';
$password = 'your_password';

Endpoints

Base URL

POST http://www.connectmedia.co.ke/user-board/?api

For receiving SMS messages (inbox functionality), use this endpoint:

POST http://www.connectmedia.co.ke/user-board/?api_v2

Available Actions

Action Description Endpoint
send Send an SMS message api
balance Check account balance api
history Retrieve sent message history api
inbox Retrieve received messages (2-WAY SMS) api_v2

Parameters

The following parameters are used when making requests to the API:

Parameter Description Required
username Your Connect Media account username Yes
password Your Connect Media account password Yes
action The action to perform:
send - Send an SMS message
balance - Check account balance
history - Retrieve sent message history
inbox - Retrieve received messages (2-WAY SMS)
Yes
to Recipient mobile number including country code (e.g., 254712345678) Yes (for send action)
sender Sender ID for the message (Use ConectMedia as default) No
message The text message content Yes (for send action)
Important: The Sender ID (ConectMedia) is limited to a maximum of 11 characters. Note the spelling with a single 'n' in "ConectMedia".

Response Codes

The API returns responses in JSON format with two indexes: code and message.

Code Description
100 Invalid login details
101 No enough balance to send message
103 No action defined
200 Shows the balance of the user
201 Message sent successfully
202 Message history retrieved successfully
301 Error in fetching data (inbox)
302 Inbox messages retrieved successfully

Examples

Sending an SMS Message

Example of a successful response when sending a message:

{"code":"201"," Message Sent Successfully!"}

Note: 201 is the response code indicating the message was sent successfully.

Checking Account Balance

Example of a successful response when checking your balance:

{"code":"200","1"}

Note: 200 is the response code and 1 is the balance of the account.

Retrieving Message History

Example of a successful response when retrieving message history:

{"0":{"message_id":"1","message_text":"test message 1","message_date":"2016-06-11 06:00:27","message_status":"Delivered","message_error":"OK"},"1":{"message_id":"2","message_text":"test message 2","message_date":"2016-06-11 15:03:49","message_status":"Delivered","message_error":"OK"},"code":"202"}

Note: 202 is the response code and indexes 0 to n show an array of messages with their details.

2-Way SMS (Inbox)

Example of a successful response when retrieving inbox messages:

{"0":{"message_text":"incoming test message","message_datetime":"2016-06-11 06:00:27","message_from":"254712345678"},"1":{"message_text":"another test message","message_datetime":"2016-06-11 15:03:49","message_from":"254787654321"},"code":"302"}

Note: 302 is the response code and indexes 0 to n show an array of received messages with their details.

Code Samples

Sending an SMS Message

<?php
$username = 'your_username'; // Your Connect Media username
$password = 'your_password'; // Your Connect Media password
$sender = 'ConectMedia'; // Sender ID (max 11 characters)
$action = 'send'; // Action: sending message
$to = '254712345678'; // Destination number with country code
$message = "Hello from Connect Media API"; // Message text

$url = "http://www.connectmedia.co.ke/user-board/?api"; 

$post = [
    'action' => "$action",
    'to' => "$to",
    'username' => "$username",
    'password' => "$password", 
    'sender' => "$sender",
    'message' => urlencode("$message")
]; 

$ch = curl_init("$url");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$response = curl_exec($ch);
curl_close($ch);

$jsonarray = json_decode($response, true);
echo "Return code is: " . $jsonarray['code']; // Response code
echo "Return message is: " . $jsonarray['message']; // Response message
?>

Checking Account Balance

<?php
$username = 'your_username'; // Your Connect Media username
$password = 'your_password'; // Your Connect Media password
$action = 'balance'; // Action: check balance

$url = "http://www.connectmedia.co.ke/user-board/?api"; 

$post = [
    'action' => "$action",
    'username' => "$username",
    'password' => "$password"
]; 

$ch = curl_init("$url");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$response = curl_exec($ch);
curl_close($ch);

$jsonarray = json_decode($response, true);
echo "Return code is: " . $jsonarray['code']; // Response code
echo "Your balance is: " . $jsonarray['message']; // Balance amount
?>

Retrieving Message History

<?php
$username = 'your_username'; // Your Connect Media username
$password = 'your_password'; // Your Connect Media password
$action = 'history'; // Action: retrieve message history

$url = "http://www.connectmedia.co.ke/user-board/?api"; 

$post = [
    'action' => "$action",
    'username' => "$username",
    'password' => "$password"
]; 

$ch = curl_init("$url");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$response = curl_exec($ch);
curl_close($ch);

$jsonarray = json_decode($response, true);

if($jsonarray['code'] == '202') {
    // Success, process message history
    foreach($jsonarray as $key => $value) {
        if($key !== 'code') {
            echo "Message ID: " . $value['message_id'] . "
"; echo "Text: " . $value['message_text'] . "
"; echo "Date: " . $value['message_date'] . "
"; echo "Status: " . $value['message_status'] . "
"; echo "Error: " . $value['message_error'] . "

"; } } } else { // Error handling echo "Error: " . $jsonarray['message']; } ?>

2-Way SMS (Inbox)

<?php
$username = 'your_username'; // Your Connect Media username
$password = 'your_password'; // Your Connect Media password
$action = 'inbox'; // Action: retrieve inbox messages

$url = "http://www.connectmedia.co.ke/user-board/?api_v2"; // Note the api_v2 endpoint

$post = [
    'action' => "$action",
    'username' => "$username",
    'password' => "$password"
]; 

$ch = curl_init("$url");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$response = curl_exec($ch);
curl_close($ch);

$jsonarray = json_decode($response, true);
$count = count($jsonarray);

if($jsonarray['code'] == '302') {
    // Process inbox messages
    foreach($jsonarray as $key => $value) {
        if($key !== 'code') {
            echo "Message: " . $value['message_text'] . "
"; echo "Date: " . $value['message_datetime'] . "
"; echo "From: " . $value['message_from'] . "

"; } } } else if($jsonarray['code'] == '301') { echo "Error in fetching data"; } ?>

Sending an SMS Message

// JavaScript (using fetch API)
const sendSMS = async () => {
    const apiUrl = 'http://www.connectmedia.co.ke/user-board/?api';
    
    const formData = new FormData();
    formData.append('username', 'your_username');
    formData.append('password', 'your_password');
    formData.append('action', 'send');
    formData.append('to', '254712345678');
    formData.append('sender', 'ConectMedia');
    formData.append('message', encodeURIComponent('Hello from Connect Media API'));
    
    try {
        const response = await fetch(apiUrl, {
            method: 'POST',
            body: formData
        });
        
        const result = await response.json();
        console.log('Response code:', result.code);
        console.log('Response message:', result.message);
    } catch (error) {
        console.error('Error:', error);
    }
};

Checking Account Balance

// JavaScript (using fetch API)
const checkBalance = async () => {
    const apiUrl = 'http://www.connectmedia.co.ke/user-board/?api';
    
    const formData = new FormData();
    formData.append('username', 'your_username');
    formData.append('password', 'your_password');
    formData.append('action', 'balance');
    
    try {
        const response = await fetch(apiUrl, {
            method: 'POST',
            body: formData
        });
        
        const result = await response.json();
        console.log('Response code:', result.code);
        console.log('Balance:', result.message);
    } catch (error) {
        console.error('Error:', error);
    }
};

Retrieving Message History

// JavaScript (using fetch API)
const getMessageHistory = async () => {
    const apiUrl = 'http://www.connectmedia.co.ke/user-board/?api';
    
    const formData = new FormData();
    formData.append('username', 'your_username');
    formData.append('password', 'your_password');
    formData.append('action','history');
    
    try {
        const response = await fetch(apiUrl, {
            method: 'POST',
            body: formData
        });
        
        const result = await response.json();
        
        if (result.code === '202') {
            // Process message history
            for (const key in result) {
                if (key !== 'code') {
                    const message = result[key];
                    console.log('Message ID:', message.message_id);
                    console.log('Text:', message.message_text);
                    console.log('Date:', message.message_date);
                    console.log('Status:', message.message_status);
                    console.log('Error:', message.message_error);
                    console.log('---');
                }
            }
        } else {
            console.error('Error:', result.message);
        }
    } catch (error) {
        console.error('Error:', error);
    }
};

2-Way SMS (Inbox)

// JavaScript (using fetch API)
const getInboxMessages = async () => {
    const apiUrl = 'http://www.connectmedia.co.ke/user-board/?api_v2';
    
    const formData = new FormData();
    formData.append('username', 'your_username');
    formData.append('password', 'your_password');
    formData.append('action', 'inbox');
    
    try {
        const response = await fetch(apiUrl, {
            method: 'POST',
            body: formData
        });
        
        const result = await response.json();
        
        if (result.code === '302') {
            // Process inbox messages
            for (const key in result) {
                if (key !== 'code') {
                    const message = result[key];
                    console.log('Message:', message.message_text);
                    console.log('Date:', message.message_datetime);
                    console.log('From:', message.message_from);
                    console.log('---');
                }
            }
        } else if (result.code === '301') {
            console.error('Error in fetching data');
        }
    } catch (error) {
        console.error('Error:', error);
    }
};

Sending an SMS Message

import requests

def send_sms():
    api_url = 'http://www.connectmedia.co.ke/user-board/?api'
    
    payload = {
        'username': 'your_username',
        'password': 'your_password',
        'action': 'send',
        'to': '254712345678',
        'sender': 'ConectMedia',
        'message': 'Hello from Connect Media API'
    }
    
    try:
        response = requests.post(api_url, data=payload)
        result = response.json()
        
        print(f"Response code: {result['code']}")
        print(f"Response message: {result['message']}")
    except Exception as e:
        print(f"Error: {e}")

# Call the function
send_sms()

Checking Account Balance

import requests

def check_balance():
    api_url = 'http://www.connectmedia.co.ke/user-board/?api'
    
    payload = {
        'username': 'your_username',
        'password': 'your_password',
        'action': 'balance'
    }
    
    try:
        response = requests.post(api_url, data=payload)
        result = response.json()
        
        print(f"Response code: {result['code']}")
        print(f"Balance: {result['message']}")
    except Exception as e:
        print(f"Error: {e}")

# Call the function
check_balance()

Retrieving Message History

import requests

def get_message_history():
    api_url = 'http://www.connectmedia.co.ke/user-board/?api'
    
    payload = {
        'username': 'your_username',
        'password': 'your_password',
        'action': 'history'
    }
    
    try:
        response = requests.post(api_url, data=payload)
        result = response.json()
        
        if result['code'] == '202':
            # Process message history
            for key, message in result.items():
                if key != 'code':
                    print(f"Message ID: {message['message_id']}")
                    print(f"Text: {message['message_text']}")
                    print(f"Date: {message['message_date']}")
                    print(f"Status: {message['message_status']}")
                    print(f"Error: {message['message_error']}")
                    print('---')
        else:
            print(f"Error: {result['message']}")
    except Exception as e:
        print(f"Error: {e}")

# Call the function
get_message_history()

2-Way SMS (Inbox)

import requests

def get_inbox_messages():
    api_url = 'http://www.connectmedia.co.ke/user-board/?api_v2'
    
    payload = {
        'username': 'your_username',
        'password': 'your_password',
        'action': 'inbox'
    }
    
    try:
        response = requests.post(api_url, data=payload)
        result = response.json()
        
        if result['code'] == '302':
            # Process inbox messages
            for key, message in result.items():
                if key != 'code':
                    print(f"Message: {message['message_text']}")
                    print(f"Date: {message['message_datetime']}")
                    print(f"From: {message['message_from']}")
                    print('---')
        elif result['code'] == '301':
            print("Error in fetching data")
    except Exception as e:
        print(f"Error: {e}")

# Call the function
get_inbox_messages()

Additional Information

Sender ID: Remember that the Sender ID is ConectMedia (with one 'n'), not "ConnectMedia". This is because the Unique Sender ID can only be a maximum of 11 characters.