API v1#

In the current version, API v1 supports two communication methods with the server: HTTPS JSON and HTTPS XML. Client applications send their requests using the URL https://smsapi.telekom.sk. All communication is encrypted via HTTPS.

To use any of the API interfaces, you must have at least one API key defined. For each API key, you also need to configure a list of IP addresses from which API requests are allowed. API requests are set to use the POST method by default. If you want to use the GET method, this must be explicitly enabled for the given API key, which is recommended only in necessary cases.

Base URL for API communication#

Communication with the API is performed by sending POST (GET) requests to the base URL below:

JSONXML

https://smsapi.telekom.sk/json

https://smsapi.telekom.sk/xml

Each endpoint is specified as a relative path to this base URL. For example, for authentication (/auth), the resulting JSON URL will be:

https://smsapi.telekom.sk/json/auth

auth function#

Method: POST, GET
Endpoint: /auth

The auth function is used for user authentication.
The required parameter for authentication is token, which is an API key generated in the web application. The result of authentication is a session_id, which is required for sending any further API requests (sending SMS, verification, etc.). The application also stores this session_id in an encrypted cookie. The validity of both sessions is 15 minutes of inactivity. If the API client does not support storing session_id or cookies, all authentication data must be sent with every request.

* - required parameter

Parameter	Type	Description
*token	string	Generated API key

Example POST request:

JSONXML

URL: https://smsapi.telekom.sk/json/auth

Request body:

{
  "token": "****************************************************************"
}

URL: https://smsapi.telekom.sk/xml/auth

Request body:

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <token>****************************************************************</token>
</request>

If authentication is successful, the response is returned in the following format:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "session_id": "a1da7970-5464-11e4-867e-9d647178712c"
}

<?xml version="1.0" encoding="UTF-8" ?>
 <response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <session_id>a1da7970-5464-11e4-867e-9d647178712c</session_id>
</response>

In case of errors, an error response is returned (example):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Access from IP address 1.2.3.4 is not allowed",
        "code": "IP_NOT_ALLOWED"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <result>
        <status>error</status>
        <description>Access from IP address 1.2.3.4 is not allowed</description>
        <code>IP_NOT_ALLOWED</code>
    </result>
</response>

ping function#

Method: POST, GET
Endpoint: /ping

As mentioned during authentication, you obtain a session_id which is valid for 15 minutes in case of inactivity. If you need to continue working with the API under the same session_id, you can use the ping function. This function is used to refresh the lifetime of the session_id before it expires.

* - required parameter

Parameter	Type	Description
*session_id	string	Session ID

Example POST request:

JSONXML

URL: https://smsapi.telekom.sk/json/ping

Request body:

{
  "session_id": "92f84490-1f89-11f0-a652-9ba39c6bc33b"
}

URL: https://smsapi.telekom.sk/xml/ping

Request body:

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <session_id>92f84490-1f89-11f0-a652-9ba39c6bc33b</session_id>
</request>

If the request is successful, the response is returned in the following format:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
</response>

In case of errors, an error response is returned (example):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Session was not found or has expired",
        "code": "SESSION_NOT_FOUND"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <result>
        <status>error</status>
        <description>Session was not found or has expired</description>
        <code>SESSION_NOT_FOUND</code>
    </result>
</response>

send_message function#

Method: POST, GET
Endpoint: /send_message

This function is used to send SMS messages and requires/supports the following input parameters:

* - required parameter

Parameter	Type	Description
*to	string	Recipient phone number in `4219xxxxxxxx` format for SMS. To prioritize sending an RCS message, use `+4219xxxxxxxx` or `09xxxxxxxx`.
*text	string	Text of the message.
*token or session_id	string	API token obtained from the web application or session_id obtained from the auth function.
from	string	Sender number or text identifier. If not defined, the message is sent from the number assigned to the account.
callback	bool	true(default) - calls the callback URL defined in API key settings to send message delivery status false - Delivery status of the message will not be sent Any value except false, 0, "0", or "" is treated as true.
delivery_time	string	[timestamp] Time when the message should be sent, format YYYY-MM-DD HH:MM:SS.
priority	integer	SMS priority: 1 (Low), 2 (Standard), 3 (High). (Default - 2).
validity	integer	SMS validity period in minutes. If the SMS is not sent to SMSC within this time, it will be removed from the queue. Allowed values: 1-1440. (Default - 1440 minutes).
unicode	bool	false - sends as standard GSM 7-bit. If the message contains diacritics, they will be removed true - sends as Unicode [UTF-16] If not defined, encoding is detected automatically. Any value except false, 0, "0", or "" is treated as true.
type	string	standard(default) - standard message flash - SMS displayed immediately upon receipt
groupId	integer	ID of the cadence group through which the SMS will be sent.

