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

Receiving (2-Way) SMS

To use this feature, you will need to purchase an inbound (MO) number. Then provide us with your URL for the inbound (MO) messages. All incoming messages from your shortcode would be routed to this URL.

# Inbound SMS Service URL
  URL http://ClientApplicationURL.com
  Request Type HTTP_POST or HTTP_GET
  Spec All URL requests will be ‘URLencoded’

# Parameter Description
  sender Mobile number of originating SMS
  message Full message content
  datetime Time is sent in Epochtime format

# API Example
       POST or GET http://ClientApplicationURL.com/?sender=234819*******&message=Hello&datetime=1334739315

Number Lookup

# API Service URL For Number Lookup (NG only)
  URL https://vividsms.com/api/lookup/
  Request Type HTTP_POST
  Spec URL encode all request

# Parameter Description
  user Account username
  pass Account password
  msisdn Mobile number (must be in international format e.g. 234819*******)

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

USSD Inbound (MO)

When the mobile user dials your USSD code, e.g *4441#, the USSD Gateway will automatically invoke your URL and pass all the pre-defined parameters. You are required to provide your application URL for the USSD inbound (MO) messages.

# API Service URL For USSD Inbound (MO) (NG only)
  URL https://ClientApplicationURL.com
  Request Type HTTP_POST or HTTP_GET
  Spec All URL requests will be 'URLencoded'

# Parameter Description
  session_msisdn Mobile number (must be in international format e.g. 234819*******)
  session_operation USSD Operation Category
begin: New USSD session with the USSDC
continue: To continue a USSD session with the USSDC for the specified session_id
end: Used to indicate the end of a USSD session
abort: Used to indicates that a USSD session ends abnormally.
  session_msg USSD message content (must <= 160chars)
  session_id A unique identifier for a menu interaction. You will indicate this in your response to the user so as to maintain the same menu communication.
  session_from Originating USSD code
  session_type 1: Require input or reply from the user
2: Notify user without any response required.
3: When responding to a request from msisdn.
4: Notify user and end interaction.
  session_mno Originating mobile network.
MTN, 9MOBILE, AIRTEL, GLO

# API Example
       POST or GET https://ClientApplicationURL.com/? session_operation=begin&session_msisdn=2348030000000&session_from=*4441# &session_msg=*4441#&session_type=1&session_id=873729&session_mno=MTN



USSD Push (MT)

# API Service URL For USSD Push (MT) (NG only)
  URL https://vividsms.com/api/ussd/push/
  Request Type HTTP_POST or HTTP_GET
  Spec URL encode all request

# Parameter Description
  user Account username
  pass Account password
  session_from Originating USSD code
  session_msisdn Mobile number (must be in international format e.g. 234819*******)
  session_msg USSD message content (must <= 160chars)
  session_type 1: Require input or reply from the user
2: Notify user without any response required.

# API Example
       POST or GET https://vividsms.com/api/ussd/push/? user=demo&pass=demopass&session_msisdn=2348030000000&session_from=1234 &session_msg=Testing&session_type=2