Scribd
Upload
23 views4 pages

HTTP API Documentation (BD SMS)

The Planet Group HTTP API documentation provides guidelines for using their Bulk SMS and 2-way messaging services, detailing methods for sending and retrieving SMS, as well as obtaining delivery reports. Key services include SendSms, GetSms, and various delivery report retrieval methods, each requiring specific parameters. Recommendations include avoiding excessive requests in a short time and using session management for efficient authentication.

Uploaded by

rahadmails
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
23 views4 pages

HTTP API Documentation (BD SMS)

The Planet Group HTTP API documentation provides guidelines for using their Bulk SMS and 2-way messaging services, detailing methods for sending and retrieving SMS, as well as obtaining delivery reports. Key services include SendSms, GetSms, and various delivery report retrieval methods, each requiring specific parameters. Recommendations include avoiding excessive requests in a short time and using session management for efficient authentication.

Uploaded by

rahadmails
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 4

Planet Group

HTTP API Documentation


Bulk SMS & 2way messaging

Common aspects

• Use GET method when you want to send SMS or retrieve information (e.g. get incoming sms, dlr etc)
• Each request takes 3 query-string parameters along with other parameters:
– userId, your user-id
– password, your password
– outputFormat (possible values: json, xml; optional. Default:json)
• userId and password parameters are optional (except in your first call|) if you maintain session.
Otherwise each request will expect these parameters for authentication.

• Before sending any request use proper url encoding to avoid request rejection [BadRequest (400)
rejection]

Services
• SendSms
• GetSms
• GetDLRSummay
• GetDLROfSingleSms
• GetDLRsOfMultipleSms
• GetDLRsOfRangedSms

Service details: SendSms()


• Url: /apex/accounts/bdsms/httpapi/sendsms
• Sends sms (single/broadcast)
• Parameters (along with the common ones):
– smsText (mandatory)
– commaSeperatedReceiverNumbers (mandatory)
– maskText (optional; string (11 char max) to use as dynamic-mask. only works if you have
dynamic masking ON.)
– ignoreMask (optional; masking is always used; provide any non-zero value to not use mask)