Example POST request:

JSONXML

URL: https://smsapi.telekom.sk/json/send_message

Request body:

{
    "to": "421XXXXXXXXX",
    "session_id": "92f84490-1f89-11f0-a652-9ba39c6bc33b",
    "text": "Text that will be displayed to the recipient",
    "unicode": false // This parameter ensures automatic removal of diacritics from the message
}

URL: https://smsapi.telekom.sk/xml/send_message

Request body:

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <to>421XXXXXXXXX</to>
    <session_id>92f84490-1f89-11f0-a652-9ba39c6bc33b</session_id>
    <text>Text that will be displayed to the recipient</text>
    <unicode>false</unicode> <!-- This parameter ensures automatic removal of diacritics from the message -->
</request>

If the message is sent successfully, the response is returned in the following format:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "message_count": 1,
    "messages": [
        {
            "status": "success",
            "code": "OK",
            "description": "",
            "message_id": 100427,
            "parts": 1
        }
    ]
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <messages count="1">
        <message id="100427">
            <status>success</status>
            <code>OK</code>
            <description></description>
        </message>
    </messages>
</response>

In case of errors, an error response is returned (example):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Relácia nebola nájdená alebo expirovala",
        "code": "SESSION_NOT_FOUND"
    }
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>error</status>
        <description>Relácia nebola nájdená alebo expirovala</description>
        <code>SESSION_NOT_FOUND</code>
    </result>
</response>

If the request was accepted successfully but some messages could not be sent (example with a specific error):

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "message_count": 1,
    "messages": [
        {
            "status": "success",
            "code": "OK",
            "description": "",
            "message_id": 100427,
            "parts": 1
        }
    ]
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <messages count="2">
        <message id="100427">
            <status>success</status>
            <code>OK</code>
            <description></description>
        </message>
    </messages>
</response>

check_message function#

Method: POST, GET
Endpoint: /check_message

This function is used to verify the message status (delivery status) and supports the following parameters.

* - required parameter

Parameter	Type	Description
*token or session_id	string	API token or session_id returned by the auth method.
*message_id	string	Message ID generated by the send_message function

Example POST request:

JSONXML

URL: https://smsapi.telekom.sk/json/check_message

Request body:

{
    "message_id":883315048,
    "session_id":"d3ccd370-114f-11f0-a1d1-0bfd5e3a9b39"
}

URL: https://smsapi.telekom.sk/xml/check_message

Request body:

<request>
    <message_id>883315048</message_id>
    <session_id>d3ccd370-114f-11f0-a1d1-0bfd5e3a9b39</session_id>
</request>

If verification is successful:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "message_id": "154786",
    "status": "Delivered",
    "code": "DELIVERED",
    "deliveryDateTime": "2017-01-01 10:45:00" // Timestamp format or empty string if the message has not yet been delivered
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <message>
        <status>Delivered</status>
        <code>DELIVERED</code>
        <deliveryDateTime>2017-01-01 10:45:00</deliveryDateTime> <!-- Timestamp format or empty string if the message has not yet been delivered. -->
    </message>
</response>

In case of an error (example):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Session was not found or has expired",
        "code": "SESSION_NOT_FOUND"
    }
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>error</status>
        <description>Session was not found or has expired</description>
        <code>SESSION_NOT_FOUND</code>
    </result>
</response>

Status parameter values

