Documentation SMSC- API

www.i-digital-m.com

SMS Service SMSC- Interface Description v. 3.9 Prepared by

interactive digital media GmbH Kronsforder Allee 8 23560 Lbeck Germany Tel: +49 451 20 93 203 Fax: +49 451 20 93 204

Office Timmendorf interactive digital media GmbH Strandstrasse 100 a 23669 Timmendorfer Strand Germany Tel: +49 4503 70 22 977 Fax: +49 4503 70 22 978
www.interactive-digital-media.com

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

1/13

Documentation SMSC- API

www.i-digital-m.com

Notice of Disclaimer

IDM has used every precaution possible during the preparation of this document; however IDM does not assume any responsibility for errors, omissions or for damages resulting from the use of the information provided herein. Product or corporate names may be trademarks or registered trademarks of IDM or other companies and used for the purpose of its explanation and evaluation, without intent to infringe.

Copyright 2011 by interactive digital media GmbH. All Rights Reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system or translated into any language in any form by any means without the written permission of interactive digital media.

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

2/13

Documentation SMSC- API

www.i-digital-m.com

Table of Contents
1 SMS - HTTP-API INTERFACE __________________________________________ 4 1.1 Regular Message Sending _________________________________________ 4 1.2 Delayed Message Sending _________________________________________ 4 1.3 Unicode Message Sending _________________________________________ 5 1.4 WAP Push Message Sending ______________________________________ 6 1.5 SMS Message Submission Status Codes __________________________ 6 1.6 SMS credit check _________________________________________________ 7 1.7 SSL encryption (enhanced security)________________________________ 7 Parameter Information: _______________________________________________ 7 2.1 Sender ___________________________________________________________ 7 2.2 recipients ________________________________________________________ 8 2.3 Message Content _________________________________________________ 8 2.4 Encoding__________________________________________________________ 9 Sample Calls__________________________________________________________ 9 Message Tracking / Status Updates: _________________________________ 11 Additional Support ___________________________________________________ 13

3 4 5

Please note that depending on your account type some features and or functions may not be available (e.g. specified sender id on Bulk or Fixed ID routes)! You need to have a separate service agreement from IDM prior to using the SMSC gateway.

ATTENTION:

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

3/13

Documentation SMSC- API

www.i-digital-m.com

1 SMS - HTTP-API INTERFACE

There are TWO main operations that you will be using:
message sending, and message tracking.

1.1 Regular Message Sending

To send a Message you need to make a call to the following URL:
http://smsc.i-digital-m.com/smsgw/sendsms.php?user=......&password=......&sender= 4915112751276&recipients=491626825631&message=Testnachricht+%E4+%F6+ %FC+%C4+%DC+%DF+%3F+%80+%24+%25+%A7+%26+%7B+%7D+%5B+...&dlr =1 The expected input parameters for this request type are the following: 1. user up to 8 characters, provided for you by IDM (form input name is user) 2. password up to 8 characters, provided for you by IDM (form input name is password) 3. sender The Sender ID of the message. This will appear to the recipient as the originator of the SMS. 4. recipients The recipient of the message, hence the contact you want to send the information to. 5. message The content of the SMS message. Please note that spaces, carriage return etc. will count against the amount of 160 characters for messages. Allowed characters are standard and extended GSM Alphabet (GSM 03.38). 6. dlr The delivery receipt request. If you want to receive delivery confirmation on your SMS you will have to set the parameter to =1. If you do not need delivery receipts, you can set the parameter to =0 OR not submit the parameter. If exceeding 160 characters the system will automatically split the SMS text into segments of 153 characters.

1.2 Delayed Message Sending

To send a time-delayed message you need to make a call to the following URL:
http://smsc.i-digital-m.com/smsgw/sendsms_timeshift.php?user=....&password=.... &recipients=.&sender=.&msg=TIMESHIFT%20DELIVERY%20TEST&delivery_date=2009 -06-04T11:40:00 The expected input parameters for this request type are the following: 1. user up to 8 characters, provided for you by IDM (form input name is user) 2. password up to 8 characters, provided for you by IDM (form input name is password)

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

4/13

Documentation SMSC- API

www.i-digital-m.com

3. recipients The recipient of the message, hence the contact you want to send the information to. 4. sender The Sender ID of the message. This will appear to the recipient as the originator of the SMS. 5. msg The content of the SMS message. Please note that spaces, carriage return etc. will count against the amount of 160 characters for messages. Allowed characters are standard and extended GSM Alphabet (GSM 03.38). 6. delivery_date The delivery date is mandatory formatted as YYYY-MMDDTHH:MM:SS. ATTENTION: The character T is the real letter T. It is also possible to replace the T with one space character. The timeshift function is assuming that you submit the delivery date according to GMT+1 / UTC+1 timezone

