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.

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.

// Example of authentication parameters
$username = 'your_username';
$password = 'your_password';

Endpoints

Base URL

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

Available Actions

Parameters

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

Response Codes

The ConnectMedia API uses standard HTTP status codes along with custom response codes to indicate the status of API requests.

Standard HTTP Status Codes

API Response Codes

Examples

The following examples demonstrate how to use the ConnectMedia API for various operations.

username=your_username&password=your_password&action=send&to=254712345678&sender=ConectMedia&message=Hello+from+Connect+Media!

{
  "code": "201",
  "message": "Message Sent Successfully!",
  "message_id": "CM123456789"
}

{
  "code": "101",
  "message": "No enough balance to send message"
}

{
  "code": "500",
  "message": "Failed to send message: [error details]"
}

username=your_username&password=your_password&action=balance

{
  "code": "200",
  "message": "1250.50"
}

username=your_username&password=your_password&action=history&limit=10&start_date=2023-01-01

{
  "0": {
    "message_id": "12345",
    "message_text": "Hello from Connect Media!",
    "message_date": "2023-01-15 10:30:45",
    "message_status": "Delivered",
    "message_error": "OK"
  },
  "1": {
    "message_id": "12346",
    "message_text": "Your verification code is 123456",
    "message_date": "2023-01-16 14:22:10",
    "message_status": "Delivered",
    "message_error": "OK"
  },
  "code": "202"
}

username=your_username&password=your_password&action=inbox&limit=10

{
  "0": {
    "message_text": "Yes, please proceed with the order",
    "message_datetime": "2023-01-15 11:45:22",
    "message_from": "254712345678"
  },
  "1": {
    "message_text": "My verification code is 654321",
    "message_datetime": "2023-01-16 09:12:05",
    "message_from": "254723456789"
  },
  "code": "302"
}

{
  "code": "302",
  "message": "No messages found"
}

Code Samples

Here are complete code samples to help you integrate with the ConnectMedia API in different programming languages.

PHP

<?php
// ConnectMedia API Client - Complete Example

