SMS API | Send SMS | Connection Steps

Follow the steps below to learn more about the Connection Steps for our Send SMS product.

If any questions arise while reading, you can contact us under support@tyntec.com. 

Connection Steps

Step 1: Request "Send an SMS"

 

To send a new outgoing SMS, make a POST request to the requests resource. The following code blocks give a basic example of how to send an SMS:

 1 | curl
 2 | -u username:password
 3 | -X POST
 4 | -H "Content-Type: application/json"
 5 | -d '{
 6 |       "from":"MyCompany",
 7 |       "to":"+491622943176",
 8 |       "message":"This is an example."
 9 |      }'
10 | https://rest.tyntec.com/sms/v1/outbound/requests

 

For time-sensitive one-time passwords, we suggest using the following basic example:

 1 | curl
 2 | -u username:password
 3 | -X POST
 4 | -H "Content-Type: application/json"
 5 | -d '{
 6 |       "from":"MyCompany",
 7 |       "to":"+491622943176",
 8 |       "message":"This is an example.",
 9 |       "validityPeriod":"00:01"
10 |      }'
11 | https://rest.tyntec.com/sms/v1/outbound/requests

 

Response to basic example for Sending SMS (JSON):

1 | HTTP/1.1 200 OK
2 | {
3 |  "requestId":"12-75cfafba-8799-4f2b-8505-ece6af6abf01",
4 |  "size":1,
5 |  "msgIdList":["12-1407778865439+1234567890"]
6 | }

 

The following code blocks demonstrate the expected and accepted message format (the parameters are filled with examples):

Sending SMS (JSON)

 1 | "from":"+4915112345678",
 2 |  "to":"+4917912345678",
 3 | (*choose one of the following*)  
 4 |  "message":"This is an example.",
 5 |  "unicode":,
 6 |  "wappush":
 7 |  {
 8 |   "title":,
 9 |   "url":
10 |   },
11 | (*optional*)
12 |  "userContext":"testmessage1",
13 |  "sendDateTime":"2014-12-24T18:30:00+01:00",
14 |  "validityPeriod":"03:00",
15 |  "callbackUrl":"https://tyntec.com/",
16 |  "flash":true
17 | }

 

Sending SMS (XML)

 1 | <sms>
 2 |  <from>+4915112345678</from>
 3 |  <to>+4917912345678</to>
 4 | (*choose one of the following*)
 5 |  <message>This is an example.</message>
 6 |  <unicode></unicode>
 7 |  <wappush>
 8 | <title></title>
 9 | <url></url>
10 |  </wappush>
11 | (*optional*)
12 |  <usercontext>testmessage1</usercontext>
13 |  <senddatetime>2014-12-24T18:30:00+01:00</senddatetime>
14 |  <validityperiod>03:00</validityperiod>
15 |  <callbackurl>https://tyntec.com/
16 |  <flash>true</flash>
17 | </callbackurl></sms>

 

In this request there are a number of parameters that need to be defined, others are optional:

