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
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
1 | HTTP/1.1 200 OK 2 | { 3 | "requestId":"12-75cfafba-8799-4f2b-8505-ece6af6abf01", 4 | "size":1, 5 | "msgIdList":["12-1407778865439+1234567890"] 6 | }
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 | }
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>
| 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. |
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 | }
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>
1 | HTTP/1.1 400 Bad Request 2 | { 3 | "responseText":"*see list below*" 4 | }
| 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. |
| 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. |
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.
1 | curl https://username:password@rest.tyntec.com/sms/v1/outbound/requests/status/12-75cfafba-8799-4f2b-8505-ece6af6abf011 | { 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. |
| 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. |
| 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. |
