API v2#

Základná URL pre komunikáciu s API v2#

Komunikácia s API v2 prebieha posielaním POST požiadaviek na nižšie uvedenú url:

https://smsapi.telekom.sk/v2

Funkcia message#

Metóda: POST
Endpoint: /message

Pre autentifikáciu je používaná HTTP hlavička X-API-KEY, ktorej hodnotu je potrebné nastaviť na vygenerovaný API kľúč
Pre odoslanie správy je potrebné vytvoriť POST požiadavku v nasledujúcom tvare:

curl -X POST\
-H "X-API-KEY: {{VÁŠ_API_KĽÚČ}}"\
-H "Accept: application/json"\
-H "Content-Type: application/json"\
-d '{
    -- Telo požiadavky, podrobne popísané nižšie --
    }'
"https://smsapi.telekom.sk/v2/messages"

Textová správaOdoslanie súboruCardCarousel

{
    "recipients": [
        {
            "phone": "+421XXXXXXXXX",
            "externalId": "8e9b404f-fd1d-4633-926c-13c286514427"
        }
    ],
    "channels": [
        {
            "type": "rcs",
            "ttl": 30
        },
        {
            "type": "sms"
        }
    ],
    "deliveryTime": "2025-09-25 08:00:00",
    "priority": 2,
    "groupId": 1,
    "callbackUrls": [
        {
            "url": "https.zakaznik.app/callback",
            "types": [
                "postback",
                "dsn"
            ]
        }
    ],
    "rcs": {
        "text": "Prajete si dostávať správy z tohto čísla?",
        "suggestions": [
            {
                "reply": {
                    "text": "Áno",
                    "postbackData": "yes"
                }
            },
            {
                "reply": {
                    "text": "Nie",
                    "postbackData": "no"
                }
            }
        ]
    },
    "sms": {
        "text": "Fallback SMS, pokiaľ príjemca nie je dostupný pre RCS"
    }
}

{
    "recipients": [
        {
            "phone": "+421XXXXXXXXX",
            "externalId": "8e9b404f-fd1d-4633-926c-13c286514427"
        }
    ],
    "channels": [
        {
            "type": "rcs",
            "ttl": 30
        },
        {
            "type": "sms"
        }
    ],
    "deliveryTime": "2025-09-25 08:00:00",
    "priority": 2,
    "groupId": 1,
    "callbackUrls": [
        {
            "url": "https.zakaznik.app/callback",
            "types": [
                "postback",
                "dsn"
            ]
        }
    ],
    "rcs": {
        "file": {
            "url": "https://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"
        },
        "suggestions": [
            {
                "action": {
                    "text": "Vyberte polohu",
                    "postbackData": "test_text",
                    "fallbackUrl": "https://google.com",
                    "shareLocation": {}
                }
            }
        ]
    },
    "sms": {
        "text": "Fallback SMS, pokiaľ príjemca nie je dostupný pre RCS"
    }
}

{
    "recipients": [
        {
            "phone": "+421XXXXXXXXX",
            "externalId": "8e9b404f-fd1d-4633-926c-13c286514427"
        }
    ],
    "channels": [
        {
            "type": "rcs",
            "ttl": 30
        },
        {
            "type": "sms"
        }
    ],
    "deliveryTime": "2025-09-25 08:00:00",
    "priority": 2,
    "groupId": 1,
    "callbackUrls": [
        {
            "url": "https.zakaznik.app/callback",
            "types": [
                "postback",
                "dsn"
            ]
        }
    ],
    "rcs": {
        "standaloneCard": {
            "cardOrientation": "VERTICAL",
            "thumbnailImageAlignment": "LEFT",
            "cardContent": {
                "title": "StandaloneCard Titulka",
                "description": "StandaloneCard Popis",
                "media": {
                    "height": "TALL",
                    "contentInfo": {
                        "fileUrl": "https://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"
                    }
                },
                "suggestions": [
                    {
                        "reply": {
                            "text": "Áno",
                            "postbackData": "yes"
                        }
                    },
                    {
                        "reply": {
                            "text": "Nie",
                            "postbackData": "no"
                        }
                    }
                ]
            }
        }
    },
    "sms": {
        "text": "Fallback SMS, pokiaľ príjemca nie je dostupný pre RCS"
    }
}