function connectMediaAPI($action, $params = []) {
    // Base API configuration
    $api_url = 'https://www.connectmedia.co.ke/user-board/?api';
    $credentials = [
        'username' => 'your_username',
        'password' => 'your_password'
    ];
    
    // If action is 'inbox', use the v2 API endpoint
    if ($action === 'inbox') {
        $api_url = 'https://www.connectmedia.co.ke/user-board/?api_v2';
    }
    
    // Merge credentials with other parameters
    $post_data = array_merge($credentials, ['action' => $action], $params);
    
    // Initialize cURL session
    $ch = curl_init($api_url);
    
    // Set cURL options
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    
    // Execute the request
    $response = curl_exec($ch);
    $error = curl_error($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    // Handle response
    if ($error) {
        return [
            'success' => false,
            'error' => "cURL Error: $error"
        ];
    }
    
    // Parse JSON response
    $result = json_decode($response, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        return [
            'success' => false,
            'error' => 'Invalid JSON response',
            'raw_response' => $response
        ];
    }
    
    return [
        'success' => ($http_code == 200),
        'http_code' => $http_code,
        'data' => $result
    ];
}

// 1. Send an SMS message
function sendSMS($to, $message, $sender = 'ConectMedia') {
    return connectMediaAPI('send', [
        'to' => $to,
        'message' => $message,
        'sender' => $sender
    ]);
}

// 2. Check account balance
function checkBalance() {
    return connectMediaAPI('balance');
}

// 3. Retrieve message history
function getMessageHistory($limit = 50, $offset = 0, $start_date = null, $end_date = null) {
    $params = [
        'limit' => $limit,
        'offset' => $offset
    ];
    
    if ($start_date) {
        $params['start_date'] = $start_date;
    }
    
    if ($end_date) {
        $params['end_date'] = $end_date;
    }
    
    return connectMediaAPI('history', $params);
}

// 4. Retrieve inbox messages
function getInboxMessages($limit = 50, $offset = 0, $start_date = null, $end_date = null) {
    $params = [
        'limit' => $limit,
        'offset' => $offset
    ];
    
    if ($start_date) {
        $params['start_date'] = $start_date;
    }
    
    if ($end_date) {
        $params['end_date'] = $end_date;
    }
    
    return connectMediaAPI('inbox', $params);
}

// Usage Examples

// Example 1: Send an SMS
$sendResult = sendSMS('254712345678', 'Hello from ConnectMedia API!');
if ($sendResult['success']) {
    echo "Message sent successfully! ID: " . $sendResult['data']['message_id'] . "\n";
} else {
    echo "Failed to send message: " . ($sendResult['data']['message'] ?? 'Unknown error') . "\n";
}

// Example 2: Check balance
$balanceResult = checkBalance();
if ($balanceResult['success']) {
    echo "Current balance: " . $balanceResult['data']['message'] . "\n";
} else {
    echo "Failed to retrieve balance\n";
}

// Example 3: Get message history
$historyResult = getMessageHistory(10, 0, '2023-01-01');
if ($historyResult['success']) {
    $messages = $historyResult['data'];
    $code = $messages['code'];
    unset($messages['code']);
    
    echo "Message History (Code: $code):\n";
    foreach ($messages as $message) {
        echo "ID: " . $message['message_id'] . "\n";
        echo "Text: " . $message['message_text'] . "\n";
        echo "Date: " . $message['message_date'] . "\n";
        echo "Status: " . $message['message_status'] . "\n";
        echo "-------------------------------\n";
    }
} else {
    echo "Failed to retrieve message history\n";
}

// Example 4: Get inbox messages
$inboxResult = getInboxMessages(10);
if ($inboxResult['success']) {
    $messages = $inboxResult['data'];
    $code = $messages['code'];
    unset($messages['code']);
    
    if (isset($messages['message']) && $messages['message'] === 'No messages found') {
        echo "No inbox messages found\n";
    } else {
        echo "Inbox Messages (Code: $code):\n";
        foreach ($messages as $message) {
            echo "From: " . $message['message_from'] . "\n";
            echo "Text: " . $message['message_text'] . "\n";
            echo "Date: " . $message['message_datetime'] . "\n";
            echo "-------------------------------\n";
        }
    }
} else {
    echo "Failed to retrieve inbox messages\n";
}
?>

JavaScript

// ConnectMedia API Client - Complete Example

class ConnectMediaAPI {
  constructor(username, password) {
    this.credentials = {
      username: username,
      password: password
    };
    this.baseUrl = 'https://www.connectmedia.co.ke/user-board/';
  }
  
  async request(action, params = {}) {
    // Determine API endpoint
    const apiEndpoint = action === 'inbox' ? '?api_v2' : '?api';
    const url = this.baseUrl + apiEndpoint;
    
    // Prepare form data
    const formData = new FormData();
    formData.append('action', action);
    
    // Add credentials
    Object.keys(this.credentials).forEach(key => {
      formData.append(key, this.credentials[key]);
    });
    
    // Add other parameters
    Object.keys(params).forEach(key => {
      formData.append(key, params[key]);
    });
    
    try {
      // Send the request
      const response = await fetch(url, {
        method: 'POST',
        body: formData
      });
      
      // Parse response
      const result = await response.json();
      
      return {
        success: response.ok,
        status: response.status,
        data: result
      };
    } catch (error) {
      return {
        success: false,
        error: error.message
      };
    }
  }
  
  // 1. Send an SMS message
  async sendSMS(to, message, sender = 'ConectMedia') {
    return this.request('send', {
      to: to,
      message: message,
      sender: sender
    });
  }
  
  // 2. Check account balance
  async checkBalance() {
    return this.request('balance');
  }
  
  // 3. Retrieve message history
  async getMessageHistory(limit = 50, offset = 0, startDate = null, endDate = null) {
    const params = {
      limit: limit,
      offset: offset
    };
    
    if (startDate) {
      params.start_date = startDate;
    }
    
    if (endDate) {
      params.end_date = endDate;
    }
    
    return this.request('history', params);
  }
  
  // 4. Retrieve inbox messages
  async getInboxMessages(limit = 50, offset = 0, startDate = null, endDate = null) {
    const params = {
      limit: limit,
      offset: offset
    };
    
    if (startDate) {
      params.start_date = startDate;
    }
    
    if (endDate) {
      params.end_date = endDate;
    }
    
    return this.request('inbox', params);
  }
}

// Usage Examples

async function runExamples() {
  const api = new ConnectMediaAPI('your_username', 'your_password');
  
  try {
    // Example 1: Send an SMS
    console.log('Sending SMS...');
    const sendResult = await api.sendSMS('254712345678', 'Hello from ConnectMedia API!');
    if (sendResult.success) {
      console.log(`Message sent successfully! ID: ${sendResult.data.message_id}`);
    } else {
      console.log(`Failed to send message: ${sendResult.data.message || 'Unknown error'}`);
    }
    
    // Example 2: Check balance
    console.log('\nChecking balance...');
    const balanceResult = await api.checkBalance();
    if (balanceResult.success) {
      console.log(`Current balance: ${balanceResult.data.message}`);
    } else {
      console.log('Failed to retrieve balance');
    }
    
    // Example 3: Get message history
    console.log('\nRetrieving message history...');
    const historyResult = await api.getMessageHistory(10, 0, '2023-01-01');
    if (historyResult.success) {
      const messages = historyResult.data;
      const code = messages.code;
      delete messages.code;
      
      console.log(`Message History (Code: ${code}):`);
      Object.values(messages).forEach(message => {
        if (typeof message === 'object') {
          console.log(`ID: ${message.message_id}`);
          console.log(`Text: ${message.message_text}`);
          console.log(`Date: ${message.message_date}`);
          console.log(`Status: ${message.message_status}`);
          console.log('-------------------------------');
        }
      });
    } else {
      console.log('Failed to retrieve message history');
    }
    
    // Example 4: Get inbox messages
    console.log('\nRetrieving inbox messages...');
    const inboxResult = await api.getInboxMessages(10);
    if (inboxResult.success) {
      const messages = inboxResult.data;
      const code = messages.code;
      
      if (messages.message === 'No messages found') {
        console.log('No inbox messages found');
      } else {
        console.log(`Inbox Messages (Code: ${code}):`);
        Object.keys(messages).forEach(key => {
          if (key !== 'code' && typeof messages[key] === 'object') {
            const message = messages[key];
            console.log(`From: ${message.message_from}`);
            console.log(`Text: ${message.message_text}`);
            console.log(`Date: ${message.message_datetime}`);
            console.log('-------------------------------');
          }
        });
      }
    } else {
      console.log('Failed to retrieve inbox messages');
    }
    
  } catch (error) {
    console.error('Error:', error);
  }
}

// Run the examples
runExamples();

Python

import requests
from datetime import datetime

# ConnectMedia API Client - Complete Example

class ConnectMediaAPI:
    def __init__(self, username, password):
        self.credentials = {
            'username': username,
            'password': password
        }
        self.base_url = 'https://www.connectmedia.co.ke/user-board/'
    
    def request(self, action, params=None):
        # Determine API endpoint
        api_endpoint = '?api_v2' if action == 'inbox' else '?api'
        url = self.base_url + api_endpoint
        
        # Prepare request data
        data = {'action': action, **self.credentials}
        if params:
            data.update(params)
        
        try:
            # Send the request
            response = requests.post(url, data=data, timeout=30)
            
            # Parse response
            result = response.json()
            
            return {
                'success': response.status_code == 200,
                'status_code': response.status_code,
                'data': result
            }
        except requests.RequestException as e:
            return {
                'success': False,
                'error': str(e)
            }
        except ValueError:
            return {
                'success': False,
                'error': 'Invalid JSON response',
                'raw_response': response.text
            }
    
    # 1. Send an SMS message
    def send_sms(self, to, message, sender='ConectMedia'):
        return self.request('send', {
            'to': to,
            'message': message,
            'sender': sender
        })
    
    # 2. Check account balance
    def check_balance(self):
        return self.request('balance')
    
    # 3. Retrieve message history
    def get_message_history(self, limit=50, offset=0, start_date=None, end_date=None):
        params = {
            'limit': limit,
            'offset': offset
        }
        
        if start_date:
            params['start_date'] = start_date
        
        if end_date:
            params['end_date'] = end_date
        
        return self.request('history', params)
    
    # 4. Retrieve inbox messages
    def get_inbox_messages(self, limit=50, offset=0, start_date=None, end_date=None):
        params = {
            'limit': limit,
            'offset': offset
        }
        
        if start_date:
            params['start_date'] = start_date
        
        if end_date:
            params['end_date'] = end_date
        
        return self.request('inbox', params)


# Usage Examples

def run_examples():
    api = ConnectMediaAPI('your_username', 'your_password')
    
    # Example 1: Send an SMS
    print('Sending SMS...')
    send_result = api.send_sms('254712345678', 'Hello from ConnectMedia API!')
    if send_result['success']:
        print(f"Message sent successfully! ID: {send_result['data'].get('message_id')}")
    else:
        error_msg = send_result['data'].get('message', 'Unknown error') if 'data' in send_result else send_result.get('error', 'Unknown error')
        print(f"Failed to send message: {error_msg}")
    
    # Example 2: Check balance
    print('\nChecking balance...')
    balance_result = api.check_balance()
    if balance_result['success']:
        print(f"Current balance: {balance_result['data'].get('message')}")
    else:
        print('Failed to retrieve balance')
    
    # Example 3: Get message history
    print('\nRetrieving message history...')
    history_result = api.get_message_history(10, 0, '2023-01-01')
    if history_result['success']:
        messages = history_result['data']
        code = messages.get('code')
        
        print(f"Message History (Code: {code}):")
        for key, message in messages.items():
            if key != 'code' and isinstance(message, dict):
                print(f"ID: {message.get('message_id')}")
                print(f"Text: {message.get('message_text')}")
                print(f"Date: {message.get('message_date')}")
                print(f"Status: {message.get('message_status')}")
                print('-------------------------------')
    else:
        print('Failed to retrieve message history')
    
    # Example 4: Get inbox messages
    print('\nRetrieving inbox messages...')
    inbox_result = api.get_inbox_messages(10)
    if inbox_result['success']:
        messages = inbox_result['data']
        code = messages.get('code')
        
        if 'message' in messages and messages['message'] == 'No messages found':
            print('No inbox messages found')
        else:
            print(f"Inbox Messages (Code: {code}):")
            for key, message in messages.items():
                if key != 'code' and isinstance(message, dict):
                    print(f"From: {message.get('message_from')}")
                    print(f"Text: {message.get('message_text')}")
                    print(f"Date: {message.get('message_datetime')}")
                    print('-------------------------------')
    else:
        print('Failed to retrieve inbox messages')


if __name__ == "__main__":
    run_examples()