Back to Blog List
Share this?
Dear Valued Customer,
Our API is easy to integrate and use.
CHECK ACCOUNT BALANCE
Checking your account balance is as follows:
Where:
your_apikey is your account API KEY on your account DashBoard
SENDING A MESSAGE
Sending a message is as follow:
Where:
your_apikey is your account API KEY on your account DashBoard
sender_id is the sender id of your message
recipients_phone_numbers are the phone numbers you are sending your message to. The numbers are seperated by commas (,).
Eg: 08169615492,0803333333,0816666666
message is your the body of your message
sim (Optional) The value is either 0, 1 or 2. If not set is assumed to be 0.
If set to 0, your SMS is sent via the regular route and those on DND are sent via hosted sim
If set to 1, all your SMS are sent via hosted sim irrespective of if they are on DND or not
If set to 2, all your SMS are sent via Corporate Route irrespective of if they are on DND or not
PS: If you have a hosted SIM, yours will be used. If you do not have, our default sim is used.
Get your own SIM?
+ RESPONSE: When you succeed in sending a message like that above, you should see a JSON Repsonse like
{"status":"OK","id":"1522059636","amount":"5"}
Where OK means the message was successfully sent and 5 is the number of SMS Units you were charged.
The number (1522059636) is the unique SMS ID. This can be used to check delivery reports of SMS sent.
SCHEDULING A MESSAGE
Scheduling a message allows you set the date and time you want the message sent automatically in future even if you are OFFLINE or SLEEPING.
It has the same features as SENDING A MESSAGE above except with the schedule parameter.
The schedule parameter allows you set the date and time.
Where:
your_apikey is your account API KEY on your account DashBoard
sender_id is the sender id of your message
recipients_phone_numbers are the phone numbers you are sending your message to. The numbers are seperated by commas (,).
Eg: 08169615492,0803333333,0816666666
message is your the body of your message
schedule is the date and time you are scheduling your message for.
Kindly note the date and time format Day/Month/Year @ Hour/Minute (am or pm)
sim (Optional) The value is either 0, 1 or 2. If not set is assumed to be 0.
If set to 0, your SMS is sent via the regular route and those on DND are sent via hosted sim
If set to 1, all your SMS are sent via hosted sim irrespective of if they are on DND or not
If set to 2, all your SMS are sent via Corporate Route irrespective of if they are on DND or not
PS: If you have a hosted SIM, yours will be used. If you do not have, our default sim is used.
Get your own SIM?
+ RESPONSE: When you succeed in scheduling a message, you should see a JSON Repsonse like
{"status":"OK","id":"1522059636","amount":"5", "duedate":"12/03/2018 @ 11:30 pm"}
Meaning the message has been scheduled for 12/03/2018 @ 11:30 pm and will cost an estimated (5) SMS Units to send.
Kindly ensure you have more than the estimate SMS Units before the scheduled date.
The number (1522059636) is the unique SMS ID. This can be used to check delivery reports of SMS after they are sent.
DELIVERY REPORTS
Check delivery report on SMS sent in either of 2 ways: By Query URL or request Delivery Push (Webhook)
[1] Delivery Push (Webhook): You can specify a URL where your delivery reports can be pushed.
Login and go to the EDIT PROFILE PAGE
to enter the URL and save.
All delivery reports will be pushed to the saved URL in a NON JSON array (POST).
The following Parameters are pushed via POST to your delivery report URL
network is the Telco used to send SMS
messageid is the message ID or SMS ID
senderid is the Sender ID used
delverystatus is the delivery status of the SMS (DELIVERED or FAILED)
number is the phone number SMS was sent to
sendtime is the time the SMS was sent (unix timestamp)
deliverytime is the time SMS was delivered (unix timestamp)
[2] Query URL: Checking delivery report on SMS sent with URL as follows:
Where:
your_apikey is your account API KEY on your account DashBoard
sms_id is the SMS ID returned when you sent the message like 1522059636 in the example above.
+ Each report is seperated by "|" symbol. So after each "|" is a new report. Delivery reports are updated as received so the amount displayed may increase over time.
Example of Report:
| 234703721111113 - DELIVRD / DELIVRD to SIM - MTN - Greenspek - [1.03 Mins]
| 234808661111112 - DELIVRD / DELIVRD to SIM - Sent Via Hosted SIM - [2.46 Mins]
| 23480581111114 - UNDELIV / Unknown Error - globacom - infiniti - [6.03 Mins]
The report shows the Phone Number, Delivery Status (DELIVRD or UNDELIV), the Network it was sent to, the Sender ID (which may be changed due to DND) and the Amount of Time (in Minutes) taken to deliver the message.
SEND SMS OTP
Send new SMS otp is as follows:
Where:
your_apikey is your account API KEY on your account DashBoard
phone receivers phone number
ref is a unique reference you can use to check status
otp is the OTP code passed in SMS. Should be between 3 and 6 digits else call will fail
expiration is the amount in Minutes the OTP SMS will expire
+ RESPONSE: Success JSON
{"success":true,"comment":"OTP Sent - 2348169615492 - (8903 expires in 12 Mins)","log_id":"smsotp-cd070b516009358e8398d","ref_id":"38238908032323F93029302","timestamp":"1732969908","otp":"8903","amount":"2.2"}
+ RESPONSE: Failed JSON
{"success":false,"comment":"OTP Sent - 2348169615492 - (8903 expires in 30 Mins)","log_id":"smsotp-cd070b516009358e8398d","ref_id":"38238908032323F93029302","timestamp":"1732969908","otp":"8903","amount":"2.2"}
SEND VOICE OTP
Send new voice otp is as follows:
Where:
your_apikey is your account API KEY on your account DashBoard
phone receivers phone number
ref is a unique reference you can use to check call status
otp is the OTP code passed in call. Should be between 3 and 6 digits else call will fail
+ RESPONSE: Success JSON
{"success":true, "comment":"Voice OTP submitted successfully. - 2348169615492 - (8903)", "log_id":"VOTP-a814195bf21527c2","ref_id":"38238908032323F", "timestamp":"1421358257","amount":"2.4"}
+ RESPONSE: Failed JSON
{"success":false, "comment":"Voice OTP submitting failed. - 08169615492 - (904)", "log_id":"VOTP-36143f11933991914142d72a7474e59a8089", "ref_id":"32038028932","timestamp":"1421358095" ,"amount":"0.0"}
CHECK VOICE OR SMS OTP STATUS
[1] We send delivery push (webhook) to a URL you specify on your account profile. Login and go to the EDIT PROFILE PAGE
to enter the URL and save.
All delivery reports will be pushed to the saved URL via POSTin a NON JSON array (POST).
The following Parameters are pushed via POST to your delivery report URL
network Service in Use (it can be SMS or Voice)
messageid is the Voice Call ID
carrier Network of receivers number
delverystatus is the delivery status of the Call.
number is the phone number call was made to
sendtime is the time the call was made (unix timestamp)
duration length of the call in seconds or SMS expiration in Mins
[2] You can also check voice otp status via direct URL query as follows:
Where:
your_apikey is your account API KEY on your account DashBoard
ref Your unique reference used when sending the OTP. You can also use our log_id returned in the JSON response. Both parameters work for this endpoint.
+ RESPONSE:
{"success":true, "comment":"VoiceOTP DLR query successful", "status":"answered", "details":"VoiceOTP delivered successfully, recipient answered the call", "phone":"2349155895233", "posted":"2024-07-25 12:11:26", "called":"2024-07-25 12:11:26", "log_id":"votp-20240725-WTvw3I0Q8QfGXK4dM1TmUwnDNl", "ref_id":"38238908032323F"}
CONFIGURATION
It is adviced (NOT compulsory) you use the POST method when submitting instead of GET, especially when sending messages to many numbers.
The reason is GET method is limited to a certain lenght of characters which if exceeded will give a (HTTP Error 400 - Bad Request - Request Too Long). POST method does not give this error.
Our API accepts both GET and POST methods
Sample Code
$c = curl_init("https://www.greenspek.net/ balance.php?apikey=your_apikey");
curl_setopt($c, CURLOPT_CONNECTTIMEOUT,60);
curl_setopt($c, CURLOPT_POST, 1);
curl_setopt ($c, CURLOPT_RETURNTRANSFER, true);
curl_setopt($c, CURLOPT_HEADER, 0);
curl_setopt($c, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($c, CURLOPT_SSL_VERIFYHOST, false);
$daresponse = curl_exec($c);
curl_close($c);
echo $daresponse;
ERROR CODES
G101 = One or more required fields are empty or invalid
G102 = Sender ID not allowed (Should NOT be longer than 11 Characters or less than 4 or only Numbers)
G103 = SMS Sending Failed
G104 = Invalid API Key
G105 = Account Balance exhausted
G106 = Insufficent Account Balance for this Message
G107 = Gateway unavailable
G108 = Invalid Schedule date or time format
G109 = Scheduled date has passed
G110 = API Key is empty
G111 = Password is empty
G112 = Recipient is empty or invalid
G113 = Message is empty
G114 = Sender is empty
G115 = Missing or Invalid Data like SMS ID, REF_ID or API key may be empty or invalid
G116 = Message has SPAM related word(s)
+ Remember to UrlEncode your Messages
+ Please note that once set, scheduled messages CANNOT be modified via the API. You have to log into your account to modify it.
+ Ensure your message or sender ID does NOT contain banned keywords. Read More
+ Use this format 081-6961-5492 when adding phone numbers to SMS body. DO NOT add numbers like this 08169615492 or it MAY be blocked by the networks
+ All API interactions like sent messages, unsent messages or drafts and scheduled messages are saved to your account by default.
+ Test your SMS length and avoid special characters that may increase your SMS size. Read More
+ If you have issues with this API integration, kindly
Contact Us