{
    "recipients": [
        {
            "phone": "+421XXXXXXXXX",
            "externalId": "8e9b404f-fd1d-4633-926c-13c286514427"
        }
    ],
    "channels": [
        {
            "type": "rcs",
            "ttl": 30
        },
        {
            "type": "sms"
        }
    ],
    "deliveryTime": "2025-09-25 08:00:00",
    "priority": 2,
    "groupId": 1,
    "callbackUrls": [
        {
            "url": "https.zakaznik.app/callback",
            "types": [
                "postback",
                "dsn"
            ]
        }
    ],
    "rcs": {
        "carouselCard": {
            "cardWidth": "MEDIUM",
            "cardContents": [
                {
                    "title": "Google Card",
                    "description": "Krátky popis karty",
                    "media": {
                        "height": "SHORT",
                        "contentInfo": {
                            "fileUrl": "https://services.google.com/fh/files/misc/google_g_icon_download.png"
                        }
                    },
                    "suggestions": [
                        {
                            "action": {
                                "text": "Otvoriť Google",
                                "postbackData": "test_text",
                                "fallbackUrl": "https://google.com",
                                "openUrl": {
                                    "url": "https://google.com"
                                }
                            }
                        }
                    ]
                },
                {
                    "title": "Instagram card",
                    "description": "Krátky popis karty",
                    "media": {
                        "height": "TALL",
                        "contentInfo": {
                            "fileUrl": "https://static.xx.fbcdn.net/rsrc.php/v4/yx/r/tBxa1IFcTQH.png"
                        }
                    },
                    "suggestions": [
                        {
                            "action": {
                                "text": "Zavolať podporu",
                                "postbackData": "call_support",
                                "fallbackUrl": "https://instagram.com",
                                "dial": {
                                    "phoneNumber": "+421YYYYYYYYY"
                                }
                            }
                        }
                    ]
                }
            ]
        }
    },
    "sms": {
        "text": "Fallback SMS, pokiaľ príjemca nie je dostupný pre RCS"
    }
}

Popis jednotlivých parametrov

Parameter	Typ	Povinnosť	Popis
recipients[]	array	✔️	Zoznam príjemcov správy
channels[]	array	✔️	Zoznam kanálov pre odoslanie správy
deliveryTime	string (datetime)	❌	Dátum a čas odoslania správy
priority	integer	❌	Priorita odosielania správy. Možné hodnoty parametra: 1 (Nízka) 2 (Štandardná) - Default 3 (Vysoká)
groupId	integer	❌	ID kadenčnej skupiny, prostredníctvom ktorej bude správa odoslaná
callbackUrls	array	❌	Callback url, ktoré budú volané pri zmene stavu/spätnej správe
sms	objekt	ℹ️	Objekt s informáciami o SMS
rcs	objekt	ℹ️	Objekt s informáciami o RCS

_{ℹ️ - Parametre sms a rcs sú povinné pokiaľ je tento typ správy zadefinovaný v parametri channels.}

recipients#

Parameter recipients obsahuje zoznam príjemcov pre danú správu. Každá správa musí obsahovať aspoň jedného prijímateľa.

Názov parametra	Typ parametra	Povinnosť	Popis
phone	string	✔️	Telefónne číslo príjemcu v tvare +421XXXXXXXXX
externalId	string	❌	Slúži na identifikáciu správy zo strany zákazníka. Odosiela sa pri úspešnom prijatí požiadavky a pri callbacku.

Príklad

[
    {
        "phone": "+421XXXXXXXXX",
        "externalId": "8e9b404f-fd1d-4633-926c-13c286514427"
    },
    {
        "phone": "+421YYYYYYYYY",
        "externalId": "caf87152-2b04-4f67-a97a-963efc3f0c21"
    }
],

channels#

Parameter channels obsahuje zoznam s informáciou o kanáloch pre doručenie správy. Poradie kanálov v zozname určuje ich prioritu. Každá správa musí mať aspoň jeden kanál, prostredníctvom ktorého bude odoslaná.

Názov parametra	Typ parametra	Povinnosť	Popis
type	string	✔️	Telefónne číslo príjemcu v tvare +421XXXXXXXXX
ttl	integer	❌	Počet sekúnd, po ktorých sa správa označí ako nedoručiteľná a správa následne môže byť odoslaná cez nasledujúci kanál.

Príklad

[
    {
        "type": "rcs",
        "ttl": 5
    },
    {
        "type": "sms",
        "ttl": 30
    }
],

deliveryTime#

Voliteľný parameter pre určenie času doručenia správy v jednom z nasledujúcich formátov:

Lokalizovaný formát: "YYYY-MM-DD HH:MM:SS"
Napr.:
- 2025-09-25 08:00:00
ISO 8601 formát: "YYYY-MM-DDTHH:MM:SS±[hh:mm]"
Napr.:
- 2025-09-25 06:00:00Z (UTC)
- 2025-09-25T08:00:00+02:00 (CEST)