Example: SendSms()
• Request:
http://180.234.210.62:8181/apex/accounts/bdsms/httpapi/sendsms?userId=myuserId&password=
mypassword&smsText=Testonly&commaSeperatedReceiverNumbers=8801XXXXXXXXX&maskText=S
enderID
• Response: {"insertedSmsIds":“12345","isError":false,"message":"Success!"}
• In the response the parameter insertedSmsIds may consists of comma separated ids (in case of
broadcasting to 500+ receivers)

Planet Group
57/1, Kazi Tower, Progati Sharani, Kuril, Dhaka-1229, Bangladesh.
Regional Head Office: 3A Floor, Block 4805, CBD Perdana 2, Cyber 12, 63000 Cyberjaya, Selangor, Malaysia
Cell: +880161652638 | Web: www.planetgroupbd.com | E-mail: [email protected]
Planet Group
Service details: GetSms()
• Url: /apex/accounts/bdsms/httpapi/getsms
• Retrieves 100 inbox sms which are newer than the provided sms-id.
• Parameters (along with the common ones):
– lastReadSmsId (long-integer; the sms-id of the last sms read)
Example: GetSms()
• Request to retrieve 100 incoming sms which are newer than the last sms with Id 20240:
http://180.234.210.62:8181/apex/accounts/bdsms/httpapi/getsms?userId=yourUserId&password=y
ourPassword&lastReadSmsId=20
• Response (json):
[{"Id":20248,"Sender":"8803592000066","Time":"2015-01-21T11:40:56","Text":"Helllo"},
{"Id":20249,"Sender":"8803592000066","Time":"2015-01-21T11:41:03","Text":"d"},
{"Id":20250,"Sender":"8801710051704","Time":"2015-01-21T11:43:57","Text":"hello"}]
• Here you got 3 incoming sms which are newer than sms with Id 20240. To get next 100, you will
need to call with id 20250 (id of the last sms).

Service details: GetDLRSummay()


• Url: /apex/accounts/bdsms/httpapi/dlr/summary
• Provides operator-wise sms summary for a date range.
• Parameters (along with the common ones):
– dateFrom (mandatory; use format yyyy-mm-dd)
– dateTo (optional; use format yyyy-mm-dd)
• Using large date range may cause timeout.

Example: GetDLRSummay()
• Request to retrieve operator-wise summary from January 31, 2015 to February 28, 2015:
http://180.234.210.62:8181/apex/accounts/bdsms/httpapi/dlr/summary?userId=yourUserId&passw
ord=yourPassword&dateFrom=2015-01-31&dateTo=2015-02-28
Sample response (json):
[{"SuccesfulCount":0,"FailedCount":0,"PendingCount":4,"OperatorName":"Warid"},{"SuccesfulCount":0,"Fail
edCount":0,"PendingCount":5211,"OperatorName":"Grameenphone"},{"SuccesfulCount":0,"FailedCount":0,
"PendingCount":25,"OperatorName":"Robi"},{"SuccesfulCount":0,"FailedCount":0,"PendingCount":6,"Opera
torName":"Banglalink"},{"SuccesfulCount":0,"FailedCount":0,"PendingCount":2,"OperatorName":"Banglaph
one"}]

Service details: GetDLROfSingleSms()


• Url: /apex/accounts/bdsms/httpapi/dlr/details/single
• Provides cell-wise delivery report for a single sms (which may contain multiple receivers, in case of
broadcast).
• Parameters (along with the common ones):
– smsId (mandatory; long-integer)
– pageIndex (mandatory; int)
• Provides 100 dlrs max in one call. Use the pageIndex parameter to get next 100 and so on

Example: GetDLROfSingleSms()
• Request to retrieve the delivery report (first page) of an sms with id 20996:
http://180.234.210.62:8181/apex/accounts/bdsms/httpapi/dlr/details/single?userId=yourUserId&p
assword=yourPassword& &smsId=20996&pageIndex=0
Sample response (json):
{"TotalPages":1,"CurrentPageIndex":0,"PageSize":100,"DLRs":[{"SmsId":20996,"CellNumber":"88016100000

Planet Group
57/1, Kazi Tower, Progati Sharani, Kuril, Dhaka-1229, Bangladesh.
Regional Head Office: 3A Floor, Block 4805, CBD Perdana 2, Cyber 12, 63000 Cyberjaya, Selangor, Malaysia
Cell: +880161652638 | Web: www.planetgroupbd.com | E-mail: [email protected]
Planet Group
48","Status":1,"ReasonCode":0},{"SmsId":20996,"CellNumber":"8801610000032","Status":1,"ReasonCode":0
},{"SmsId":20996,"CellNumber":"8801710000000","Status":1,"ReasonCode":0}]}
• Here you got the delivery status of the sms with id 20996. The value of the array DLR shows that the
sms had 3 receivers (broadcast).
• Status codes are: 1(pending), 2(delivered), and 3(undelivered)

Service details: GetDLRsOfMultipleSms()


• Url: /apex/accounts/bdsms/httpapi/dlr/details/multiple
• Provides cell-wise delivery report for multiple sms items
• Parameters (along with the common ones):
– commaSeparatedSmsIds (mandatory; 10 id max)
– pageIndex (mandatory; int)
• Provides 100 dlrs max in one call. Use the pageIndex parameter to get next 100 and so on

Example: GetDLRsOfMultipleSms()
• Request to retrieve the delivery report (first page) of the sms with ids 20992,20996 and 21152:
http://180.234.210.62:8181/apex/accounts/bdsms/httpapi/dlr/details/multiple?userId=yourUserId
&password=yourPassword&commaSeparatedSmsIds=20996%2C20992%2C21152&pageIndex=0
• Sample response (json):
{"TotalPages":1,"CurrentPageIndex":0,"PageSize":100,"DLRs":[{"SmsId":20996,"CellNumber":"88016
10000048","Status":1,"ReasonCode":0},{"SmsId":20996,"CellNumber":"8801610000032","Status":1,
"ReasonCode":0},{"SmsId":20996,"CellNumber":"8801710000000","Status":1,"ReasonCode":0},{"Sm
sId":21152,"CellNumber":"8801711080781","Status":1,"ReasonCode":0}]}
• Status codes are: 1(pending), 2(delivered), and 3(undelivered)

Service details: GetDLRsOfRangedSms()


• Url: /apex/accounts/bdsms/httpapi/dlr/details/ranged
• Provides cell-wise delivery report for an sms id range.
• Parameters (along with the common ones):
– fromSmsId (mandatory; long integer)
– toSmsId (mandatory; long integer)
– pageIndex (mandatory; int)
• Provides 100 dlrs max in one call. Use the pageIndex parameter to get next 100 and so on

Example: GetDLRsOfRangedSms()
• Request to retrieve the delivery report (first page) of the sms whose ids are between 20990 and
21000:
http://180.234.210.62:8181/apex/accounts/bdsms/httpapi/dlr/details/ranged?userId=yourUserId&
password=yourPassword&fromSmsId=20990&toSmsId=21000&pageIndex=0
• Sample response (json):
{"TotalPages":1,"CurrentPageIndex":0,"PageSize":100,"DLRs":[{"SmsId":20996,"CellNumber":"88016
10000048","Status":1,"ReasonCode":0},{"SmsId":20996,"CellNumber":"8801610000032","Status":1,
"ReasonCode":0},{"SmsId":20996,"CellNumber":"8801710000000","Status":1,"ReasonCode":0},{"Sm
sId":21152,"CellNumber":"8801711080781","Status":1,"ReasonCode":0}]}
• Status codes are: 1(pending), 2(delivered), and 3(undelivered)

Problem/Recommendation

Planet Group
57/1, Kazi Tower, Progati Sharani, Kuril, Dhaka-1229, Bangladesh.
Regional Head Office: 3A Floor, Block 4805, CBD Perdana 2, Cyber 12, 63000 Cyberjaya, Selangor, Malaysia
Cell: +880161652638 | Web: www.planetgroupbd.com | E-mail: [email protected]
Planet Group
• DO NOT call inside a loop when you are trying to send same content to different users (broadcast).
Just concatenate the receiver numbers with commas; a single call will suffice.
• You will receive a forbidden status (403) with message “Server is loaded” if you send many requests
in a short time span.
• You might receive a forbidden status (403) if your ip is not registered for httpAPI.
• Use session to avoid authentication check in each call; results a faster operation. In future you will
be forced to login first (via http call).

Planet Group
57/1, Kazi Tower, Progati Sharani, Kuril, Dhaka-1229, Bangladesh.
Regional Head Office: 3A Floor, Block 4805, CBD Perdana 2, Cyber 12, 63000 Cyberjaya, Selangor, Malaysia
Cell: +880161652638 | Web: www.planetgroupbd.com | E-mail: [email protected]

You might also like