Developer Province

Developer API (SMPP / HTTP)

Sending SMS

# API Service URL For Sending SMS
  URL https://vividsms.com/api/send/
  Request Type HTTP_POST
  Spec URL encode all request

# Parameter Description
       user Account username
  pass Account password
  from SMS SenderID
(must <= 11chars for Alphanumerical)
(must <= 16chars for Numerical)
  to Destination number(s)
(must be in international format and no prefix e.g. 234819*******)
Separate with comma if you are sending to multiple recipients e.g. 234805******* , 234803*******
  msg SMS Message content (must <= 905chars)
  type (optional) Message Format
0 = Normal SMS
1 = Flash SMS
2 = Unicode SMS (Arabic, Chinese etc)
  enable_msg_id (optional) 0 = false
1 = true

If TRUE, the API response will contain a unique message_id for your sms. You can then use the returned message_id to check message delivery status via https://vividsms.com/developer#status.

Sample response
2348030000000,24137cf8-eccc-469c-80af-109538857e53

Tilde (~) will be used to separate multiple destination numbers.
e.g 2348030000000,42138969-09f9-434d-a3c6-db5733fba736~2348030000011,974790b3-e598-41a8-939b-772d16860fb4
  message_uuid (optional) This serves as the idempotency unique ID for safely retrying failed or timeout requests without accidentally executing the same operation twice.

(automatically expire after 30days)
(maximum of 64 characters)

We suggest the message_uuid should be a V4 UUIDs (e.g 58c0d0f9-7dc6-4ce0-91ae-2d84c5880713), or another random string that can guarantee uniqueness to avoid collisions.

# API Example - Single Recipient
       POST https://vividsms.com/api/send/? user=demo&pass=demopass&to=2348030000000&from=Testing&msg=Testing
# API Example - Multiple Recipients
       POST https://vividsms.com/api/send/? user=demo&pass=demopass&to=2348030000000,2348030000011,2348030000022&from=Testing&msg=Testing

Checking Credit

# API Service URL For Checking Credit Balance
  URL https://vividsms.com/api/credit/
  Request Type HTTP_POST
  Spec URL encode all request

# Parameter Description
  user Account username
  pass Account password

# API Example
       POST https://vividsms.com/api/credit/?user=demo&pass=demopass

Checking Delivery Status

This endpoint allows you to check the delivery status of messages sent.

You will need to enable the parameter enable_msg_id at the time of sending the SMS via https://vividsms.com/developer#sms

# API Service URL For Checking Message Delivery Status
  URL https://vividsms.com/api/report/
  Request Type HTTP_POST
  Spec URL encode all request

# Parameter Description
  user Account username
  pass Account password
  msgid Message ID

# API Example
       POST https://vividsms.com/api/report/?user=demo&pass=demopass&msgid=24137cf8-eccc-469c-80af-109538857e53

API Response

All VividSMS Ltd APIs return a response in json format. The HTTP (RESTful) API returns one of the following HTTP status codes.

#    API Response Description
1 sent Message(s) have been sent successfully
2 error_param You have supplied incomplete parameter to the url or one of the required parameter is missing
3 error_credit Insufficient credit
3 error_billing We were unable to debit your account. Ususally a temporary error message.
4 error_gw Gateway is down, busy or not responding
5 error_user Invalid user or user has been suspended
6 error_limit Exceed maximum number limit for bulk/batch sending. The maximum limit on the API is currently 500 numbers at a single call.
# Message IDs - Applicable only if you have message ID response enabled on your account
       number,message_id Sample response is 2348030000000,4b1d777e.
Tilde (~) will be used to seperate multiple destination numbers. e.g 2348030000000,4b1d777e~2348030000011,47e63835