UMSComms API Documentation

Comprehensive guide to integrating with UMSComms communication services including SMS, WhatsApp, and Android device messaging.

Introduction

Welcome to the UMSComms API Documentation. This guide helps developers integrate applications with UMSComms, enabling seamless communication services. The API provides access to features such as airtime purchases, WhatsApp messaging, SMS services, and more.

Before You Start

You'll need to generate API credentials to authenticate your requests. See the API Key Generation section for details.

Generating API Keys

To interact with UMSComms services, generate an API key. Both API key and App ID are required for authentication.

Steps to Generate an API Key

  1. Navigate to API Settings: Log in to your UMSComms account and go to "API Settings".
  2. Click Generate API Key: Locate and click the "Generate API Key" button.
  3. Provide App Details:
    • App Name: Name of your application
    • Product: Services your app will use (Airtime, WhatsApp, SMS)
  4. Generate Key: Click "Generate" to create unique API key and App ID.

Example Credentials

// API Credentials
API Key: "1db708db9157ec9156528743650e4ae7"
App ID: "UMSC803833"
API URL: "https://comms.umeskiasoftwares.com"

Send SMS API

Send SMS messages to one or more recipients. Supports both POST and GET methods.

POST /api/v1/sms/send

Send SMS messages via HTTP POST request.

Request Parameters

Parameter Type Required Description
api_key string Yes Your UMSComms API key
app_id string Yes Application ID
sender_id string Yes Sender ID for SMS (default: UMS_TX or UMS_SMS)
message string Yes Message content (max 160 chars per SMS)
phone string Yes Comma-separated recipient numbers

Example Request

// POST Request
{
  "api_key": "1db708db9157ec9156528743650e4ae7",
  "app_id": "UMSC803833",
  "sender_id": "UMS_SMS",
  "message": "Hello, your verification code is 1234",
  "phone": "254712345678,254798765432"
}

Success Response

{
  "status": "complete",
  "message": "SMS sending completed",
  "data": [
    {
      "phone": "254712345678",
      "status": "success",
      "message_id": "req12345",
      "sms_cost": 1
    }
  ]
}

Error Handling

{
  "status": "error",
  "error_code": 1001,
  "message": "API key and App ID are required"
}

Common Error Codes:

Code Description
1001 API key and App ID required
1002 Invalid credentials
1005 Message content required
2001 SMS sending failure
GET /api/v1/sms/send/ums

Send SMS messages via HTTP GET request with query parameters.

Request Parameters

Parameter Type Required Description
api_key string Yes Your UMSComms API key
app_id string Yes Application ID
sender_id string Yes Sender ID for SMS (default: UMS_TX or UMS_SMS)
message string Yes Message content (URL-encoded, max 160 chars per SMS)
phone string Yes Comma-separated recipient numbers

Example Request

// GET Request
https://comms.umeskiasoftwares.com/api/v1/sms/send/ums?
  api_key=1db708db9157ec9156528743650e4ae7&
  app_id=UMSC803833&
  sender_id=UMS_SMS&
  message=Hello%20your%20OTP%20is%201234&
  phone=254712345678,254798765432

Success Response

{
  "status": "complete",
  "message": "SMS sending completed",
  "data": [
    {
      "phone": "254712345678",
      "status": "success",
      "message_id": "req12345",
      "sms_cost": 1
    }
  ]
}

Error Handling

{
  "status": "error",
  "error_code": 1001,
  "message": "API key and App ID are required"
}

Common Error Codes:

Code Description
1001 API key and App ID required
1002 Invalid credentials
1005 Message content required
2001 SMS sending failure

Send WhatsApp Message API

Send WhatsApp messages through connected Android devices.

POST /api/v1/whatsapp/send

Request Parameters

Parameter Type Required Description
api_key string Yes Your API key
app_id string Yes Application ID
device_id string Yes ID of connected Android device
phone string Yes Recipient's phone number
message string Yes Message content (max 4096 chars)

Example Request

// POST Request
{
  "api_key": "1db708db9157ec9156528743650e4ae7",
  "app_id": "UMSC803833",
  "device_id": "AND12345",
  "phone": "254712345678",
  "message": "Hello, your verification code is 5678"
}

Note

WhatsApp messages are limited to 4096 characters. The recipient must have your number saved in their contacts for the message to appear as a business message.

GET /api/v1/whatsapp/send/ums

Request Parameters

Parameter Type Required Description
api_key string Yes Your unique API key
app_id string Yes Registered App ID
device_id string Yes ID of your connected Android device
phone string (comma-separated) Yes Comma-separated phone numbers in international format (e.g. 254712345678)
message string Yes Message to be sent (max 4096 characters)

Example Request

// Example GET Request
https://comms.umeskiasoftwares.com/api/v1/whatsapp/send/ums?
api_key=1db708db9157ec9156528743650e4ae7&
app_id=UMSC803833&
device_id=AND12345&
message=Hello%20your%20OTP%20is%201234&
phone=254712345678,254798765432

Note

- The phone parameter supports multiple comma-separated values.
- Message must be URL-encoded.
- The receiving user should have the sender’s WhatsApp number saved to ensure successful delivery as a business message.
- Maximum message length: 4096 characters.

Receive WhatsApp Message

Feature Under Development

The WhatsApp message receiving API will be available in upcoming versions with the following features:

  • Webhook integration for real-time message delivery
  • Support for media messages (images, documents, audio)
  • Message filtering and routing capabilities
  • Automated response triggers

Check back in our next release for updates!

Send Android SMS API

Send SMS messages through a connected Android device.

POST /api/v1/phone/send-sms

Request Parameters

Parameter Type Required Description
api_key string Yes Your API key
app_id string Yes Application ID
phonenumber string Yes Recipient's phone number
phone_id string Yes ID of connected phone
message string Yes SMS content (max 160 chars per SMS)

Example Request

// POST Request
{
  "api_key": "1db708db9157ec9156528743650e4ae7",
  "app_id": "UMSC803833",
  "phonenumber": "254712345678",
  "phone_id": "PH12345",
  "message": "Hello from UMSComms Android API"
}

Important

The Android device must be connected to the internet and have the UMSComms app installed and running. SMS delivery depends on the device's cellular connectivity.