Reference Documentation
Service endpoint
A service endpoint is a base URL that specifies the network address of an API service. One service might have multiple service endpoints. This service has the following service endpoint and all URIs below are relative to this service endpoint:
https://developers.smswithoutborders.com:14000
API V1 Endpoints
Action |
Endpoint |
Parameters |
Request body |
POST /v1/sms |
None |
|
|
POST /v1/sms/operators |
None |
|
|
PUT /v1/metrics/<uid> |
|
|
Warning
We advise you to use this endpoint safely in the back-end to avoid exposing your developer’s token to unauthorized persons.
Examples using curl
Send single SMS message
Note
To send messages using Twilio Messaging Service, twilio_account_sid
, twilio_auth_token
and, either twilio_service_sid
or twilio_from
fields should be present in the request body.
Phone numbers with country calling codes listed in the whitelist
, will NOT
receive messages through the Twilio Messaging Service.
Country calling codes listed in the whitelist
field should begin with a +
symbol (e.g “+237”).
Note
The uuid
key is any random string provided by the user used to identify the request. If left empty, OpenAPI will populate the uuid
key with a randomly generated uuid.
The callback_url
will be invoked after the request is complete with a POST
in the form:
{
"errors": [{
"operator_name":"",
"number":"",
"error_message": "",
"timestamp": ""
}],
"uuid": ""
}
If the
errors
array is empty all messages were requested successfully.callback_url
field accepts multiple urls, seperate each with a comma. Example “callback_url”:”https://example.com,https://example1.com,https://example2.com”
The phone number format to be used in the request bodies of the API calls should be E.164.
curl --location --request POST 'https://developers.smswithoutborders.com:14000/v1/sms' \
--header 'Content-Type: application/json' \
--data-raw '{
"auth_id":"",
"twilio_account_sid": "",
"twilio_auth_token": "",
"twilio_service_sid": "",
"twilio_from": "",
"whitelist": ["+237"],
"data": [{
"text":"",
"number":""
}],
"callback_url": "",
"uuid": ""
}'
Send bulk SMS messages
Note
To send messages using Twilio Messaging Service, twilio_account_sid
, twilio_auth_token
and, either twilio_service_sid
or twilio_from
fields should be present in the request body.
Phone numbers with country calling codes listed in the whitelist
, will NOT
receive messages through the Twilio Messaging Service.
Country calling codes listed in the whitelist
field should begin with a +
symbol (e.g “+237”).
Note
The uuid
key is any random string provided by the user used to identify the request. If left empty, OpenAPI will populate the uuid
key with a randomly generated uuid.
The callback_url
will be invoked after the request is complete with a POST
in the form:
{
"errors": [{
"operator_name":"",
"number":"",
"error_message": "",
"timestamp": ""
}],
"uuid": ""
}
If the
errors
array is empty all messages were requested successfully.callback_url
field accepts multiple urls, seperate each with a comma. Example “callback_url”:”https://example.com,https://example1.com,https://example2.com”
The phone number format to be used in the request bodies of the API calls should be E.164.
curl --location --request POST 'https://developers.smswithoutborders.com:14000/v1/sms' \
--header 'Content-Type: application/json' \
--data-raw '{
"auth_id":"",
"twilio_account_sid": "",
"twilio_auth_token": "",
"twilio_service_sid": "",
"twilio_from": "",
"whitelist": ["+237"],
"data": [{
"text":"",
"number":""
},
{
"text":"",
"number":""
},
{
"text":"",
"number":""
}],
"callback_url": "",
"uuid": ""
}'
Get Phone Number operator name
The text
key is optional and can be left out of the request body.
curl --location --request POST 'https://developers.smswithoutborders.com:14000/v1/sms/operators' \
--header 'Content-Type: application/json' \
--data-raw '[
{
"text":"",
"number":""
},
{
"text":"",
"number":""
},
{
"text":"",
"number":""
}
]'
Update message status
There are two steps involved in the update process
2. Update status
Note
This step requires the user to have an SMSWithoutBorders OpenAPI setup and configured to communitcate with their SMSWithoutBorders Developer Back-end server.
The user has to make sure SMSWithoutBorders Developer Back-end server is running.
The user has to provide the following in the request body:
status (The message status. Either sent, delivered, failed, requested)
message (Information regarding the message status)
The user also must configure their header to:
Content-Type = application/json
Here is an example. Running SMSWithoutBorders OpenAPI locally on port 4000
curl --location --request POST 'http://localhost:4000/v1/metrics/<uid>' \
--header 'Content-Type: application/json' \
--data-raw '{
"status": "",
"message": ""
}'