Pokiaľ parameter nie je určený alebo je jeho hodnota v minulosti, správa sa odošle okamžite.

callbackUrls#

Zoznam adries, ktoré budú volané pri zmene stavu doručenia správy alebo pri odpovedi príjimateľa.

Názov parametra	Typ parametra	Povinnosť	Popis
url	string	✔️	Url, na ktorú príde požiadavka pri zmene stavu alebo odpovedi
types	array - string	✔️	Typ callbacku. Podporované sú 2 hodnoty: dsn - informácia o zmene stavu doručenia správy postback - odpoveď na správu pomocou suggestions

Príklad

[
    {
        "url": "https://zakaznik.app/postback",
        "types": [
            "postback",
        ]
    },
    {
        "url": "https://zakaznik.app/dns",
        "types": [
            "dns",
        ]
    }
]

sms#

Obsahuje informácie potrebné pre odoslanie SMS.

Názov parametra	Typ parametra	Povinnosť	Popis
text	string	✔️	Text správy. Maximálna dĺžka správy závisí od použitého kódovania
from	string	❌	Číslo alebo textový identifikátor, ktorý bude zobrazený u prijímateľa. Pokiaľ tento parameter nebude definovaný, použije sa primárne číslo priradené účtu.
unicode	string	❌	V prípade, že tento parameter nie je definovaný, aplikácia odošle správu na základe automatickej detekcie kódovania. true pošle ako unicode[UTF-16] false pošle ako GSM-7

rcs#

Informácie potrebné pre odoslanie RCS správy

Názov parametra	Typ parametra	Povinnosť	Popis
file	objekt	ℹ️	Objekt s informáciami o súbore.
text	string	ℹ️	Text správy
standaloneCard	objekt	ℹ️	Objekt s definíciou mediálnej karty, ktorá sa zobrazí prijímateľovi
carouselCard	objekt	ℹ️	Carousel, ktorý môže obsahovať rôzne vizuálne prvky alebo médiá.
suggestions[]	array	❌	Návrhy na odpoveď vo forme tlačidiel, ktoré sa zobrazia pod správou.

_{ℹ️ - Povinné je použiť presne jeden z týchto parametrov.}

rcs.file#

rcs.standaloneCard#

Názov parametra	Typ parametra	Povinnosť	Popis
cardOrientation	string (enum)	✔️	Orientácie karty. Môže mať 2 hodnoty: VERTICAL- vertikálne rozloženie HORIZONTAL - horizontálne rozloženie
thumbnailImageAlignment	string (enum)	❌	Zarovnanie náhľadu obrázka pre karty s horizontálnym rozložením. Môže mať 2 hodnoty: LEFT- zarovnanie náhľadu doľava RIGHT - zarovnanie náhľadu doprava
cardContent	objekt	✔️	Obsah karty

Príklad

{
    "cardOrientation": "HORIZONTAL",
    "thumbnailImageAlignment": "RIGHT",
    "cardContent": {
        "title": "Slovak Telekom",
        "media": {
            "contentInfo": {
                "fileUrl": "https://www.telekom.sk/documents/10179/19896051/telekom-logo.png"
            }
        },
        "suggestions": [
            {
                "action": {
                    "text": "Zavolať podporu",
                    "postbackData": "call_support",
                    "dial": {
                        "phoneNumber": "+421800123456"
                    }
                }
            }
        ]
    }
}

rcs.carouselCard#

Názov parametra	Typ parametra	Povinnosť	Popis
cardWidth	string (enum)	✔️	Šírka jednotlivých kariet. Môže mať 2 hodnoty: SMALL- 120 DP. Pokiaľ je šírka karty small nie je možné použiť media s výškou TALL MEDIUM - 232 DP
cardContents[]	array objektov cardContent	✔️	Obsah jednotlivých kariet

Príklad

