This document provides the HTTP API description for external systems' integration with the CommPeak SMS service. HTTPS API enables SMS submitting and checking delivery status.
You can set authentication information (login and password) for connecting to the CommPeak SMS platform when you create your SMS channels. Each API request must contain credentials; otherwise, the system will reject it as unauthorized.
You can send requests either using GET or POST methods to the URL provided by the system owner.
Submit SMS
Request format:
HTTPS:
https://sms1.commpeak.com:8002/api?username=<username>&password=<password>&ani=<ani>&dnis=<dnis>&message=<message>&command=submit&serviceType=<serviceType>&longMessageMode=<longMessageMode>
HTTP:
http://sms1.commpeak.com:8001/api?username=<username>&password=<password>&ani=<ani>&dnis=<dnis>&message=<message>&command=submit&serviceType=<serviceType>&longMessageMode=<longMessageMode>
Parameters:
Parameter | Description |
User name | Username |
Password | Password |
ANI | Caller ID. Technical limitation - alpha-numeric up to 32 symbols. Peculiarities of the destination route can impose additional restrictions. |
DNIS | Destination number. Must be sent in an international E.164 format (up to 15 digits allowed). |
Message | Message text |
Command | Request type. Must be set to the submit value. |
Service type | Service type, provided by the system owner for the registered interconnection. Can be blank. |
LongMessageMode | Type of long messages processing. The following values are allowed:
The splitting (options 2/3) depends on the encoding:
|
All parameters except for LongMessageMode are obligatory, the default value for LongMessageMode is 1 (cut).
Response format:
In the case of successful processing, the HTTP response status is 200 OK. The response body contains the message_id in JSON format.
Response sample:
HTTP/1.1 200 OKContent-Type: text/html; charset=UTF-8{"message_id":"alss-a1b2c3d4-e5f67890"}In case of rejected messages (no compatible routes found or authentication data is incorrect), the HTTP response status is 400 Bad Request.
The response body contains the string describing the reason for rejection e.g. NO ROUTES or Unknown username.
HTTP/1.1 400 Bad RequestContent-Type: text/html; charset=UTF-8Unknown username
In case an incorrect password is provided, HTTP status is 401 Unauthorized.
HTTP/1.1 401 UnauthorizedContent-Type: text/html; charset=UTF-8Incorrect password
Request SMS Status
Request format:
https://sms1.commpeak.com:8002/api?username=<username>&password=<password>&messageId=<messageId>&command=query
http://sms1.commpeak.com:8001/api?username=<username>&password=<password>&messageId=<messageId>&command=query
Parameters:
Parameter | Description |
User name | Login |
Password | Password |
messageId | Message identifier received in the response to submit |
command | Request type. Must be set to “query” value |
All parameters are obligatory.
Response format:
In the case of successful processing, the status in the header of the HTTP response is 200 OK.
The response body contains one of the following possible values:
Parameter | Description |
ENROUTE | The message is in the routing stage. |
SENT | The message is delivered to the SMSC. |
DELIVRD | The message is delivered to the subscriber. |
EXPIRED | The message storage period expired. |
DELETED | The message was deleted. |
UNDELIV | The message can not be delivered. |
ACCEPTD | The message is accepted by SMSC. |
UNKNOWN | Unknown message status. |
REJECTD | The message was rejected by SMSC. |
Response sample:
HTTP/1.1 200 OKContent-Type: text/html; charset=UTF-8{"status":"DELIVRD"}Status can be requested within 72 hours after submitting the message.
In case the message with the requested message ID is not found, the HTTP response code is 200 OK. The response body contains the error description in the “status” field:
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
{"status":"message ID alss-some-message-id not found"}
If a status request is incorrect (for example, the login is incorrect), the HTTP status 400 Bad Request is sent back. The response body contains the string describing the reason for rejection, e.g., NO ROUTES or Unknown username.
HTTP/1.1 400 Bad RequestContent-Type: text/html; charset=UTF-8Unknown username
If the password is incorrect, the HTTP status is 401 Unauthorized. The response body contains a string describing the reason for rejection.
HTTP/1.1 401 UnauthorizedContent-Type: text/html; charset=UTF-8Incorrect password