Click on images to see them in full screen

API - HTTP

The smsPULSE server offers a range of HTTP calls which allow:

Group updates
Contact updates
Directory look-ups creation and synchronisation
SMS sending
MMS sending (media files must be present on the server's file system - from smsPULSE V7.1)

These functions are designed to allow simple integration with any system able to issue HTTP calls and makes smsPULSE client agnostic. Future versions of smsPULSE will no doubt provide further functions. Furthermore, the smsPULSE server is designed to work in any type of network environment, for example Microsoft Exchange and SharePoint, and as such the ability to exploit all smsPULSE functions using a web browser and http calls is greatly expanded.

To synchronise the directory on the smsPULSE server with an Exchange server, please see this document: http://technet.microsoft.com/en-us/library/bb125104(EXCHG.65).aspx

Before you begin
To get the API working on your server you need to prepare it first. If you use the smsPULSE for Windows server you may skip this section. Otherwise, please use the following checklist:

Ensure the system ACL (Access Control List) is correctly set (see image 1). You do not need to do this if you use the smsPULSE Windows Server
Sign the sms.ACK database using the Domino Administrator
Ensure that the signer name (server or user) is included in the list of authorised executors on the server, in the server profile. Please note that if you upgrade smsPULSE, the databases will be signed again using the server ID name, so please ensure that this name also appears in the list of authorised executors (see image 2)
Update the System ID and provide it to your HTTP API developer (images 3 and 4)

Image 1 (required for Domino users but not for the smsPULSE for Windows server)
ACL: change the rights for "Anonymous" to "Depositor", if it is not yet set:

Image 2
List the signer in the server document:

Images 3 and 4: Update the System ID
Click on the System ID button and fill-in the ID. You can find the ID by viewing the smsPULSE status on the Domino Console (type: tell smspulse st):

The following screen appears:

If you use the smsPULSE Windows Server or use the smsPULSE Web UI, use the following to change the system ID:

Logon to the smsPULSE Web UI using your admin password, and click "Change" on the System ID:

a pop-up will appear:

You can obtain your system ID in a licensed system by issuing the smsPULSE Status command, or make up your own number if the server is not licensed yet.

IP Addresses allowed
from smsPULSE V8.2 you may also set the IP address from which API calls may be made to your server. This is a security feature which augments the usage of the System ID. Specify the IP addresses of connected clients. You may use wild card for a segment, for example. 192.168.*.*. You cannot set a wild card inside a segment, for example 10.20.30.*1. Of course you may just type a complete IP address. None allows all.

API Calls

General Syntax: All calls to the http server are made using the following syntax, when using HTTP GET:
	http://<server_address>/smspulse/smsack.nsf/ds?openagent&action=<action_name>&sysid=<System_ID>&para=value&para1=value1...&paraN=valueN OR http://<server_address>/smspulse/smsack.nsf/in?openagent&gtw=<gateway_name>&sysid=<System_ID>&para=value&para1=value1...&paraN=valueN If wish to use HTTP POST - see below

POST vs GET: In the examples below, all calls are HTTP GET. If you wish to perform an HTTP POST for all calls, use the URL listed below. You will then set all the variables in the HTTP Body or Header as required by a standard HTTP POST. Please note that this feature is available from smsPULSE V8.1.6 onwards
	http://<server_address>/smspulse/smsack.nsf/ds?createdocument OR http://<server_address>/smspulse/smsack.nsf/in?createdocument

You can test your HTTP posts by using the following URLs...
http://<server_address>/smspulse/smsack.nsf/ds?openform

OR
http://<server_address>/smspulse/smsack.nsf/in?openform

Basic parameters:
	<server_address> - the address of your server, may be an IP address too. The server must be configured to accept such addresses. <action_name> - defines what you want to do. For the list of actions, see below. Not required for inbound SMS submitted from a gateway <System_ID> - is an ID code which you must always provide. The code is defined in the system and is fixed. When accepting inbound SMS from a gateway, use the second System ID. See above. Please note that for inbound SMS you must also add the text &params after the System ID value (but not if you use HTTP POST)
Optional basic parameters:
	<key> - when a key is specified the call is always assumed to be an update. A record is fetched using the key and other fields are used for update. &json=y - use this if you wish the response to be in JSON format
Examples:
	http://192.168.1.10/smspulse/smsack.nsf/ds?openagent&action=con&sysid=33452345234&name=Jo+Blogs&tel=07787538925&public=y&gsm=y&exempt=n&country=1
As you can see from the above, the system uses a single agent which executes all http commands. The url part "/smspulse/smsack.nsf/ds?openagent&action=" is common to al calls.
	http://213.72.3.172/smspulse/smsack.nsf/in?openagent&gtw=unicell&sysid=3456753456323465&params&from=120185858383&to=68000&message=agree+to+subscribe
The above shows an HTTP call made to smsPULSE from a remote gateway in response to a message sent to them from cell phone 120185858383, saying "Agree to subscribe". Note the use of two different System IDs

General Return codes: Each call provides a simple response with two or three variables. The response is provided as raw text, each on its own line. The response has the following format:
	<type>:<code> MSG:<response_message> KEY:<data_key>
Parameters:
	<type> - Two possible values: "ERR" or "OK" <code> - Response code, see below for for numbers and what they mean <response_message> - The meaning of the code, from the same table below. <data_key> - A unique key which identifies the data that was either created or updated. If data item is deleted, the returned key will always be 0
Example:
	OK:14 MSG:Group updated KEY:F46B1C24F2F0BC6E8025781300773015 OR in JSON format {"OK":"14","MSG":"Group updated","KEY":"F46B1C24F2F0BC6E8025781300773015"}

Fixed list of error codes
	1:No such action 2:No System ID Set 3:System ID mismatch 4:No such key

System ID: Each call must include the system ID otherwise the call will be rejected. To obtain the system ID type "tell smspulse st" at the server console or use the Web UI to obtain the same information without access to the console. If you expect a gateway to post messages to the smsPULSE server you must provide the sms.IN system ID. The syntax is:
	&sysid=<number>
Example:
	&sysid=33452345234 OR &sysid=3456753456323465

User ID: Each call may include the User ID the data will be listed for. If you omit this field, data will be visible to the smsPULSE Server and to the administrators only. The syntax is:
	&userid=<name>
Example:
	&userid=Mike+Smith

Note:
If your server is not yet licensed and you are still in evaluation mode, you will need to insert a temporary System ID which is it least 8 characters long. You will need to use this System ID in all calls and the setup. Please remember to change the System ID in all code you have used once your server is licensed. If you use the Notes client to access the sms.ADMIN database, the number is the same you provided when you used the "Set System ID".

Available Calls

Group (simple) - create or update
Action:
	grp
Variables:
	"name": the name of the group. If you do not provide a key, the name will be used as a key. eg &name=sales "mode": optional, value ="new". Use this variable when you want to force the creation of a group even if one already exists. eg: &mode=new "members": Lists the members and their phone numbers, separated by semi-colons. eg: &members=joe+blogs+12232334489;mike+doe+3456345737 "categories": Lists the contact categories you wish to use instead of members, separated by semi-colons. eg: studentsAD23;studentsAD25
Example:
	http://192.168.1.10/smspulse/smsack.nsf/ds?openagent&action=grp&sysid=67878979542&name=sales&members=joe+blogs+12232334489;mike+doe+3456345737&userid=Mike+Smith OR http://192.168.1.10/smspulse/smsack.nsf/ds?openagent&action=grp&sysid=67878979542&name=students&categories=studentsAD23;studentsAD25&userid=Mike+Smith
Returns:
	11:No group name 12:Group is empty 13:New Group saved 14:Group updated

Contact - create or update
Action:
	cont
Variables:
	"name": the name of the group. If you do not provide a key, the name will be used as a key. eg &name=Joe+Smith "mode": optional, value ="new", eg &mode=new. Use this variable when you want to force the creation of a group even if one already exists "country": Country code for the contact. For example, 1 for the USA, 33 for France. eg &country=1 "phone": Phone number for the contact. For example, 07712345678. eg &phone=07712345678 "categories": optional, List the contact categories you wish this contact to be part of, separated by semi-columns. eg: studentsAD23;studentsAD25
Example:
	http://192.168.1.10/smspulse/smsack.nsf/ds?openagent&action=cont&sysid=67878979542&name=Joe+Smith&categories=studentsAD23;studentsAD25&country=1&phone=07712345678&userid=Mike+Smith
Returns:
	30:No contact name 31:No phone number 33:New Contact saved 34:Contact updated

Send - send a message to multiple cell phone using numbers provided
Action:
	send
Variables:
	"smsBody": the text of the message. Long messages will be truncated according to system setup. If you need to use & inside the body of your message use the parameter "&bodyend=y" and include smsBody as your last parameter. You may then use ...&smsBody=you&me "smsMobiles": cell phone numbers, each in the standard international format, separated by commas. <country_code><number_no_leading_zeros>. For example, 1806123456 "smsMobileFrom": optional, name or number of the sender. Please note that when using GSM the "from" value is automatically the SIM phone number. Note: if you are using a gateway that dictates sender names you must use one of these here "deleteMe": optional, value "Y". Deletes the record after the message is sent "smsCallback": optional, request delivery confirmation "gsm": optional, value "Y". If the system has GSM lines, the message will be routed via GSM (as oppose to HTTPS) "gsmQue": optional, value is the GSM queue you wish to use, if the system allows such choices. From V8.1 this also apply to SMPP Queue "smsFlash": optional, value "Y" "smsRule": optional. The name of the rule you wish executed should the sender reply to the message "files": optional, a list of file names (full path) for files to add to the message and form an MMS. Separate file names with a vertical bar (\|). Please note that from version 8.1.6 you can send and receive vcf files. Note: smsPULSE has set a fixed limit on the number of allowed attachments in a single MMS message to 10. Your server must be licensed and configured to have at least one MM1 Communication Line. New from V8.1: "from": email address of the user posting the SMS/MMS. Any failures will be emailed back to this address "org": the name of the organisation the post relates to "smsDelayDate": optional, the date you wish the message to be sent on. Format is <year_four_digits>-<month>-<day_of_month>. Example: &smsDelayDate=2014-9-23 "smsDelayTime": optional, the time you wish the message to be sent after, in 24 hours format. Format is <hours>:<minutes>. For example: &smsDelayTime=21:35 "bodyend": optional, use if you need to use & in your text and include &smsBody as the last parameter. For example: &bodyend=y
Example:
	http://192.168.1.10/smspulse/smsack.nsf/ds?openagent&sysid=67878979542&action=send&smsBody=Hello+World&smsMobileFrom=avitchi&smsMobiles=447787123456,1806123456&userid=Mike+Smith mms example: http://192.168.1.10/smspulse/smsack.nsf/ds?openagent&sysid=67878979542&action=send&smsBody=Hello+World&smsMobileFrom=avitchi&smsMobiles=447787123456,1806123456&userid=Mike+Smith&files=c:\mms\img1.jpg\|c:\mms\img2.gif
Returns:
	15:Message is empty 16:No Numbers 17:Bad file 18:No such router rule 20:Message posted OK

status - check delivery status of sms
Action:
	status
Variables:
	"key": the key you recived when the original sms was posted . eg &key=8907383820183765
Example:
	http://192.168.1.10/smspulse/smsack.nsf/ds?openagent&action=status&sysid=67878979542&key=8907383820183765
Returns:
	7:No message key 8:Bad message key 10:Status checked OK (including status information)

In-bound Messages from external source or gateway

Variables:
	"gtw": the name of the gateway. Use the "std" gateway if the parameters below can be accommodated by your gateway. Otherwise use the gateway code we provide. Contact support@smspulse.com "to": the phone number the message was sent to "from": number or name of sender "text": the text of the message "isunicode": optional, value "Y". Set to Y if the text above is supplied as Unicode Note: Please remember that you must add the text "&params" after the sysid value, or simply at the end of the URL installed at the service provider.
Example:
	http://213.72.3.172/smspulse/smsack.nsf/in?openagent&gtw=std&sysid=3456753456323465&params&text=Hello+World&from=447787538925&to=68700 OR http://213.72.3.172/smspulse/smsack.nsf/in?openagent&gtw=std&sysid=3456753456323465&params&text=00480065006C006C006F00200057006F0072006C0064&from=447787538925&to=68700&isunicode=Y
Returns:
	6: No such gateway 15:Message is empty 20:Message posted OK

Spam - SPAM White/Black Lists Update
Action:
	spam
Variables:
	"upd-type": use of the values below to define the update you wish to perform: bl-add - black list add number wl-add - white list add number bl-rem - black list remove number wl-rem - white list remove number "number": cell phone number in the standard format or as it arrives into smsPULSE inbox, sms.IN, common format <country_code><number_no_leading_zeros>. For example 1806123456. Numner may also by alphabetic
Example:
	http://192.168.1.10/smspulse/smsack.nsf/ds?openagent&sysid=67878979542&action=spam&upd-type=wl-add&number=17892029393
Returns:
	40:Incorrect SPAM action 41:No phone number 42:Phone number too short 43:Phone number already listed 44:Phone number was not listed 48:Spam number added to list 49:Spam number removed list