SMSPORTAL outbound API

Used to deliver SMS messages

Sending message

URL : https://api.smsportal.ch/sendsms

Method : POST GET

Auth required : YES

Data structure for POST (JSON object)

{
     "msgId"    : "UUID (optional)",
     "auth"     : {
                    "username": "string",
                    "password": "string"
                  },
     "sender"   : "string",
     "receiver" : "string",
     "mclass"   : "integer (optional)",
     "coding"   : "integer (optional)",
     "text"     : "string",
     "dlrMask"  : "integer",
     "dlrUrl"   : "string (optional)"
}

Parameters description

Parameter	Description	Valid format	Required
`msgId`	Message id to keep track of dlr response, when missing, system will generate one and send with the response. ⚠ When provided must be unique	UUID	No
`auth`	Authorization object with `username` and `password` strings used to identify user	Json object	Yes
`sender`	Sender of the message, if sender is alphanumeric it’s length is limited to 11 chars.	String	Yes
`receiver`	Receiver of the message, numbers can be prefixed with `+`	String	Yes
`mclass`	Sets the Message Class in DCS field. Accepts values between 0 and 3. A value of 0 sends the message directly to display, 1 sends to mobile, 2 to SIM and 3 to SIM toolkit. When missing defaults to 1.	Integer	No
`coding`	Sets the coding scheme bits in DCS field. Accepts values 0 to 2, for 7bit, 8bit or UCS-2. When missing defaults to 0 (GSM7)	Integer	No
`text`	Content of the message, accepts up to 10 concatenated messages	String	Yes
`dlrMask`	Request for delivery reports with the state of the sent message. The value is a bit mask composed of: 1: Delivered to phone, 2: Non-Delivered to Phone, 4: Queued on SMSC, 8: Delivered to SMSC, 16: Non-Delivered to SMSC	Integer	Yes
`dlrUrl`	This is the url to be called (GET request) with dlr report	String	Yes

POST Data example

{
     "msgId"    : "4734f81a-7d63-478f-a0c7-f4a2dd595a71",    
     "auth"     : {
                    "username": "user",
                    "password": "pass"
                  },
     "sender"   : "Test",
     "receiver" : "41000000001",
     "mclass"   :  1,
     "coding"   :  0,
     "text"     : "This is a test message",
     "dlrMask"  : "19",
     "dlrUrl"   : "http://customer.biz/dlr-url"
}

GET Call example

https://api.smsportal.ch/sendsms?username=user&password=pass&sender=Test&receiver=41000000001&text=This%20is%20a%20test%20message&dlrUrl=http%3A%2F%2Fcustomer.biz%2Fdlr-url&dlrMask=19

⚠ Get calls must be percent encoded
https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding

Success Response

Code : 202 Accepted

Content example

{ 
  "msgId": "4734f81a-7d63-478f-a0c7-f4a2dd595a71"
}

Error Response

Code : 403 Forbidden

Condition : If ‘username’ and ‘password’ combination is wrong.

Code : 400 Bad request

Condition : If object structure is invalid

Content example

{ 
  "reason": "JSON parse error: Unexpected character ('}' "
}

DLR Reports

DLR reports are deliver to the given dlrUrl parameter as a GET call with parameters:

msgId the id our API reply with when accepting message for processing, this can be given on API call or generated by our system.

report this is a structure of a Delivery Receipt Format specified in SMPP protocol, see description below.

Example call

http://customer.biz/dlr-url?msgId=4734f81a-7d63-478f-a0c7-f4a2dd595a71&report=id%3A54ab9a3c-d97b-49fd-9b1b-1a03dcc9f463+sub%3A001+dlvrd%3A000+submit+date%3A200430092654+done+date%3A200430092654+stat%3AACCEPTD+err%3A000+text%3A'

data is URL-Encoded

Delivery Receipt Format (as described in SMPP protocol specification v3.4)

The format for this Delivery Receipt
message is SMSC vendor specific but following is a typical example of Delivery Receipt report.

id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:E Text:......

The fields of the above delivery receipt example are explained in the following
table:

Field	Description
`id`	The message ID allocated to the message by the SMSC when originally submitted.
`sub`	Number of short messages originally submitted. This is only relevant when the original message was submitted to a distribution list.The value is padded with leading zeros if necessary.
`dlvrd`	Number of short messages delivered. This is only relevant where the original message was submitted to a distribution list.The value is padded with leading zeros if necessary.
`submit date`	The time and date at which the short message was submitted. In the case of a message which has been replaced, this is the date that the original message was replaced.The format is as follows: YYMMDDhhmm where: YY = last two digits of the year (00-99) MM = month (01-12) DD = day (01-31) hh = hour (00-23) mm = minute (00-59
`done date`	The time and date at which the short message reached it’s final state. The format is the same as for the submit date.
`stat`	The final status of the message. For settings for this field see Table B-2.
`err`	Where appropriate this may hold a Network specific error code or an SMSC error code for the attempted delivery of the message. These errors are Network or SMSC specific and are not included here.
`text`	The first 20 characters of the short message.

Example Delivery Receipt message states:

Message State	Final Message States	Description
DELIVERED	`DELIVRD`	Message is delivered to destination
EXPIRED	`EXPIRED`	Message validity period has expired.
DELETED	`DELETED`	Message has been deleted.
UNDELIVERABLE	`UNDELIV`	Message is undeliverable
ACCEPTED	`ACCEPTD`	Message is in accepted state (i.e. has been manually read on behalf of the subscriber by customer service)
UNKNOWN	`UNKNOWN`	Message is in invalid state
REJECTED	`REJECTD`	Message is in a rejected state