Endpoints

We'll have two endpoints:

REST (GET/POST): https://mc5.smartmessagingservices.net/services/rest/message/sendSingle2?username=[]&password=[]&text=[]&replyTo=[]&recipient=[]&sender=[]&rotation=[]&encoding=[]
SOAP: https://mc5.smartmessagingservices.net/services/ws/message?wsdl (method: sendSingle2)

REST endpoint

parameter

meaning

example

username

username of user who wants to send the message (Mandatory)

scott

password

password to authenticate in MC5 system (Mandatory)

scottish

text

SMS message text (escaped string) (Mandatory)

Hello+world

replyTo

Path for reply message to forwarded back to your system/s. Note that this process only works where one of our reply source address pool is used to set the source address of your message. So for this to work the sender parameter must either be set to empty string of not included in the call.

For dedicated numbers a push MO address must be set against either your customer or user record for the MO message to pushed to you.

Push Reply Options

log: This is the default value if replyTo parameter is not specified - MO messages are stored in the Inbox for collection via Query and can be view in the message log report. You can also set this as your value.

Push to URI

Url push in the replyTo string will support templating. Because it will be a url inside a url, some characters need to be url-encoded. A sample API call might look like this:
https://mc5.smartmessagingservices.net/services/rest/message/sendSingle2?username=[]&text=[](...)&replyTo=http://requestb.in/vw66muvw?from%3D%7B%7Bfrom%7D%7D%26text%3D%7B%7Btext%7D%7D
which will set the replyTo to the following url: http://requestb.in/vw66muvw?from={{from}}&text={{text}}

encoded values

Character	Value
&	%26
=	%3D
{	%7B
}	%7D

Online url encoder: http://meyerweb.com/eric/tools/dencoder/

NOTE if sending via SOAP - do not url encode the replyTo value. this will result in a error as it is not decodedon the server. put you replyTo string inside CDATA tag eg

<![CDATA[http://requestb.in/vw66muvw?from={{from}}&text={{text}}]]>

Push to Email

Email push in the replyTo string will be as simple as it today, e.g. replyTo=mailto:magda.stozek@softwaremill.com. Email subject will be "Reply from 123456", and email body will contain the message text. So if clients need specific push format, they need to set it on the user level.

see page /wiki/spaces/MC5OH/pages/42195 for details on avaliable insert parameters for push to uri

List of supported replacement tokens:

- MOMessageId
- MTMessageId (for replies only)
- from
- to
- text
- timestamp
- chargedAmount
- numberOfParts

recipient

phone number we want to send SMS to (Mandatory)

61421112322 - Can use local prefix for Australia or New Zealand - otherwise you must you international format without the + sign.

sender

sender phone number or name (maximum 11 characters) (Optional)

eg John - if phone is used the number must be in international formation without the + sign. Do not include the parameter if you are using reply messaging by defining a replyTo parameter. While you will not get a error, the system will send the message with this value as your message source address and the reply messaging feature will not work. Setting the sender to empty string has the same affect as not adding the parameter.

rotation

Rotation algorithm for MT messages. Valid values: CONVERSATION, MAX_ROTATION (case insensitive).
Parameter is (Optional). When not provided, default value set for the Customer is used.

conversation or max_rotation - contact Intelli Messaging Prior to defining this parameter to get a current list of country destinations that support these number rotation methods. The conversation method attempts to keep the messages source address the same when a sending more than one message to a recipient. The max_rotation method attempts to always change the source address when sending to the same recipient. The max_rotation method is used for reply to unique message functionality where conversation rotation method is used to maintain message conversations.

If specified it must contain a valid value.

encoding

(Optional), allows to user to set the encoding which is really either GSM or UTF-16. When not set GSM is used by default. GSM is a limited character containing about 182 characters. It includes most characters on US keyboard for Windows. UTF-16 is a full character set including all known characters world wide. eg Chinese Characters.

NOTE: this param should indicate the text payload as you wish it to be encoded into the GSM Network. It is not not a setting to indicate the encoding over Http. Encoding in your http packet should be utf8.

https://en.wikipedia.org/wiki/GSM_03.38

GSM encoded SMS messages can contain up to 140 characters and UTF16 encoding can only contain 70 characters per message. Note that GSM extension characters take up the equivalent of 2 normal characters in the character count of 140.

accepted values are:

gsm
iso-8859-1
ucs-2

additional values mapped to ucs-2:

ucs2
utf16
utf-16

The parameter value is case insensitive

If specified it must contain a valid value.

scheduleDeliveryTime

(optional) Specify the absolute time for when the message should be delivered.

Accepted format: standard epoch timestamp - seconds since 00:00:00 January 1970 UTC.

e.g. validUntil 1545089663 = 12/17/2018 @ 11:34pm (UTC).

If specified it must contain a valid value.

validUntil

(optional) Specify how long the message should be valid for before being removed from delivery.

Accepted format: standard epoch timestamp - seconds since 00:00:00 January 1970 UTC.

e.g. validUntil 1545089663 = 12/17/2018 @ 11:34pm (UTC)

If the supplied value in the request is greater than the system maximum allowed value then the system maximum will be used.

If no valid is supplied or the value is invalid then the max validity will be used.

The system maximum value is 3 days.

If specified it must contain a valid value.

Server response looks like this (JSON):

{"documentId":"508fb3bfe4b0a193c539f559","recipient":"33333333","messageStatus":10}

documentId is message ID unique in MC5 system, status 10 means message was successfully submitted to the system. Other statuses are listed in Message Status Query and Status Codes.

SOAP endpoint

Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.server.submission.mc5.smspl.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:sendSingle2>
         <username>scott</username>
         <password>tiger</password>
         <recipient>48651333444</recipient>
         <replyTo></replyTo>
         <sender>johnny</sender>
         <text>hello</text>
         <rotation>max_rotation</rotation>
         <encoding>utf-16</encoding>
		 <scheduleDeliveryTime></scheduleDeliveryTime>
		 <validUntil>1545089187</validUntil>
      </ws:sendSingle2>
   </soapenv:Body>
</soapenv:Envelope>

Parameters are the same as in REST request. You don't need to escape special characters in text, one exception is "<" sign. It's necessary to write it as <

You need to provide all parameters and leave either replyTo or sender empty. Encoding can be also left empty to use default one.

Server response is similar to the one from REST endpoint:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:sendSingle2Response xmlns:ns1="http://ws.server.submission.mc5.smspl.com/">
         <return>
            <recipient>48651333444</recipient>
            <messageStatus>10</messageStatus>
            <documentId>508fb776e4b0a193c539f560</documentId>
         </return>
      </ns1:sendSingle2Response>
   </soap:Body>
</soap:Envelope>

Browser not supported