Ping Africa Unified Communication API

Send SMS, WhatsApp messages, manage USSD sessions, and handle credits — all from one API.

Prerequisites

Before using the API, ensure you have:

1. Account — Register at bulk.ping.africa
2. API Token — Generate from your dashboard (see below)
3. Sender ID — New accounts get PING-AFRICA by default
4. Credits — Purchase credits to send messages

Step 1: Get Your API Token

1. Login to bulk.ping.africa
2. Go to Account Settings → API Tokens
3. Click Create Token
4. Name your token (e.g., "Production API")
5. Copy the token immediately (shown only once)

Step 2: Use Your Token

All authenticated requests require the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Step 3: Send Your First SMS

curl -X POST https://bulk.ping.africa/api/sms/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+254712345678",
    "message": "Hello from Ping Africa!",
    "sender_id": "PING-AFRICA"
  }'

Response:

{
  "success": true,
  "message": {
    "status": "sent",
    "recipient": "+254712345678",
    "parts": 1
  },
  "credits_charged": "0.20",
  "new_balance": 106.6
}

Send Bulk SMS

Send the same message to multiple recipients in one call:

curl -X POST https://bulk.ping.africa/api/sms/send-bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+254712345678", "+254723456789"],
    "message": "Bulk message to all!",
    "sender_id": "PING-AFRICA"
  }'

Sender IDs

What is a Sender ID?

The name/number that appears as the sender when recipients receive your SMS.

Default Sender ID

New organizations are automatically granted access to PING-AFRICA.

Using Sender IDs

• Specify in request: Include sender_id parameter
• Auto-select: If omitted, your default authorized sender ID is used
• No sender ID? Request returns error with available options

Getting Your Own Sender ID

Apply via Dashboard → Shortcodes → Apply for Sender ID

Error when no sender ID available:

{
  "error": "No sender ID available. You must have at least one verified shortcode or authorized system sender ID.",
  "available_sender_ids": []
}

Step 4: Send WhatsApp Messages

WhatsApp messaging requires a connected WhatsApp instance. Set up your instance from the Dashboard under WhatsApp → Instances.

List Your Instances

First, retrieve your connected WhatsApp instances to get the instanceName needed for sending messages:

curl -X GET https://bulk.ping.africa/api/whatsapp/instances \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "success": true,
  "data": [
    {
      "name": "my-instance",
      "connectionStatus": "open",
      "profileName": "My Business"
    }
  ]
}

Use the name field as instanceName in your message requests below. Only instances with connectionStatus: "open" can send messages.

Send a Text Message

curl -X POST https://bulk.ping.africa/api/whatsapp/messages/text \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my-instance",
    "number": "254712345678",
    "text": "Hello from Ping Africa!"
  }'

Response:

{
  "success": true,
  "data": {
    "key": {
      "id": "3EB0148249BCB40099292C"
    },
    "status": "PENDING",
    "messageType": "conversation"
  }
}

The key.id is the message ID you can use to track delivery.

Send a Document (PDF, Word, Excel, etc.)

curl -X POST https://bulk.ping.africa/api/whatsapp/messages/media \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my-instance",
    "number": "254712345678",
    "mediatype": "document",
    "media": "https://example.com/report.pdf",
    "caption": "Monthly Report",
    "fileName": "Report-Feb-2026.pdf"
  }'

Send an Image

curl -X POST https://bulk.ping.africa/api/whatsapp/messages/media \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my-instance",
    "number": "254712345678",
    "mediatype": "image",
    "media": "https://example.com/photo.jpg",
    "caption": "Check this out!"
  }'

Send a Video

curl -X POST https://bulk.ping.africa/api/whatsapp/messages/media \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my-instance",
    "number": "254712345678",
    "mediatype": "video",
    "media": "https://example.com/promo.mp4",
    "caption": "Watch our latest update"
  }'

Send Audio

curl -X POST https://bulk.ping.africa/api/whatsapp/messages/media \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my-instance",
    "number": "254712345678",
    "mediatype": "audio",
    "media": "https://example.com/message.mp3"
  }'