{
    "cardWidth": "MEDIUM",
    "cardContents": [
        {
            "title": "Predajne Slovak Telekom",
            "media": {
                "height": "TALL",
                "contentInfo": {
                    "fileUrl": "https://www.telekom.sk/documents/10179/19720195/spolupraca.jpg"
                }
            },
            "suggestions": [
                {
                    "action": {
                        "text": "Zobraziť predajne",
                        "postbackData": "open_url_nearby_stores",
                        "fallbackUrl": "https://www.telekom.sk/",
                        "viewLocation": {
                            "query": "Slovak Telekom predajňa"
                        }
                    }
                },
                {
                    "action": {
                        "text": "Zavolať zákaznícku linku",
                        "postbackData": "dial_support",
                        "fallbackUrl": "https://www.telekom.sk/",
                        "dial": {
                            "phoneNumber": "+421800123456"
                        }
                    }
                }
            ]
        },
        {
            "title": "Slovak Telekom",
            "media": {
                "height": "MEDIUM",
                "contentInfo": {
                    "fileUrl": "https://www.telekom.sk/documents/10179/19896051/telekom-logo.png"
                }
            },
            "suggestions": [
                {
                    "action": {
                        "text": "Volania",
                        "postbackData": "open_url_calls",
                        "openUrl": {
                            "url": "https://www.telekom.sk/volania"
                        }
                    }
                },
                {
                    "action": {
                        "text": "Internet",
                        "postbackData": "open_url_internet",
                        "openUrl": {
                            "url": "https://www.telekom.sk/internet"
                        }
                    }
                },
                {
                    "action": {
                        "text": "Televízia",
                        "postbackData": "open_url_tv",
                        "openUrl": {
                            "url": "https://www.telekom.sk/televizia"
                        }
                    }
                },
                {
                    "action": {
                        "text": "Stiahnúť aplikáciu",
                        "postbackData": "open_url_app",
                        "openUrl": {
                            "url": "https://play.google.com/store/apps/details?id=com.telekom.portal"
                        }
                    }
                }
            ]
        }
    ]
}

cardContent#

Slúži na definovanie obsahu, ktorý sa zobrazí na karte.

Názov parametra	Typ parametra	Povinnosť	Popis
title	string	ℹ️	Názov karty. Maximálne 200 znakov
description	string	ℹ️	Popis karty. Maximálne 2000 znakov.
media[]	objekt	ℹ️	Mediálny súbor zobrazený na karte.
suggestions[]	array	❌	Návrhy odpovedí vo forme tlačidiel, ktoré sa zobrazia na karte.

_{ℹ️ - Povinné je použiť aspoň jeden z týchto parametrov.}

cardContent.media#

Mediálny súbor, ktorý sa zobrazí na karte

Názov parametra	Typ parametra	Povinnosť	Popis
height	string (enum)	✔️	Výška zobrazovaného média pri vertikálnom rozložení.
contentInfo	objekt	✔️	Informácie o mediálnom súbore vrátane URL adresy súboru a URL adresy jeho náhľadu.

cardContent.media.height#

Výška zobrazovaného média pri vertikálnom rozložení. Pri samostatnej karte s horizontálnym rozložením nie je výška prispôsobiteľná a toto pole sa ignoruje. Hodnoty:

SHORT - 112 DP.
MEDIUM - 168 DP.
TALL - 264 DP. Nie je možné použiť pre carousel card ak je veľkosť karty nastavená na SMALL.

cardContent.media.contentInfo#

Tento objekt má rovnaké parametre a obmedzenia ako rcs.file

suggestions#

Parameter suggestions je zoznam objektov, ktoré slúžia ako návrhy odpovedí pre prijímateľa. Maximálna dĺžka zoznamu je 11 návrhov.

Tento parameter môže byť nastavený buď na úrovni rcs alebo cardContent. V prípade, že správa RCS obsahuje cardContent, je tento parameter na úrovni rcs ignorovaný.

Suggestion môže nadobúdať 2 typy a to reply alebo action, pričom tieto typy je v zozname možné kombinovať.

Príklad

[
    {
        "reply": {
            "text": "Áno",
            "postbackData": "yes"
        }
    },
    {
        "reply": {
            "text": "Nie",
            "postbackData": "no"
        }
    },
    {
        "action": {
            "text": "Zavolať podporu",
            "postbackData": "call_support",
            "dial": {
                "phoneNumber": "+421800123456"
            }
        }
    }
]

suggestions.reply#

Objekt typu reply slúži ako návrh rýchlej textovej odpovede pre prijímateľa.

Názov parametra	Typ parametra	Povinnosť	Popis
text	string	✔️	Text, ktorý sa prijímateľovi zobrazí ako rýchla odpoveď. Maximálne 25 znakov.
postbackData	string	✔️	Dáta, ktoré sa odošlú na callbackUrl po kliknutí na rýchlu odpoveď

Príklad

{
    "reply": {
        "text": "Áno",
        "postbackData": "yes"
    }
},

suggestions.action#

Objekt typu action slúži pre navrhnutie akcie ako napr. zdieľanie lokácie, návšteva stránky, vytočenie čísla a pod.

