The API is a standard REST interface using the HTTP / HTTPS POST method. The format of the message is a standard XML message. The endpoint for the service is http://smsserver.channelmobile.co.za:8088 or https://smsserver.channelmobile.co.za:8084. The following functions are defined.
balance - request your current account balance
send - send sms messages
receive - receive replies
The send message call is used to send a message or messages to a handset or a number of handsets. The api call will return the status and a unique message id for each message accepted.
Once a message has been accepted the message will be placed in the sending queue and once the message has been delivered to the handset, or the message has expired, a notification message will be sent to the sender informing them of the status of the message.
The destination of these delivery notifications can be specified in the send request, or Channel Mobile can configure a default destination for delivery notifications and replies.
The delivery message will contain the unique references generated by the system as well as the UID specified by the sender (if the UID was specified).
The element name for sending is send, and the following attributes can be specified for the element, The optional attributes will be used as the default values for the specified setting and can be overridden in each subsequent message element. The default message text can also be specified at this level. The message text is specified as the element value. The element value can be specified as CDATA to cater for special characters in the message text.
| Name | Format | Required | Description |
|---|---|---|---|
| user | string | YES | The username to identify the account user |
| password | string | YES | The Password for the specified user |
| from | string | NO | The from address can be specified for some international messages. This specifies the source address that will be used when sending the message. South African networks do not allow the changing or re-writing of the source address for security reasons. |
| concatenate | numeric | NO |
An indicator to specify how messages longer than 160 characters should be handled. Options 1 and 2 will generate multiple messages and it will be charged as multiple messages |
| validity | string | NO | The validity period of the message. This indicates how long after the message has been submitted to the network, it will expire if not delivered. This time interval must be specified as the period and the units with no spaces. The possible units are: mhd when m = minutes , h = hours and d = days. The default is 24h |
| scheduled | string | NO | Specify a time in the future the message must be scheduled for. The message will be accepted now, but will be placed in a pending queue until the scheduled date time is reached. The format is in the xs:dateTime format or the normal YYYY-MM-DD hh:mm:ss format is also supported. |
| type | string | NO |
An indicator of the type of message, for 16bit/ucs2 or binary messages the buffer must be specified as a hexidecimal character string. The possible values are: 16bit, ucs2, binary and flash The default is text |
| reply | string | NO | The destination url for replies, must be a standard http url, the url must start with http:// or https:// for secure posts. |
| notify | string | NO | The destination url for delivery notifications, must be a standard http url, the url must start with http:// or https:// for secure posts. |
The destinations are specified as message sub elements and can contain the following attributes, the message text is specified as the element value, and can be specified using CDATA to cater for special characters
| Name | Format | Required | Description |
|---|---|---|---|
| to | string | YES | The destination address, this must be in international format with the leading + sign. |
| from | string | NO | The from address can be specified for some international messages. This specifies the source address that will be used when sending the message. South African networks do not allow the changing or re-writing of the source address for security reasons. |
| concatenate | numeric | NO |
An indicator to specify how messages longer than 160 characters should be handled. Options 1 and 2 will generate multiple messages and it will be charged as multiple messages |
| validity | string | NO | The validity period of the message. This indicates how long after the message has been submitted to the network, it will expire if not delivered. This time interval must be specified as the period and the units with no spaces. The possible units are: mhd when m = minutes , h = hours and d = days. The default is 24h |
| scheduled | string | NO | Specify a time in the future the message must be scheduled for. The message will be accepted now, but will be placed in a pending queue until the scheduled date time is reached. The format is in the xs:dateTime format or the normal YYYY-MM-DD hh:mm:ss format is also supported. |
| type | string | NO |
An indicator of the type of message, for 16bit/ucs2 or binary messages the buffer must be specified as a hexidecimal character string. The possible values are: 16bit, ucs2, binary and flash The default is text |
| reply | string | NO | The destination url for replies, must be a standard http url, the url must start with http:// or https:// for secure posts. |
| notify | string | NO | The destination url for delivery notifications, must be a standard http url, the url must start with http:// or https:// for secure posts. |
| uid | string | NO | a user reference, this value will be returned in the delivery notification, and for individual replies |
The response message is in standard xml format. and returns the status of the send request, the main element is send-response. For complete request failure a single error status will be returned with the reason code and text. a typical sample of a complete failure is an invalid username or password. All other errors will return a response message that will have a status entry for each message submitted. On successful submission, the status entry will also contain the source address used to send the message and a system generated numeric id, This id is unique for the lifetime of the message. The client user id or UID will also be returned for each status entry. This will allow the user to update the submission status of each message submitted. The possible attributes for the send-response element is:
| Name | Format | Specified | Description |
|---|---|---|---|
| status | numeric | always | The status of the request. I successful request will return a status of 0 |
| error | string | error | A string description of the error |
| credits | decimal | success | The number of credits required by the call |
| available-credits | decimal | success | The number of remaining credits |
Successful requests will have a message element for each message submitted with status information about the message. The message element can contain the following attributes
| Name | Format | Specified | Description |
|---|---|---|---|
| status | numeric | always | The status of the request. I successful request will return a status of 0 |
| error | string | error | A string description of the error |
| to | mobile number | always | The mobile number the message was destined for |
| uid | string | always | The uid specified by the send request |
| reference | numeric | success | The unique reference number generated by the gateway |
The receive call is used to check for reply messages. If you have not specified a reply destination when sending the message, and there is no default reply destination configured for your username, You will use this API call to check for and return replies
The element name for this API call is receive, and it supports the following attributes:
| Name | Format | Required | Description |
|---|---|---|---|
| user | string | YES | The username to identify the account user |
| password | string | YES | The Password for the specified user |
The response to the receive call is a receive response with a message sub element for each received response. The message element has the following attributes:
| Name | Format | Specified | Description |
|---|---|---|---|
| to | string | always | The destination number of the reply. This is the same number that was returned in the from response in the message send |
| from | string | always | The source number of the reply. This is the number of the mobile device that the reply was received from |
| created | datetime | always | The date and time the reply was received on the system |
| options | string | always | Additional options to indicate flags on the received message |
| type | string | always | An indication of the type of message received, This can be TEXT or BINARY |
| uid | string | always | The uid that was specified in the outgoing message. |
| message-id | string | always | a unique message id generated by the gateway. |
The message text of the reply will be the element content
Download call and response samples from here
You can download sample code/programmes from here
| NameValueDescription | ||
|---|---|---|
| ERR_TECHNICAL | 10000 | Technical error on message server |
| ERR_AUTHENTICATION | 10001 | Invalid user or password |
| ERR_NO_DESTINATION_ADDR | 10003 | No number specified |
| ERR_INV_DESTINATION_ADDR | 10004 | Invalid number |
| ERR_NO_VALID_ROUTING_ENTRY | 10005 | Unable to route the specified number |
| ERR_INSUFFICIENT_FUNDS | 10006 | Insufficient funds available |
The possible values for delivery notifications are
3 - DELIVERED
4 - SUBMITERROR
5 - DELIVERERROR
8 - CANCELED