HTTP(S) API Description
Integrate with CommPeak's SMS service using HTTPS API, enabling SMS submitting and delivery status checking.
The HTTPS API enables SMS submission and checking of delivery status.
You can set authentication information (login and password) for connecting to the CommPeak SMS platform when you create your SMS channels. Each SMS 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: - cut (trim message text to 140 bytes) - shortens the message leaving only the first 140 bytes to send. - split - split_sar - splits the message according to the logic described below. The difference between split and split_sar is in the header to be used, for split, it is UDH header, for split_sar, it is SAR accordingly. - payload - message_payload field is used for sending the message text via SMPPprotocol. The splitting (options 2/3) depends on the encoding: - dataCoding = 0: one message can contain up to 160 symbols, if more – segment count = message length / 152 - dataCoding from 1 to 7: one message can contain up to 140 symbols, if more – segment count = message length / 134 - dataCoding = 8: one message can contain up to 70 symbols (140 bytes), if more – segment count = message length / 67 (134 bytes). |
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 OKContent-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
Updated 4 days ago