REST API Guide

Getting Started

Welcome to the world’s greatest SMS API!

Our REST API helps developers integrate SMS Messenger with their existing systems quickly and easily.

Ready to get started? Great!

Here’s the short version of what you need to do:

Register – once you have created your SMS Messenger account, create an API token on the Developer Settings page
Be a good API citizen – read, understand, and abide by the terms of use
Authenticate – all API requests need to be authenticated
Build cool stuff :)

Authentication

Requests to SMS Messenger are authenticated by providing your account email address and API token as request header attributes named email and token respectively. Your API key is securely encrypted by the SSL channel. Basic Authentication is also supported, using your email address and API token as the username and password.

You may also provide the email and token as URL parameters, although this only recommended for testing purposes as your API token will not be encrypted.

Character Encoding

Please note that SMS uses GSM7 character encoding by default, which allows for 160 characters in a single SMS. Should you send messages in non-GSM7 character encoding, the available character count is reduced to 70.

You are able to get the credit cost of an SMS, the number of SMS parts that it would require to send a specific message, as well as the encoding which would be used through the frontend or via API. It is your responsibility to ensure you are sending using the desired character encoding.

API Endpoints

This section documents all endpoints, parameters and error messages available with the SMS Messenger REST API. The base URL for all API endpoints is https://www.zoomconnect.com/app/

Account

Endpoint

Description

Parameters / Request Body Class

GET /api/rest/v1/account/balance

Returns your account’s credit balance

None

GET /api/rest/v1/account/statistics

Returns data from the statistics report. Note that by default the statistics shown are based on the number of messages, use the calculateCreditValue should you wish to calculate the statistics based on credit value.

Parameters:

from	string	date format: dd-MM-yyyy
to	string	date format: dd-MM-yyyy
userEmailAddress	string	optional email address of user to return statistics for a single user, default is to return statistics for all users if administrator, or statistics for your own account if not an administrator
campaign	string	optional campaign name
includeRefundedAndOptout	boolean	optionally include refunded and optout counts, default is false
calculateCreditValue	boolean	optionally calculate using credit value rather than message count, default is false

POST /api/rest/v1/account/transfer

Transfers credits between two users in the same team. The account email address fields as well as the number of credits to transfer are required.

Request Body:
{
“transferFromEmailAddress”: “”,
“transferToEmailAddress”: “”,
“numberOfCreditsToTransfer”: 0
}

GET /api/rest/v1/account/user

Find a user for a particular email address

Parameters:

searchEmail

string

search by email address

PUT /api/rest/v1/account/user

Creates a new sub-account in your team. The following fields are required firstname, lastname, email address, contact number and password.

Request Body:
{
“password”: “”,
“creditBalance”: 0,
“emailAddress”: “”,
“firstName”: “”,
“lastName”: “”,
“contactNumber”: “”,
“userId”: 0,
“company”: “”
}

GET /api/rest/v1/account/user/{userId}

Gets a user from a given user id

Parameters:

userId

integer

id of user

POST /api/rest/v1/account/user/{userId}

Updates a sub-account in your team. The following fields can be updated firstname, lastname, contact number and password.

SMS

Endpoint

Description

Parameters / Request Body Class

POST /api/rest/v1/sms/send

Sends a single message. The recipientNumber and message fields are required. All other fields are optional.

Request body:
{
“message”: “”,
“campaign”: “”,
“recipientNumber”: “”,
“dateToSend”: “”,
“dataField”: “”
}

POST /api/rest/v1/sms/send-bulk

Send multiple messages in one transaction.

Request Body:
{
“sendSmsRequests”: [
{
“message”: “”,
“campaign”: “”,
“recipientNumber”: “”,
“dateToSend”: “”,
“dataField”: “”
}
],
“defaultDateToSend”: “”,
“messagesPerMinute”: 0
}

GET or POST /api/rest/v1/sms/send-url-parameters

Send a single message using URL parameters.The recipientNumber and message parameters are required. All other parameters are optional.

Parameters:

recipientNumber (required)	string	the phone number of the recipient to send to
message (required)	string	the message to send
dateToSend	string	date format: yyyyMMddHHmm
campaign	string	optional campaign name
dataField	string	optional extra data

GET or POST
/api/rest/v1/sms/send-url/{token}

Send a single message using your unique URL without having to authenticate using your email address or REST API token. The token required is the URL Sending token available on the developer setting page. The recipientNumber and message parameters are required. All other parameters are optional. Not that the token required here is not the REST API token, but rather the token specifically created for URL sending.

Parameters:

token	string	Send-URL token
recipientNumber (required)	string	the phone number of the recipient to send to
message (required)	string	the message to send
dateToSend	string	date format: yyyyMMddHHmm
campaign	string	optional campaign name
dataField	string	optional extra data

Contacts

Endpoint

Description

Parameters / Request Body Class

GET /api/rest/v1/contacts/all

Returns all contacts

None. Paginated.

POST /api/rest/v1/contacts/create

Request Body:
{
“firstName”: “”,
“lastName”: “”,
“contactId”: “”,
“contactNumber”: “”,
“title”: “”
}

DELETE /api/rest/v1/contacts/{contactId}

Deletes a contact

Parameters:

contactId (path)

string

id of the contact

GET /api/rest/v1/contacts/{contactId}

Returns details for a single contact

Parameters:

contactId (path)

string

id of the contact

POST /api/rest/v1/contacts/{contactId}

Updates a contact

Parameters:

contactId (path)

string

id of the contact

Request Body:
{
“firstName”: “”,
“lastName”: “”,
“contactId”: “”,
“contactNumber”: “”,
“title”: “”
}

GET or POST /api/rest/v1/contacts/{contactId}/addFromGroup/{groupId}

Remove a contact from a group