code	status	Description
UNSENT	Not sent	The message has not yet been processed.
SCHEDULED	Scheduled	The message is scheduled for later delivery.
QUEUED	Queued	The message has been accepted and is waiting to be sent.
SENDING	Sending	The message is currently being sent.
SENT	Sent	The message was sent to the target platform (SMS Center, RBM, Viber).
DELIVERED	Delivered	The message was delivered to the recipient.
EXPIRED	Expired	The delivery timeout has expired.
DELETED	Deleted	The message was removed from the delivery queue.
UNDELIVERABLE	Undeliverable	The message cannot be delivered.
DENIED	Denied	The message was rejected by the target platform.
IN_GROUP	In group	The message is assigned to a cadence group.
READ	Read	The message has been read.
PROCESSING	Processing	The message is currently being processed.
ERROR	Error	The message cannot be sent due to an error. The system will retry delivery up to 5 times within 60 minutes.
UNKNOWN	Unknown	The message was sent, but the delivery status cannot be determined.

sms-groups function#

Method: POST, GET
Endpoint: /sms-groups

This function is used to retrieve a list of all SMS cadence groups.

* - required parameter

Parameter	Type	Description
*token or session_id	string	API token or session_id returned by the auth method.
limit	integer	Number of records to be returned.
startFrom	integer	Returns records starting from the specified value.

Example POST request:

JSONXML

URL: https://smsapi.telekom.sk/json/sms-groups

Request body:

{
    "token": "****************************************************************",
    "limit": 5,
    "startFrom": 5
}

URL: https://smsapi.telekom.sk/xml/sms-groups

Request body:

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <token>****************************************************************</token>
    <limit>5</limit>
    <startFrom>5</startFrom>
</request>

If the request is successful, the response is returned in the following format:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    }
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <groups count="1">
        <number>
            <id>1000</id> <!-- Group ID -->
            <name>success</name> <!-- Group name -->
            <isPaused>false</isPaused> <!-- Sending paused -->
            <note>Text</note> <!-- Note -->
        </number>
    </groups>
</response>

In case of errors, an error response is returned (example):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Session was not found or has expired",
        "code": "SESSION_NOT_FOUND"
    }
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>error</status>
        <description>Session was not found or has expired</description>
        <code>SESSION_NOT_FOUND</code>
    </result>
</response>

check_phone_number function#

Method: POST, GET
Endpoint: /check_phone_number

This function is used to verify the existence of a phone number and its operator.

* - required parameter

Parameter	Type	Description
*token or session_id	string	API token or session_id returned by the auth method.
*phone_number	string	Phone number

Example POST request:

JSONXML

URL: https://smsapi.telekom.sk/json/check_phone_number

Request body:

{
    "phone_number":"0900000001",
    "token": "****************************************************************"
}

URL: https://smsapi.telekom.sk/xml/check_phone_number

Request body:

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <phone_number>0900000001</phone_number>
    <token>****************************************************************</token>
</request>

If verification is successful, the response is returned in the following format:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "exists": true,
    "operator": "Telekom"
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <phone_number>
        <exists>false</exists>
        <operator>Telekom</operator>
    </phone_number>
</response>

In case of errors, an error response is returned (example):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Session was not found or has expired",
        "code": "SESSION_NOT_FOUND"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <result>
        <status>error</status>
        <description>Session was not found or has expired</description>
        <code>SESSION_NOT_FOUND</code>
    </result>
</response>

Delivery status callback#

Example callback:

{
  "delivery": {
    "status": "DELIVERED",
  },
  "messageId": 991003276,
  "channel": "sms",
  "messageParts": 1,
  "type": "dsn",
  "timestamp": "2025-10-02T08:31:39.825Z"
}

Properties description

Property	Type	Description
delivery.status	string	Message status. Possible values are described below
messageId	integer	Message ID
channel	string	Channel through which the message was sent (sms, rcs)
messageParts	integer	Number of parts the message was split into
type	string	Callback type (dsn, postback)
timestamp	string	Timestamp in ISO 8601 format

Possible values of status property:

Status	Description
QUEUED	The message has been accepted and is waiting to be sent
SENDING	The message is currently being sent
SENT	The message was sent to the SMS center
DELIVERED	The message was delivered to the recipient
EXPIRED	The delivery time limit has expired
UNDELIVERABLE	The message cannot be delivered
DENIED	The message was rejected by the SMS center
ERROR	The message cannot be sent due to an error. The system will retry delivery up to 5 times within 60 minutes
UNKNOWN	The message was sent, but the delivery status cannot be determined