Parameter Optional/Mandatory Possible Values Description
from Mandatory Any international phone number OR alphanumeric sender ID (1 – 11 characters)* This parameter gives the identification of the sending party, which can either be the phone number in international format or an alphanumeric identifier with up to 11 characters*. *Some destination networks impose restrictions on the sender ID format. Please check the coverage list and/or contact your account manager for more information.
to Mandatory Any international phone number This parameter represents the receiving party’s phone number in international format
(*choose one of the following*) Mandatory Only one of the following parameters has to be set This API version supports sending messages either as plain text SMS (with GSM-7 encoding – http://en.wikipedia.org/wiki/GSM_03.38), as Unicode SMS (with USC-2 encoding), or as WAP-Push SMS (with UTF-8 encoding). The expected encoding given in the HTTPS POST request for all message types is UTF-8. tyntec automatically translates your UTF-8 string into the respective encoding. The maximum overall length for accepted messages is 3000 UTF-8 characters (counted before the encoding). The maximum length of a single SMS is limited to 160 (message)/70 (Unicode) / 130 (wappush) characters depending on the final encoding (counted after encoding). tyntec automatically splits the sent message into concatenated messages if the message exceeds the given limits. These concatenated messages are unified by the handset once again and are displayed as one message (if supported by the handset). NOTE: tyntec will charge for each part of the concatenated message as an individual message.
message Any UTF-8 encoded string The message will be sent with characters encoded in the GSM standard alphabet GSM-7. Max. length is 160 characters per single message and 153 characters per concatenated message. Characters that are not supported by the GSM-7 alphabet are replaced by “*”.
unicode Any UTF-8 encoded string The message will be sent with characters encoded in the GSM Unicode alphabet USC-2. Max. length is 70 characters per single message and 66 characters per concatenated message.
wappush - title Any UTF-8 encoded string The message part of the WAP-Push message in the UTF-8 encoding.
Wappush - url Any pre-formatted URL This URL will be interpreted directly and displayed by the handset as a web link (if supported by the handset). Max. length of a WAP-Push (incl. title and URL) is 130 characters per single message and 123 characters per concatenated message.
userContext Optional Any UTF-8 encoded string This parameter allows for personalized identifiers or context. This field will not be modified by tyntec. The message notification will return this identifier in addition to the request ID and message ID.
sendDateTime Optional Any future date in the format “yyyy-MM-ddT-HH:mm:ss+HH:mm” (according to ISO 8601) tyntec will submit the message at this given date. Otherwise tyntec will submit your message immediately. Default time zone is UTC.
validityPeriod Optional Any time in the format “hh:mm” tyntec will attempt to resend the message for the time specified (validityPeriod can be set from 00:01 to 48:00). The default value is 48:00.
callbackUrl Optional Any valid URL This parameter allows for overriding of the default call-back URL for this message. If it is not specified, the default call-back URL will be used for push message notifications. If no call-back URL is provided, tyntec will not enable push message notifications. No matter, the status of the message and the message notification will be available via the HTTPS GET “Query the status of an SMS”.
flash Optional true/false This parameter specifies that the sent message is sent as a flash-SMS, i.e., the message will only be displayed one time and will not be stored on the handset (if supported by the handset). The default value is false.

 

 

Step 2: Response to request “Send an SMS”

tyntec will immediately respond to a HTTPS POST request to “Send an SMS”. The response will contain the request ID, the size of your message and list of respective message IDs. 

In the case there are delivery issues, the response will contain possible delivery issues following an immediate check for inconsistencies (e.g., case sensitivity, wrong parameter, too many characters, no receiver defined, etc.). The HTTP status code returned will be accordingly.

 

  • Successful Request Response (JSON)
1 | HTTP/1.1 200 OK
2 | {
3 |  "requestId":"12-75cfafba-8799-4f2b-8505-ece6af6abf01",
4 |  "size":"2",
5 |  "msgIdList":["12-1407778865439+1234567890","12-1407778865439+1234567891"]
6 | }

 

Successful Request Response (XML)

1 | HTTP/1.1 200 OK
2 | <restmessageresponse>
3 |  <requestid>12-75cfafba-8799-4f2b-8505-ece6af6abf01<requestid>
4 |  <size>2<size>
5 |  <msgidlist>
6 |   <msgid>12-1407778865439+1234567890</msgid>
7 |   <msgid>12-1407778865439+1234567891</msgid>
8 |  <msgidlist>
9 | </msgidlist></msgidlist></size></size></requestid></requestid></restmessageresponse>

 

Unsuccessful Request Response (JSON)

1 | HTTP/1.1 400 Bad Request
2 | {
3 |  "responseText":"*see list below*"
4 | }

HTTP status codes

HTTP Code Message Description
200 OK *see code examples “Un/Successful Request Response”* OR *see code examples “Message Notification”* The HTTPS request was accepted. The posted message passed an initial consistency check and tyntec will reply with the respective request ID, size and message ID. OR The requested message notification can be retrieved and is returned.
400 Bad Request *see validation error message list below The HTTPS request failed to pass the validation, i.e., one or more of the required parameters of the request are empty/mission/contradictory/invalid. The given message provides more information as to why the validation failed.
403 Forbidden Username/password wrong or missing. The provided credentials are not authorized.
404 Not Found The requested message notification cannot be retrieved. The request URI is either non-existent or the respective authentication is invalid.
405 Method Not Allowed Invalid request method. The request contains an invalid HTTP method (POST/GET).
406 Not Acceptable The content-type is not supported. Allowed values are “application/xml” and “application/json”. The request is neither JSON nor XML format, or the header reads “Content-Type”.
415 Unsupported Media Type The media type is not supported. Allowed media-types are “application/xml” and “application/json”. The request is neither JSON nor XML format, or the HTTP header reads “Accept”.
500 Internal Server Error Please retry. If error persists, please contact customer support. Unexpected error.

Validation error message may be one reason or a combination of the below:

Message Sent Description
Invalid authentication Send/Query actions Invalid username and/or password, or wrong authentication token.
Request ID is missing Query action Please specify the request-ID for which the message status should be retrieved.
Sender is missing Send action The mandatory parameter “from” is not specified.
Receiver is missing Send action The mandatory parameter “to” is not specified.
Receiver number is not numeric Send action The mandatory parameter “to” is malformed. It has to be an international phone number.
Message is empty Send action It is not allowed to send an empty message.
More than one message content parameter is set Send action Please use EITHER “message”, “unicode” or “wappush” to send a message.
Message exceeds maximum character length of 3000 Send action Message text exceeds the limit of 3000 symbols.
The respond-back URL is invalid Send action Please format the URL according to http(s)://host(:port).
One or more mandatory parameters are missing Send action The request is missing mandatory parameters.
Your message is rejected because it has over-length Send action Your account settings block the sending of over-length message.
The requested URI was not found Query action The requested URI is either non-existent or the respective authentication is invalid.
Unexpected error, please retry. If error persists, please contact your customer support Query action/Send action Something unexpected occurred during the processing of the request.
The parameter ${invalidparameter} is invalid Send action The request contains at least one invalid parameter. ${invalidparameter} will state which parameter.

 

 

Step 3: Query the status of a sent SMS / message notification

The tyntec server will respond to your query with the current message notification. tyntec stores message notifications for three months. tyntec will also POST these message notifications in case there is a call-back URL specified.

 

Query the status of a request / Message Notification (JSON)

1 | curl https://username:password@rest.tyntec.com/sms/v1/outbound/requests/status/12-75cfafba-8799-4f2b-8505-ece6af6abf01

 

Message Notification (JSON)

 1 | {
 2 |  
 3 |  "requestId":"12-75cfafba-8799-4f2b-8505-ece6af6abf01",
 4 |  "overallState":"DELIVERED",
 5 |  "size":"1",
 6 |  "from":"+4915112345678",
 7 |  "to":"+4917912345678",
 8 |  "userContext":"testmessage1",
 9 |  "mccmnc":"26207",
10 |  "ttid":"16",
11 |  "overallPrice":"0.55",
12 |  "contentList":
13 |   [{
14 |    "deliveryState":"DELIVERED",
15 |    "statusText":"This is a test.",
16 |    "msgId":"12-1407778865439+1234567890",
17 |    "price":"0.55",
18 |    "currency":"EUR",
19 |    "priceEffective":"2014-12-24T18:30:00+01:00",
20 |    "sentDate":"2014-05-13T17:41:06+01:00",
21 |    "doneDate":"2014-05-13T17:41:07+01:00",  
22 |    "errorCode":"001"
23 |   }]
24 | }
25 |
26 |   Message Notification (XML)
27 | <messagenotification>
28 |  <requestid>12-75cfafba-8799-4f2b-8505-ece6af6abf01</requestid>
29 |  <overallstate>DELIVERED</overallstate>
30 |  <size>1</size>
31 |  <from>+4915112345678</from>
32 |  <to>+4917912345678</to>
33 |  <usercontext>testmessage1</usercontext>
34 |  <mccmnc>26207</mccmnc>
35 |  <ttid>16</ttid>
36 |  <overallprice>0.55</overallprice>
37 |  <contentlist>
38 |   <messagenotificationcontent>
39 |    <deliverystate>DELIVERED</deliverystate>
40 |    <statustext>This is a test.</statustext>
41 |    <msgid>12-1407778865439+1234567890</msgid>
42 |    <price>0.55<price>
43 |    <currency>EUR<currency>
44 |    <priceeffective>2014-12-24T18:30:00+01:00</priceeffective>
45 |    <sentdate>2014-05-13T17:41:06+01:00</sentdate>
46 |    <donedate>2014-05-13T17:41:07+01:00</donedate> 
47 |    <errorcode>001</errorcode>
48 |   </currency></currency></price></price></messagenotificationcontent>
49 |  </contentlist>
50 | </messagenotification>
Parameter Description
requestId The unique identifier provided for each request.
overallState Aggregated status from all respective delivery status.
size The amount of respective concatenated SMS parts.
from This parameter gives the identification of the sending party, which can either be the phone number in international format or an alphanumeric identifier with up to 11 characters*.
to *Some destination networks impose restrictions on the sender ID format. Please check the coverage list and/or contact your account manager for more information. This parameter represents the receiving party’s phone number in international format.
userContext The custom message context provided by the customer.
mccmnc A representative IMSI prefix of the target network. The respective mapping can be found at http://mcc-mnc.com/, for example.
ttid The respective tyntec ID of the target network.
overallPrice Aggregated price from all respective message parts.
MessageNotificationContent The actual message notifications for respective parts.
message Separator for each part.
deliveryState The delivery status of this specific part. Possible values are given in a following table.
statusText The first 20 characters of the sent message.
msgId The unique identifier provided for each message.
price The price for sending the respective message part.
currency The currency in which the price is given; corresponding to the currency of the invoice.
priceEffective The date when the “price” became active.
sentDate The time stamp when the message was sent out by tyntec for delivery.
doneDate The time stamp when the message was successfully delivered.
errorCode The reason for an unsuccessful delivery attempt. Possible values are given in a following table.

 

Possible values for “deliveryStatus”:

Delivery Status Description
DELIVERED Message was successfully delivered.
UNDELIVERABLE Message cannot be delivered. See error codes for more details.
EXPIRED Message expired, i.e., the message could not be delivered within the specified time span. See error codes for more details.
REJECTED Message rejected, i.e., the message could not be accepted by our platform. See error codes for more details.
BUFFERED Message could not be delivered. tyntec is in the process of resending. Please wait for one of the above final statuses.

 

Possible values for “errorCode” without GSM-error-code account-feature active (default):

Code Description
001 Message was successfully delivered.
002 Message cannot be delivered.
006 Message expired, i.e., the message could not be delivered within the specified time span.
010 Message rejected, i.e., the message could not be delivered by our platform.
011 Message could not be delivered. tyntec is in the process of resending. Please wait for one of the above final statuses.
013 Same as 010.
020 Same as 010.