Parameters:

contactId (path)	string	id of the contact
groupId (path)	string	id of the group

GET or POST /api/rest/v1/contacts/{contactId}/addToGroup/{groupId}

Add a contact to a group

Parameters:

contactId (path)	string	id of the contact
groupId (path)	string	id of the group

Groups

Endpoint

Description

Parameters / Request Body Class

GET /api/rest/v1/groups/all

Returns all groups

None. Paginated.

POST /api/rest/v1/groups/create

Create a group

Request Body:
{
“name”: “”,
“groupId”: “”
}

GET /api/rest/v1/groups/{groupId}

Returns details for a single group

Parameters:

groupId (path)

string

id of the group

DELETE /api/rest/v1/groups/{groupId}

Deletes a group

Parameters:

groupId (path)

string

id of the group

POST /api/rest/v1/groups/{groupId}

Update a group

Parameters:

groupId (path)

string

id of the group

Request Body:
{
“name”: “”,
“groupId”: “”
}

GET or POST /api/rest/v1/groups/{groupId}/addContact/{contactId}

Add a contact to a group

Parameters:

groupId (path)	string	id of the group
contactId (path)	string	id of the contact

GET or POST /api/rest/v1/groups/{groupId}/removeContact/{contactId}

Remove a contact from a group

Parameters:

groupId (path)	string	id of the group
contactId (path)	string	id of the contact

Messages

Endpoint

Description

Parameters / Request Body Class

GET /api/rest/v1/messages/all

Returns all messages

Paginated.
Parameters:

pageSize	integer	number of elements to return at a time
page	integer	page number
type	string INBOUND OUTBOUND	filter by message type
status	string SCHEDULED UNKNOWN SENT FAILED FAILED_REFINDED FAILED_OPTOUT DELIVERED	filter by message status
fromDateTimeSent	string	date format: yyyyMMdd
toDateTimeSent	string	date format: yyyyMMdd
fromDateTimeReceived	string	date format: yyyyMMdd
toDateTimeReceived	string	date format: yyyyMMdd
fromNumber	string	phone number the message was sent from
toNumber	sting	phone number the message was sent to
message	string	search matching message text
campaign	string	search by campaign
dataField	string	search by data field
deleted	boolean	return only deleted / not deleted messages
read	boolean	return only read / unread messages (inbox messages only)
repliesToMessageId	string	return only inbox messages which are a reply to the message with the given message id

POST /api/rest/v1/messages/analyse/full

Returns full analysis of message

Request Body:
{
“message”: “”,
“recipientNumber”: “”
}

POST /api/rest/v1/messages/analyse/message-credit-cost

Returns the number of credit which would be required to send the request message to the requested recipient number

Request Body:
{
“message”: “”,
“recipientNumber”: “”
}

POST /api/rest/v1/messages/analyse/message-encoding

Returns the message encoding that would be required to send the requested message

Request Body:
{
“message”: “”,
“recipientNumber”: “”
}

POST /api/rest/v1/messages/analyse/message-length

Returns the number of characters the requested message consists of

Request Body:
{
“message”: “”,
“recipientNumber”: “”
}

POST /api/rest/v1/messages/analyse/message-length-within-max-allowed

Returns whether the given message length is within the maximum allowed number of characters given the encoding that would be required to send the message

Request Body:
{
“message”: “”,
“recipientNumber”: “”
}

POST /api/rest/v1/messages/analyse/number-of-messages

Returns the number of SMS parts which would be sent when sending the requested message

Request Body:
{
“message”: “”,
“recipientNumber”: “”
}

GET /api/rest/v1/messages/{messageId}

Returns details for a single message

Parameters:

messageId (path)

string

id of the message

DELETE /api/rest/v1/messages/{messageId}

Deletes a message

Parameters:

messageId (path)

string

id of the message

PUT or POST /api/rest/v1/messages/{messageId}/markRead

Marks a message as read

Parameters:

messageId (path)

string

id of the message

PUT or POST /api/rest/v1/messages/{messageId}/markUnread

Marks a message as unread

Parameters:

messageId (path)

string

id of the message

Templates

Endpoint

Description

Parameters / Request Body Class

GET /api/rest/v1/templates/all

Returns all templates

None. Paginated.

GET /api/rest/v1/templates/{templateId}

Returns details for a single template

Parameters:

templateId (path)

integer

id of the template

DELETE /api/rest/v1/templates/{templateId}

Deletes a template

Parameters:

templateId (path)

integer

id of the template

Receiving a reply

SMS Messenger provides two possible methods for receiving replies by API, either by Webhooks or by Polling. Using Webhooks is the preferred method as it allows messages to be received efficiently and in real-time.

When using webhooks, all replies received are sent as a POST request to a specified URL. To set the message forward URL please login to SMS Messenger, click on your company name, click on “Developer settings” and paste the URL to which inbound replies are to be forwarded.

Note that while polling the server for new replies is possible, should this result in high server load, the requests may be rate limited resulting in a delay in receiving replies.

http://yourserver.com/receive-sms.php?
      from=+27725551234
          &repliedToMessageId=121212
      &messageId=124567
      &message=REPLY
      &date=201404282055
      &campaign=shoe campaign
      &dataField=custom

Receiving a delivery report

Similar to receiving replies, all delivery reports received are sent as a POST request to a specified URL. To set the delivery report URL please login to SMS Messenger, click on your company name, click on “Developer settings” and paste the URL to which delivery reports are to be forwarded.

http://yourserver.com/delivery/report.php?
      &status=DELIVERED
      &messageId=40124213

REST API Guide

Getting Started

Authentication

Character Encoding

API Endpoints

Account

SMS

Contacts

Groups

Messages

Templates

Receiving a reply

Receiving a delivery report

Title

Register