1.3

Unicode Message Sending

To send a UNICODE Message you need to make a call to the following URL:
http://smsc.i-digital-m.com/smsgw/sendunicode.php?user=.....&password=......&sender= ...&recipients=491626825631&message=%u062A%u0639%u0642%u062F%20%u06 44%u062C%u0646%u0629%20%u0634%u0643%u0644%u0647%u0627%20%u062 7%u0644%u0627%u0626%u062A%u0644%u0627%u0641%20%u0627%u0644%u06 45%u0648%u062D%u062F%20%u0627%u0644%u064A%u0648%u0645%20%u064 5%u0641%u0627%u0648%u0636%u0627%u062A%20%u0645%u0639%20%u062C %u0628%u0647%u0629%20%u0627%u0644%u062A%u0648%u0627%u0641%u064 2&dlr=1 The expected input parameters for this request type are the following: 1. user up to 8 characters, provided for you by IDM (form input name is user) 2. password up to 8 characters, provided for you by IDM (form input name is password) 3. sender The Sender ID of the message. This will appear to the recipient as the originator of the SMS. 4. recipients The recipient of the message, hence the contact you want to send the information to. 5. message The content of the SMS message. Please note that spaces, carriage return etc. will count against the amount of 160 characters for messages. Allowed characters are standard and extended GSM Alphabet (GSM 03.38). 6. dlr The delivery receipt request. If you want to receive delivery confirmation on your SMS you will have to set the parameter to =1. If you co not need the delivery receipts then you can set the parameter to =0 OR not submit the parameter.

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

5/13

Documentation SMSC- API

www.i-digital-m.com

1.4

WAP Push Message Sending

To send a WAP Push Message you need to make a call to the following URL:
http://smsc.i-digital-m.com/smsgw/sendwap.php?user=......&password=......&sender=...&recipients=491626825631&type=...&name=....&url=....... The expected input parameters for this request type are the following: 1. user up to 8 characters, provided for you by IDM (form input name is user) 2. password up to 8 characters, provided for you by IDM (form input name is password) 3. sender The Sender ID of the message. This will appear to the recipient as the originator of the SMS. 4. recipients The recipient of the message, hence the contact you want to send the information to. 5. type The type of Wap Push message you intend to send. Allowed values = 1 (OTA Bookmark!) (meaning &type=1 is the only supported value at present. 6. name The name the bookmark should have. This will be shown as the descriptor of the bookmark on the recpipients phone. (similar to the name you assign to a bookmark in your PC internet browser) 7. url The url the bookmark should point to. (this has to be a full domain name, like any PC browser bookmark. E.g. http://www.i-digital-m.com )

1.5

SMS Message Submission Status Codes

Upon delivery of the SMS to the V-SMSC Gateway the system will return the following status codes:
______________________________________ 491626825631: +OK 59bba754a ______________________________________

Where: 491626825631 is the recipient of the SMS Message +Ok is the status of the message 59bba754a is the SMS Message id for the SMS submitted
Status Information will ONLY be submitted if you have provided a Status-push URL to IDM and DLR are available on the desired route.

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

6/13

Documentation SMSC- API

www.i-digital-m.com

Alternatively if you are having incorrect information the system will return any of the following status codes: ERROR ERROR ERROR ERROR ERROR ERROR 502 503 504 505 506 507 MISSING USER MISSING PASSWORD MISSING SENDER MISSING RECIPIENT WRONG RECIPIENT FORMAT MISSING MESSAGE

In case of incorrect User/ Password submission the system will return a blank page.

1.6

SMS credit check

If you have an prepaid SMS account, you can query the SMS credit balance of our system via a simple URL call.
In order to get your current balance, you need to make a call to: http://smsc.i-digital-m.com/clients/credits.php?username=........ &password=...... The system will then return your current amount of SMS credits. (e.g. 123) Note: if you are on postpaid terms, the system will return 0

1.7

SSL encryption (enhanced security)

If you want to add additional security to your communication, you may make encrypted calls to our system, but simple replacing the URL.
Regular URL: Encrypted URL http://smsc.i-digital-m.com/..... https://smsc.i-digital-m.com/..

You may do this for any call, like SMS sending, Wap message, Credit check etc.

2 Parameter Information:
2.1 Sender

The SourceAddress may be either of the following: - alphanumeric string with up to 11 characters - numeric string with up to 20 characters (internationally formatted number) ATTENTION: Numeric SenderID: You need to submit an internationally formatted number WITH a 00; a + or just the country code. Required parameters are: &sender= On specific Gateways you may be able to specify a local number, please contact IDM for specific information on this.

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

7/13

