Specification

SENDLY SMS API

Specification v1.2

The SENDLY SMS API works by transmitting messages over the HTTP protocol. Two mutually exclusive modes are available for handling SMS messages: SMS API and 3CX API

1. SMS API

1.1 Sending a message

This is the default API mode, intended for use with applications that support REST API. The following endpoint is available for sending SMS:

POST https://api.sendly.link/api/sms

Authorization: Bearer token
Expected content type: application/json

Request body fields:

Field	Data type	Description
`from`	Numeric string, minimum 9 characters, maximum 11 characters (optional field)	The virtual mobile number in SENDLY
`to`	Numeric string, minimum 9 characters, maximum 11 characters	Destination mobile number
`body`	String, minimum 1 character	Message content

Example request:

curl -X POST https://api.sendly.link/api/sms \
     -H "Authorization: Bearer TWOJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "from": "48732129000",
           "to": "48732129001",
           "body": "Test SENDLY"
         }'

The token can be generated and downloaded from the client panel. Alternatively, the token can be obtained through customer support.

Possible responses:

200 – the message has been accepted for sending

Response body:

Field	Data type	Description
`message_id`	String	Unique message identifier (16 hex characters)

Example response:

{"message_id":"a906cff7719bd889"}

Possible error responses:

403 – authorization problem
422 – data validation problem
429 – Rate limit exceeded

In case of errors, the response body may contain one or more of the fields described in the table below:

Field	Data type	Description
`errors.token`	Array of strings	Description of the error related to the provided access token
`errors.from`	Array of strings	Description of the error related to the source number
`errors.to`	Array of strings	Description of the error related to the destination number
`errors.body`	Array of strings	Description of the error related to the message body

Example response:

{"errors":{"token":["Invalid token"]}}

Outgoing messages are encoded in UCS-2 and split every 60 characters. Optionally, it is possible to send SMS in GSM7 encoding with a limit of a single message with a maximum length of 160 characters. This option can be enabled in the client panel or by submitting a request to customer support.

1.2 Sending a message to multiple numbers

This is an API method that allows sending the same message to multiple numbers. Enabling this feature for an access token happens exclusively through contact with customer support. The following endpoint is available:

POST https://api.sendly.link/api/sms-multi

Authorization: Bearer token
Expected content type: application/json

Request body fields:

Field	Data type	Description
`from`	Numeric string, minimum 9 characters, maximum 11 characters (optional field)	The virtual mobile number in SENDLY
`to`	Array of numeric strings, minimum 9 characters, maximum 11 characters, minimum 1 element, maximum 100 elements	Destination mobile numbers
`body`	String, minimum 1 character	Message content

Example request:

curl -X POST https://api.sendly.link/api/sms-multi \
     -H "Authorization: Bearer TWOJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "from": "48732129000",
           "to": ["48732129001", "48732129002"],
           "body": "Test SENDLY"
         }'

Validation of the submitted phone numbers follows an “all or nothing” principle – each of the submitted numbers must be a valid Polish mobile number or the entire request will be rejected. The submitted numbers must be unique; submitting duplicate numbers will cause the entire request to be rejected.

Possible responses:

200 – the message has been accepted for sending

Response body:

Field	Data type	Description
`message_ids`	Array of objects	Each returned object contains a “number” field pointing to one of the given destination numbers and “message_id”, which is the identifier of the message accepted for sending

Example response:

{"message_ids":[{"number":"48732129001","message_id":"a906cff7719bd889"}]}

Possible error responses:

403 – authorization problem
422 – data validation problem
429 – Rate limit exceeded

In case of errors, the response body may contain one or more of the fields described in the table below:

Field	Data type	Description
`errors.token`	Array of strings	Description of the error related to the provided access token
`errors.from`	Array of strings	Description of the error related to the source number
`errors.to`	Array of strings	Description of the error related to the destination number
`errors.body`	Array of strings	Description of the error related to the message body

Example response:

{"errors":{"token":["Invalid token"]}}

1.3 Receiving messages

Incoming messages are sent to the webhook specified in the client panel. The webhook can also be provided in a request to customer support. A single delivery attempt will be made. The API request does not follow redirects and does not authenticate to the webhook. The request will originate from the current IP address of the api.sendly.link domain.

Method: POST
Content type: application/json

Request body fields:

Field	Data type	Description
`type`	String	Message type. For an incoming message it takes the value “MESSAGE”
`from`	String	Presentation of the source number. For a message with an overridden number, this field contains the sender ID (nadpis).
`to`	Numeric string	Destination phone number
`body`	String	Message content

Example request body:

{"type":"MESSAGE","from":"48732129000","to":"48732129001","body":"Test sms"}

1.4 Delivery confirmation

If you wish to receive delivery notifications, you must enable this option in the client panel or via a request to customer support. Enabling this option will cause a request to be sent to the specified webhook address. A single notification delivery attempt will be made. The API request does not follow redirects and does not authenticate to the webhook. The request will originate from the current IP address of the api.sendly.link domain.

Method: POST
Content type: application/json

Request body fields:

Field	Data type	Description
`type`	String	Message type. For a status message it takes the value “NOTIFICATION”
`message_id`	String	The message identifier returned after acceptance for sending
`status`	String	DELIVERED for a delivery notification. ERROR for an error notification.

Example request body:

{"type":"NOTIFICATION","message_id":"a906cff7719bd889","status":"DELIVERED"}

2. 3CX SMS API

This version of the API supports sending and receiving messages based on the current specification of the 3CX Phone System. To enable this API, select both options in the client panel: SMS API and 3CX SMS API.

To handle outgoing traffic, you must provide, in the SMS section in 3CX, the token that can be generated in the client panel, and the URL:

https://api.sendly.link/api/tcx

To handle incoming messages, provide in the client panel the webhook available in your 3CX system.

Customer support can also perform the activation; in that case you provide the webhook and a token is sent back in response.