Názov parametra	Typ parametra	Povinnosť	Popis
text	string	✔️	Text, ktorý sa zobrazí pri danej akcii. Maximálne 25 znakov
postbackData	string	✔️	Dáta, ktoré sa odošlú na callbackUrl po kliknutí na navhrovnú akciu
fallbackUrl	string	❌	URL adresa, ktorá sa otvorí v prehliadači, ak zariadenie nepodporuje funkciu suggestions
dial	objekt	ℹ️	Otvorí predvolenú aplikáciu na telefonovanie a vloží do nej špecifikované t.č.
viewLocation	objekt	ℹ️	Akcia na zobrazenie polohy v predvolenej mapovej aplikácii na základe zemepisnej šírky a dĺžky alebo dotazu
shareLocation	objekt	ℹ️	Otvorí výber polohy, kde si používateľ môže vybrať lokáciu, ktorú chce odoslať agentovi
openUrl	objekt	ℹ️	Akcia, ktorá otvorí poskytnutú url v predvolenom webovom prehliadači
createCalendarEvent	objekt	ℹ️	Akcia pre vytvorenie udalosti v kalendári

_{ℹ️ - Povinné je použiť presne jeden z týchto parametrov.}

suggestions.action.dial#

Názov parametra	Typ parametra	Povinnosť	Popis
phoneNumber	string	✔️	Telefónne číslo vo formáte +421XXXXXXXXX

Príklad

{
    "action": {
        "text": "Zavolať podporu",
        "postbackData": "call_support",
        "fallbackUrl": "https://instagram.com",
        "dial": {
            "phoneNumber": "+421XXXXXXXXX"
        }
    }
}

suggestions.action.viewLocation#

Názov parametra	Typ parametra	Povinnosť	Popis
latLong	objekt	❌ ℹ️	Objekt ktorý na základe zemepisnej šírky a dĺžky definuje miesto na mape
label	string	❌	Názov miesta, definovaného objektom latLong
query ⚠️	string	❌ ℹ️	Pre predvolené mapové aplikácie, ktoré podporujú funkciu vyhľadávania (vrátane Google Maps), klepnutie na túto navrhovanú akciu spôsobí vyhľadanie miesta v okolí aktuálnej polohy používateľa. Ak je dotaz dostatočne špecifický, môže byť použiťý na určenie akéhokoľvek miesta na svete. Napríklad nastavenie dotazu na Slovak Telekom zobrazí všetky pobočky Slovak Telekom v okolí používateľa. Nastavenie dotazu na Námestie SNP 1, 811 01 Bratislava vyberie túto konkrétnu adresu bez ohľadu na polohu používateľa.

_{ℹ️ - Je povinné použiť presne jeden z týchto parametrov.}
_{⚠️ - Dostupné iba na zariadeniach s Android OS.}

Príklad

{
   "action": {
        "text": "Slovak Telekom",
        "postbackData": "view_location",
        "fallbackUrl": "https://www.telekom.sk/",
        "viewLocation": {
            "query": "Slovak Telekom"
        }
    }
}

suggestions.action.viewLocation.latLong#

Názov parametra	Typ parametra	Povinnosť	Popis
latitude	number	✔️	Zemepisná šírka v stupňoch. Musí byť v rozsahu [-90.0, +90.0]
longitude	number	✔️	Zemepisná dĺžka v stupňoch. Musí byť v rozsahu [-180.0, +180.0]

Príklad

{
    "latitude": 49.16259795554555, 
    "longitude": 19.999893522995347
}

suggestions.action.shareLocation#

Umožňuje užívateľovi poslať polohu vášmu agentovi. Poloha, ktorú užívateľ určí, nemusí byť nutne polohou užívateľa. Táto akcia nemá žiadne povinné ani voliteľné parametre.

suggestions.action.openUrl#

Názov parametra	Typ parametra	Povinnosť	Popis
url	string	✔️	URL adresa, ktorá sa otvorí v predvolenom prehliadači

Príklad

{
    latitude: 49.16259795554555, 
    longitude: 19.999893522995347
}

suggestions.action.createCalendarEvent#

Názov parametra	Typ parametra	Povinnosť	Popis
title	string	✔️	Názov udalosti
description	string	✔️	Popis udalosti
startDateTime	string (date-time)	✔️	Začiatok udalosti
endDateTime	string (date-time)	✔️	Koniec udalosti

Dátum je potrebné zadávať vo formáte ISO 8601: "YYYY-MM-DDTHH:MM:SS±[hh:mm]", napr:

2025-09-25 06:00:00Z (UTC)
2025-09-25T08:00:00+02:00 (CEST)

Príklad

{
    "title": "Názov udalosti",
    "description" : "Popis udalosti",
    "startDateTime": "2025-05-16T14:00:00.00+02:00",
    "endDateTime": "2025-05-16T14:30:00.00+02:00"
}