Documentation SMSC- API

www.i-digital-m.com

Alpha Sender ID: You can enter any 11 characters such as your company Name etc. Required parameters are: &sender= On specific Gateways you may be able to user ONLY pre-registered sender ids, please contact IDM for specific information on this.

2.2

recipients

The destination address has to be a numeric string with up to 20 characters (internationally formatted number). ATTENTION: Numeric recipient: For the destination Address it is irrelevant if you submit the SMS with +49; 0049 or a simple 49, as our system will correct the destination address automatically to the correct format. However, it is recommended to submit with 49xxx as a format. Required parameters are: &recipients=

2.3

Message Content
The Message content may contain any of the characters from the international GSM alphabet (03.38) as per the table below. Please note that some characters will count with 2 against the 160 characters of the message.

GSM Alphabet 03.38 (Any of these characters will count 1 of 160 characters)
The GSM 03.38 Default Character Set Dec Hex 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 8 9 A B C D E F @ $ LF CR 0 0 _ <ESC> 16 10 ! " # % & ' ( ) * + , . / 32 20 SP 0 1 2 3 4 5 6 7 8 9 : ; < = > ? 48 30 A B C D E F G H I J K L M N O 64 40 P Q R S T U V W X Y Z a b c d e f g h i j k l m n o 80 50 96 60 p q r s t u v w x y z 112 70

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

8/13

Documentation SMSC- API

www.i-digital-m.com

Extended GSM Alphabet. (For any of these characters you need to count 2 of 160 characters against the total character amount of your message!!!)
Some additional characters can be sent using the <ESC> code in the above table plus an additonal character Sending additional characters on GSM phones You want to send ASCII Character <FF> [ \ ] ^ { | } ~ 10 91 92 93 94 123 124 125 126 0C 5B 5C 5D 5E 7B 7C 7A 7E Decimal Hex <ESC> e <ESC> <LF> <ESC> < <ESC> / <ESC> > <ESC> ^ <ESC> ( <ESC> @ <ESC> ) <ESC> = Send the following Characters Hex 1B 65 1B 0A 1B 3C 1B 2F 1B 3E 1B 14 1B 28 1B 40 1B 29 1B 3D Decimal 27 101 27 10 27 60 27 47 27 62 27 20 27 40 27 64 27 41 27 61

This table shows the default GSM character set, but does not indicate how to encode the characters when you wish to send them in an HTTP POST message.

For Unicode SMS, please visit http://www.unicode.org in order to get the correct Values for Unicode SMS if you are not familiar with it. If you are familiar with Unicode SMS, you can use plain UTF-16 URL encode to send Unicode SMS to our Gateway.

2.4

Encoding

Messages that are send through the HTTP API need to be encoded using the URL -encode method which is very popular and any Web Developer should be familiar with.

3 Sample Calls
In the following we will provide you with a few samples of the SMSC HTTP API in order to facilitate development efforts. Numeric SENDER ID Regular SMS:

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

9/13

Documentation SMSC- API

www.i-digital-m.com

http://smsc.i-digital-m.com/smsgw/sendsms.php?user=......&password=......&sender= %2B4945037022977&recipients=491626825631&message=Testnachricht+%E4+% F6+%FC+%C4+%DC+%DF+%3F+%80+%24+%25+%A7+%26+%7B+%7D+%5B+...

