|

Help center

Submit a ticket My Tickets
Welcome
Login

HTTP(S) API Description

This document provides the HTTP API description for external systems' integration with the CommPeak SMS platform. 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.

SMS Submitting

Request format:

 Parameters:

User name    Username
PasswordPassword
ANICaller ID. Technical limitation - alpha-numeric up to 32 symbols. Peculiarities of the destination route can impose additional restrictions.
DNISDestination number. Must be sent in an international E.164 format (up to 15 digits allowed).
MessageMessage text
CommandRequest type. Must be set to the “submit” value.
Service typeService type, provided by the system owner for the registered interconnection. Can be blank.
LongMessageModeType of long messages processing. The following values 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 SMPP protocol.
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 OK
Content-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 Request
Content-Type: text/html; charset=UTF-8
Unknown username

In case an incorrect password is provided HTTP status is 401 Unauthorized

HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=UTF-8
Incorrect password

SMS Status Request

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:

User name    Login
PasswordPassword
messageIdMessage identifier received in the response to submit
commandRequest type. Must be set to “query” value

All parameters are obligatory.

Response format:

In the case of successful processing, status in the header of the HTTP response is 200 OK.

The response body contains one of the following possible values:

ENROUTEThe message is in the routing stage.
SENTThe message is delivered to the SMSC.
DELIVRDThe message is delivered to the subscriber.
EXPIREDThe message storage period expired.
DELETEDThe message was deleted.
UNDELIVThe message can not be delivered.
ACCEPTDThe message is accepted by SMSC.
UNKNOWNUnknown message status.
REJECTDThe message was rejected by SMSC.

Response sample:

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
{"status":"DELIVRD"}

Status can be requested within 48 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"}

In case of an incorrect status request (for example, 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 Request
Content-Type: text/html; charset=UTF-8
Unknown username

In case of an incorrect password, the HTTP status is 401 Unauthorized. The response body contains the string describing the reason for rejection.

HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=UTF-8
Incorrect password

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.