Getting Started

Base URL

All API requests should be made to:

https://pushr.pywe.org/api/client

For local development:

http://localhost:6700/api/client

Response Format

All API responses are in JSON format. Successful SMS sending responses follow this structure:

{
  "id": 123,
  "business": 1,
  "message": "Your message text",
  "status": "sent",
  "created": "2024-01-15T10:30:00Z",
  "cost": "2.50",
  "sender_id": "PYWE",
  "recipients_count": 2
}

Authentication

Push.R SMS API uses API key authentication. This is the simplest and recommended method for sending SMS programmatically.

API Key Authentication

Use your API keys from the dashboard to authenticate your requests.

API keys are passed directly in the request body - no headers needed:

{
  "api_key_public": "your_public_key",
  "api_key_secret": "your_secret_key",
  ...
}

Send SMS

Send SMS messages to one or more recipients using your API keys.

{
  "api_key_public": "your_public_key",
  "api_key_secret": "your_secret_key",
  "message": "Hello! This is a test message.",
  "recipients": ["233558544343", "233548769324"],
  "sender_id": "PYWE",
  "scheduled": false,
  "time_scheduled": null
}

{
  "id": 123,
  "business": 1,
  "message": "Hello! This is a test message.",
  "status": "sent",
  "created": "2024-01-15T10:30:00Z",
  "cost": "2.50",
  "sender_id": "PYWE",
  "recipients_count": 2
}

{
  "detail": "Insufficient balance to send messages."
}

Send Customized SMS

Send personalized SMS messages to multiple recipients using a template and CSV file. Each recipient receives a customized message with their specific data.

contact,name,order_id,amount
233558544343,John Doe,ORD123,150.00
233548769324,Jane Smith,ORD124,200.00
233559876543,Bob Johnson,ORD125,75.50

Hi {name}, your order {order_id} for GHS {amount} is ready for pickup!

{
  "recipients_count": 3,
  "status": "PROCESSING"
}

Check Message Status

Retrieve the status of your sent messages.

{
  "data": [
    {
      "id": 123,
      "message": "Hello!",
      "status": "delivered",
      "created": "2024-01-15T10:30:00Z",
      "cost": "2.50",
      "sender_id": "PYWE",
      "recipients_count": 2
    },
    {
      "id": 124,
      "message": "Test message",
      "status": "pending",
      "created": "2024-01-15T11:00:00Z",
      "cost": "1.25",
      "sender_id": "PYWE",
      "recipients_count": 1
    }
  ],
  "count": 2,
  "next": null,
  "previous": null
}

Code Examples

Here are code examples in different programming languages for sending SMS using the API:

import requests

# Send SMS using API keys
url = "https://pushr.pywe.org/api/client/sms/send-sms"
headers = {"Content-Type": "application/json"}

data = {
    "api_key_public": "your_public_key",
    "api_key_secret": "your_secret_key",
    "message": "Hello from Python! This is a test message.",
    "recipients": ["233558544343", "233548769324"],
    "sender_id": "PYWE"
}

response = requests.post(url, json=data, headers=headers)

if response.status_code == 201:
    result = response.json()
    print(f"Message sent! ID: {result['id']}, Cost: GHS {result['cost']}")
else:
    print(f"Error: {response.json()}")

// Send SMS using API keys
const url = 'https://pushr.pywe.org/api/client/sms/send-sms';

const data = {
  api_key_public: 'your_public_key',
  api_key_secret: 'your_secret_key',
  message: 'Hello from JavaScript!',
  recipients: ['233558544343'],
  sender_id: 'PYWE'
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => {
  console.log('Success:', data);
})
.catch(error => {
  console.error('Error:', error);
});

const axios = require('axios');

const sendSMS = async () => {
  try {
    const response = await axios.post(
      'https://pushr.pywe.org/api/client/sms/send-sms',
      {
        api_key_public: 'your_public_key',
        api_key_secret: 'your_secret_key',
        message: 'Hello from Node.js!',
        recipients: ['233558544343'],
        sender_id: 'PYWE'
      },
      {
        headers: {
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Success:', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
};

sendSMS();

<?php
$url = 'https://pushr.pywe.org/api/client/sms/send-sms';
$data = [
    'api_key_public' => 'your_public_key',
    'api_key_secret' => 'your_secret_key',
    'message' => 'Hello from PHP!',
    'recipients' => ['233558544343'],
    'sender_id' => 'PYWE'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 201) {
    $result = json_decode($response, true);
    echo "Message sent! ID: " . $result['id'] . "\n";
} else {
    echo "Error: " . $response . "\n";
}
?>

# Send SMS with API keys
curl -X POST https://pushr.pywe.org/api/client/sms/send-sms \
  -H "Content-Type: application/json" \
  -d '{
    "api_key_public": "your_public_key",
    "api_key_secret": "your_secret_key",
    "message": "Hello from cURL!",
    "recipients": ["233558544343"],
    "sender_id": "PYWE"
  }'

Important Notes

Phone Number Format

All phone numbers must be in Ghana format: 233XXXXXXXXX (country code + number without leading zero).

SMS Cost Calculation

SMS costs are calculated based on:

• Message length: 160 characters = 1 SMS unit
• Number of recipients: Each recipient is charged separately
• Your pricing plan: Price per SMS unit from your plan

Example: A 320-character message to 10 recipients = 2 SMS units × 10 recipients = 20 SMS units total.

Sender IDs

Sender IDs must be:

• Maximum 11 characters
• Approved by the system before use
• Requested through the dashboard or API

If you don't specify a sender_id, the system will use your first approved sender ID automatically.

Scheduled Messages

You can schedule messages to be sent at a future time:

• Set scheduled: true
• Provide time_scheduled in ISO 8601 format
• Scheduled time must be in the future

Example: "2024-01-20T14:30:00Z"

Error Handling

Common errors you might encounter:

• 400 Bad Request: Invalid parameters, insufficient balance, invalid sender ID
• 401 Unauthorized: Invalid or missing API keys
• 404 Not Found: Business or resource not found

Always check the response status code and handle errors appropriately in your code.

Rate Limits

Rate limits may apply to prevent abuse. Contact support if you need higher limits for your use case.

Support

For additional help, questions, or to report issues, please contact support through your dashboard or visit the dashboard for more information.