will result in a SMS Message with the following parameters: Originator (SenderID): +4945037022977 Recipient (destination phone): +491626825631 Message content: Testnachricht ? $ % & { } [ ... Alpha SENDER ID Regular SMS:
http://smsc.i-digital-m.com/smsgw/sendsms.php?user=......&password=......&sender=idigital-m&recipients=491626825631&message=Testnachricht+%E4+%F6+%FC+% C4+%DC+%DF+%3F+%80+%24+%25+%A7+%26+%7B+%7D+%5B+...

will result in a SMS Message with the following parameters: Originator (SenderID): i-digital-m Recipient (destination phone): +491626825631 Message content: Testnachricht ? $ % & { } [ ... Please note that multiple recipients need to be separated by colons ; Alpha SENDER ID UNICODE SMS:
http://smsc.i-digital-m.com/smsgw/sendunicode.php?user=......&password=......&sender =-IDM-&recipients=491626825631&message= %u062A%u0639%u0642%u062F%20%u0644%u062C%u0646%u0629%20%u0634% u0643%u0644%u0647%u0627%20%u0627%u0644%u0627%u0626%u062A%u0644 %u0627%u0641%20%u0627%u0644%u0645%u0648%u062D%u062F%20%u0627% u0644%u064A%u0648%u0645%20%u0645%u0641%u0627%u0648%u0636%u0627 %u062A%20%u0645%u0639%20%u062C%u0628%u0647%u0629%20%u0627%u06 44%u062A%u0648%u0627%u0641%u0642&dlr=1

will result in a SMS Message with the following parameters: Originator (SenderID): -IDMRecipient (destination phone): +491626825631 Message content: _ _ For Information on how to send Unicode, please visit http://www.unicode.org Please note that you need to send UTF-16 encoded Unicode. Alternatively you can send the Unicode SMS as well in Hex coding. Therefore, please request our HEX SMS API from support@i-digital-m.com

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

10/13

Documentation SMSC- API

www.i-digital-m.com

Alpha SENDER ID WAP PUSH SMS:

http://smsc.i-digital-m.com/smsgw/sendwap.php?user=.....&password=......&sender=IDM-&recipients=491626825631&type=1&name=IDM-TEST&url=http://www.i-digitalm.com

will result in a SMS messages arriving on the destination phone, where the originator (sender id) of the SMS is: -IDM- the bookmark NAME/descriptor is: IDM-TEST the url the bookmark points to is: http://www.i-digital-m.com

4 Message Tracking / Status Updates:

If you require Status information on your SMS messages you need to submit a STATUS PUSH URL to interactive digital media GmbH.
(This URL can be entered in your Account Setup Form)

Status reports will then be automatically sent to the specified URL containing the FULL SMPP Parameter Information: A sample SMS Status update is like this: [DLR]=id:5959aaed3 sub:001 dlvrd:001 submit date:0611051327 done date:0611051327 stat:DELIVRD err:000 text: 62F210 [msgId]=5959aaed3 [srcAddress]=4945037022977 [dstAddress]=4915112751276 [addedDate]=2006-11-05 14:26:37.0 The corresponding contained parameters have the following meanings: [DLR]= Where id:5959aaed3 message Where stat:DELIVRD is the SMS message id of the originally submitted SMS is the Status of the SMS Message

[srcAddress]=4945037022977 Where SrcAddress=4945037022977 is the Source of the original submitted SMS message [dstAddress]=4915112751276 Where dstAddress=4915112751276is the destination Address of the original submitted SMS message [addedDate]=2006-11-05 14:26:37.0 Where addedDate= 2006-11-05 14:26:37.0 is the time of the original SMS submission to the SMSC Please do NOT pay to much attention to the submit date and done dates as these may imply incorrect values due to the international time zones and SMSC timestamps!

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

11/13

Documentation SMSC- API The important parts for HTTP injected SMS messages are: Id: SMS message id Stat: The SMS Status

www.i-digital-m.com

As the SMS Status information are NOT unified over all potential destination networks and countries, a useful SMS Status translation is defined in the following: Stat: DELIVRD = the SMS has been received on the Handset or by the terminating SMSC (most likely by the handset) Public Status recommendation: DONE (meaning successful delivered) Stat: ACCEPTD = the SMS has been received by the terminating SMSC but not yet delivered or has been submitted to the corresponding SMSC (most likely the SMS is buffered as the recipient phone is turned of or out of reach) Public Status recommendation: PENDING Stat: BUFFERD = the SMS has been buffered by the terminating SMSC but not yet delivered or has been submitted to the corresponding SMSC (most likely the SMS is buffered as the recipient phone is turned of or out of reach) Public Status recommendation: PENDING Stat: ENROUTE = the SMS has been buffered by the terminating SMSC but not yet delivered or has been submitted to the corresponding SMSC (most likely the SMS is buffered as the recipient phone is turned of or out of reach) Public Status recommendation: PENDING Stat: FAILED = the SMS could not be delivered by the terminating SMSC (most likely the SMS is wrongly formatted, or the destination phone number is invalid) Public Status recommendation: FAILED Stat: UNDELIV = the SMS could not be delivered by the terminating SMSC (most likely the SMS is wrongly formatted, or the destination phone number is invalid) Public Status recommendation: FAILED Stat:REJECTED = the SMS could not be delivered by the terminating SMSC (most likely the SMS is wrongly formatted, or the destination phone number is invalid) Public Status recommendation: FAILED Stat: EXPIRED = the SMS could not be delivered by the terminating SMSC (The message has expired the validity period) Public Status recommendation: FAILED

If you are sending via our MODEM SMSC there is one other SMS Status possible: Stat:UNKNOWN = the SMS status is unknown Public Status recommendation for MODEM SMSC injections: DONE

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

12/13

Documentation SMSC- API

www.i-digital-m.com

5 Additional Support
For additional support inquiries please contact support@i-digital-m.com . Please make sure to provide adequate contact information. Kind regards, IDM SMSC Support Team!

- A service of interactive digital media GmbH www.i-digital-m.com

(v3.9) Confidential

13/13