WhatsApp Media Types

Note: The number field should be the phone number without the + prefix (e.g., 254712345678 not +254712345678). The media field must be a publicly accessible URL.

Step 5: USSD Sessions

Build interactive USSD menus for your users. USSD sessions follow a request-response flow: initiate a session, send user inputs, and complete or cancel when done.

Initiate a Session

curl -X POST https://bulk.ping.africa/api/ussd/initiate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "unique-session-123",
    "phone_number": "+254712345678",
    "service_code": "*384*100#"
  }'

Response:

{
  "success": true,
  "session": {
    "id": 1,
    "session_id": "unique-session-123",
    "status": "active"
  },
  "response": "CON Welcome to our service\n1. Check Balance\n2. Buy Airtime\n3. Exit"
}

Send User Input

curl -X POST https://bulk.ping.africa/api/ussd/interact/unique-session-123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "1"
  }'

Response:

{
  "success": true,
  "response": "END Your balance is KES 1,500.00",
  "is_end": true
}

Complete a Session (charges credits)

curl -X POST https://bulk.ping.africa/api/ussd/complete/unique-session-123 \
  -H "Authorization: Bearer $TOKEN"

Cancel a Session

curl -X POST https://bulk.ping.africa/api/ussd/cancel/unique-session-123 \
  -H "Authorization: Bearer $TOKEN"

Get Session Details

curl -X GET https://bulk.ping.africa/api/ussd/session/unique-session-123 \
  -H "Authorization: Bearer $TOKEN"

USSD Response Prefixes: Responses prefixed with CON mean the session continues (show menu, wait for input). Responses prefixed with END mean the session is complete (show message, close).

Step 6: Credits & Billing

Check your balance before sending messages and track your spending.

Check Balance

curl -X GET https://bulk.ping.africa/api/credits/balance \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "balance": 106.6
}

Estimate Cost Before Sending

curl -X POST https://bulk.ping.africa/api/credits/estimate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_type": "sms_local",
    "quantity": 500
  }'

Response:

{
  "service_type": "sms_local",
  "quantity": 500,
  "credits": 100,
  "sufficient_credits": true
}

Service types: sms_local, sms_international, whatsapp, ussd

View Available Packages

curl -X GET https://bulk.ping.africa/api/credits/packages

Note: Credit packages and pricing endpoints are public — no authentication required.

Available APIs

Error Codes

Rate Limits

Quick Start (Complete Example)

# Set your token
TOKEN="your-api-token-here"

# 1. Check credit balance
curl -s -X GET https://bulk.ping.africa/api/credits/balance \
  -H "Authorization: Bearer $TOKEN"

# 2. Send a single SMS
curl -s -X POST https://bulk.ping.africa/api/sms/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+254712345678",
    "message": "Hello from Ping Africa!",
    "sender_id": "PING-AFRICA"
  }'

# 3. Send bulk SMS
curl -s -X POST https://bulk.ping.africa/api/sms/send-bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+254712345678", "+254723456789"],
    "message": "Bulk message to all!",
    "sender_id": "PING-AFRICA"
  }'

# 4. Send a WhatsApp text message
curl -s -X POST https://bulk.ping.africa/api/whatsapp/messages/text \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my-instance",
    "number": "254712345678",
    "text": "Hello via WhatsApp!"
  }'

# 5. Send a PDF via WhatsApp
curl -s -X POST https://bulk.ping.africa/api/whatsapp/messages/media \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "my-instance",
    "number": "254712345678",
    "mediatype": "document",
    "media": "https://example.com/invoice.pdf",
    "caption": "Your invoice",
    "fileName": "Invoice-001.pdf"
  }'

# 6. Start a USSD session
curl -s -X POST https://bulk.ping.africa/api/ussd/initiate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-001",
    "phone_number": "+254712345678",
    "service_code": "*384*100#"
  }'

Support

• Email: support@ping.africa
• Dashboard: bulk.ping.africa