Skip to main content
POST
/
api
/
v1
/
sms
/
test
Test SMS Integration
curl --request POST \
  --url https://api.example.com/api/v1/sms/test
{
  "status": "<string>",
  "message": "<string>",
  "messageId": "<string>",
  "recipient": "<string>"
}

​
Overview

Send a test SMS message to verify that the Africa’s Talking SMS integration is working correctly. This endpoint is useful during development and setup.

​
Query Parameters

​
phone_number
string
default:"+254733000000"
Phone number to send the test message to

​
Response

​
status
string
Status of the test (success or error)
​
message
string
Status message or error description
​
messageId
string
Message ID if successful
​
recipient
string
Phone number that received the test message

​
Example Request

# Test with default number
curl -X POST "http://localhost:8000/api/v1/sms/test"

# Test with specific number
curl -X POST "http://localhost:8000/api/v1/sms/test?phone_number=%2B254712345678"

​
Example Response (Success)

{
  "status": "success",
  "message": "SMS sent successfully",
  "messageId": "ATXid_test123",
  "recipient": "+254733000000"
}

​
Example Response (Service Unavailable)

{
  "status": "error",
  "message": "SMS service not available. Check AT_API_KEY environment variable."
}

​
Example Response (Send Failure)

{
  "status": "error",
  "message": "SMS test failed: Invalid phone number format"
}

​
Status Codes

  • 200 - Test completed (check status field in response)

​
Test Message Format

The test message follows this pattern: 
VoicePact SMS Test - HH:MM:SS
The timestamp helps identify when each test was sent.

​
Use Cases

  • Initial Setup: Verify Africa’s Talking credentials are correct
  • Development: Confirm SMS integration during local development
  • Debugging: Test SMS functionality when troubleshooting issues
  • Sandbox Testing: Send test messages in sandbox environment

​
Testing with Sandbox

Africa’s Talking provides a sandbox environment for testing. Test messages sent in sandbox mode:
  • Will not be delivered to real phones
  • Will appear in the sandbox simulator
  • Will not incur charges
To use sandbox mode, set: 
AT_USERNAME=sandbox
AT_API_KEY=your_sandbox_api_key

​
Implementation

This endpoint uses a fixed Africa’s Talking client instance to send a simple test message with the current time. Source: sms.py:142-161

​
Troubleshooting

Problem: The AT_API_KEY environment variable is not set or invalidSolution:
  1. Check your .env file has AT_API_KEY set
  2. Verify the API key is correct (copy from Africa’s Talking dashboard)
  3. Restart the server after updating environment variables
Problem: Phone number doesn’t include country codeSolution: Use international format with + and country code:
  • Correct: +254712345678
  • Incorrect: 0712345678 or 712345678
Problem: Using sandbox credentialsSolution:
  • Sandbox messages only appear in the AT simulator, not on real phones
  • To send to real phones, use production credentials
  • Check the Africa’s Talking dashboard for delivery status

​
Next Steps

Send SMS

Send actual SMS messages

SMS Status

Check SMS service status

Africa's Talking Setup

Complete integration guide

Environment Setup

Configure credentials

Build docs developers (and LLMs) love

Get started for freeTalk to us