Find:

API - HTTP

From smsPULSE V5.5, 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. Further, 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 expended.

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 authorise 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 set yet.

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.

API Calls

General Syntax: All calls to the http server are made using the following syntax:
	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

Basic parameters:
	<server_address> - the address of your server, may be an IP address too. The server must be configured to accept such address. <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 in-bound SMS from a gateway, use the second System ID. See above.
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.
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&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

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 licences 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 use this System ID in all calls and the set-up. 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-columns. eg: &members=joe+blogs+12232334489;mike+doe+3456345737 "categories": List the contact categories you wish to use instead of members, separated by semi-columns. 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 "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 was 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 "smsFlash": optional, value "Y" "smsRule": Optional. The name of the rule you wish executed should the sender reply again "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 (\|). Note: smsPULSE has set a fix 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.
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

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
Example:
	http://213.72.3.172/smspulse/smsack.nsf/in?openagent&gtw=std&sysid=3456753456323465&text=Hello+World&from=447787538925&to=68700 OR http://213.72.3.172/smspulse/smsack.nsf/in?openagent&gtw=std&sysid=3456753456323465&text=00480065006C006C006F00200057006F0072006C0064&from=447787538925&to=68700&isunicode=Y
Returns:
	6: No such gateway 15:Message is empty 20:Message posted OK