Dokumentace GoSMS API
https://app.gosms.cz/oauth/v2/token
https://app.gosms.cz/api/v1/
https://app.gosms.cz/api/v1/messages/
https://app.gosms.cz/api/v1/messages/test
https://app.gosms.cz/api/v1/messages/{id}
https://app.gosms.cz/api/v1/messages/{id}/replies
API je zabezpečeno pomocí OAuth2. Abyste mohli posílat zprávy přes API, tak musíte nejprve získat access token. Kromě posílání zpráv můžete využít webhooky pro zjištění doručení zprávy.
Příklad použití GoSMS API můžete stahovat zde
Získání access tokenu
curl -X POST "https://app.gosms.cz/oauth/v2/token" \
-d "client_id=A&client_secret=X&grant_type=client_credentials"
curl "https://app.gosms.cz/oauth/v2/token?client_id=A&client_secret=X&grant_type=client_credentials"
200 - Získaný access token z odpovědi
{
"access_token":"AccessTokenIU78JO",
"expires_in":3600,
"token_type":"bearer",
"scope":"user"
}
Doporučené použití access tokenu při komunikaci s API je v hlavičce
curl "https://app.gosms.cz/api/v1/messages/1" \
-H "Authorization: Bearer AccessTokenIU78JO"
Access token můžete poslat i jako GET parametr
curl "https://app.gosms.cz/api/v1/messages/1?access_token=AccessTokenIU78JO"
Odpověď při použití neplatného access tokenu
{
"error":"access_denied",
"error_description":"The access token provided is invalid."
}
POST https://app.gosms.cz/oauth/v2/token
API je zabezpečeno pomocí OAuth2. Abyste mohli posílat zprávy přes API, tak se musíte nejprve autentizovat a získat access token. Každá organizace v administraci GoSMS zjistí svoje klient id (client_id
) a klient secret (client_secret
).
Doporučuje se získat access token pomocí POST volání, ale může použít i GET (obě varianty byly vždy dostupné, ale dříve byla v dokumentaci ukázka jen s GET).
Request parametry
Parametr | Význam |
---|---|
client_id | klient id, najdete ho v administraci GoSMS |
client_secret | tajné “heslo” |
grant_type | vždy nastavte na client_credentials |
Návratové hodnoty
Kód | Význam |
---|---|
200 OK | Úspěšné získání access tokenu |
400 Bad Request | Neplatné klientské údaje, nebo chybějící grant_type |
Použití tokenu
Získaný access token musíte zaslat s každým Vaším požadavkem na API pomocí:
- v hlavičce
Authorization
- GET parametru
access_token
(teoreticky méně bezpečné)
Chybové stavy
V případě neplatného access tokenu bude API vracet chybovou hlášku access_denied
z OAuth standardu. Příčinou může být
error_description | Význam |
---|---|
The access token provided is invalid | Zadaný access token je neplatný. |
OAuth2 authentication required | V požadavku se ani v Authorization hlavičce ani v GET parametru nevyskytuje access_token |
The access token provided has expired. | Vypršela platnost access_token , je potřeba zažádat o nový token. |
Expirace tokenu
Když vyprší platnost tokenu, tak musíte znovu zažádat o nový token.
Detail organizace
curl "https://app.gosms.cz/api/v1/" \
-H "Authorization: Bearer {token}"
{
"currentCredit": 23.09,
"channels": [
{
"id": 1,
"name": "Název kanálu",
"sourceNumber": "GoSMS"
}
]
}
GET https://app.gosms.cz/api/v1/
Detail organizace vrací aktuální stav kreditu a přehled nastavených komunikačních kanálů. Stav kreditu je vždy záporný, pokud Vaše organice má fakturaci přes tarif.
Jak poslat zprávu
curl -X POST "https://app.gosms.cz/api/v1/messages/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{"message":"Hello","recipients":"111222333","channel":1}'
Vytvoření zprávy, která se začne odesílat za jednu hodinu
{
"message": "Hello World!",
"recipients": ["+420111222333", "Peter"],
"channel": 1,
"expectedSendStart": "now + 1 hour"
}
POST https://app.gosms.cz/api/v1/messages/
Request parametry
Parametr | Typ | Význam |
---|---|---|
message | string | Text zprávy |
recipients | string, pole | Příjemce může být pole čísel, nebo jedno samostatné číslo, viz příjemci |
channel | int | ID komunikačního kanálu |
expectedSendStart | datum | nepovinné datum odeslání zprávy, není vyžadován specifický formát datumu a lze použít i výrazy jako now + hour/day . Pokud nepoužijete datum v relativním formátu, tak doporučujeme použít formát data ISO8601, např. 2014-09-11T07:20:21+0200 . |
Co vrací API
Vrácená odpověď při úspěšném vytvoření zprávy
{
"recipients": {
"invalid": ["Peter"]
},
"link": "api/v1/messages/1"
}
Návratové hodnoty
Kód | Význam |
---|---|
201 Created | Zpráva byla úspěšně zařazena do fronty zpráv k odeslání |
400 Bad Request | Zpráva nelze z nějakého důvodů odeslat, viz chyby |
401 Unauthorized | Nemáte přístup, musíte mít platný access token |
500 Internal Server Error | Zprávu se nepodařilo zařadit do fronty čekajících zpráv (chyba na naší straně) |
Response atributy
Parametr | Typ | Význam |
---|---|---|
recipients | objekt | Objekt s příjemci zprávy |
recipients.invalid | array | Pole čísel na které se zprávu nepodařilo odeslat. |
link | string | Odkaz na detail zprávy |
Chyby při odesílání zprávy
Když API vrátí 400 (application/problem+json):
Zprávu se nedaří odeslat, protože nastal minimálně jeden z níže uvedených důvodů. Podrobnější popis formátu chybových hlášek najdete v dokumentaci chyb API.
- request obsahuje nevalidní JSON
- zvolený komunikační kanál v rámci organizace neexistuje
- zpráva je prázdná
- zvolený komunikační kanál je deaktivovaný,
- zpráva neobsahuje ani jedno číslo, na které lze zprávu odeslat (nevalidní čísla nebo blokovaní příjemci)
- odeslání zprávy je naplánované do minulosti
- nedostatek kreditu k odeslání zpráv
Co když API vrátí 500 (application/problem+json)?
Vaše zpráva je validní, ale na naší straně se zprávu nepodařilo odeslat, zkuste požadavek opakovat.
Příjemci zprávy
Zaslání zprávy jednomu nebo více číslům
{
"recipients": "+420111222333"
}
{
"recipients": ["+420111222333", "+420111222444"]
}
Jak zaslat všem všem kontaktům ze skupiny v adresáři
{
"recipients": {
"groups": "Práce"
}
}
Skupinám, kontaktům i číslům mimo kontaktní adresář
{
"recipients": {
"groups": ["Doma", "Práce"],
"contacts": ["+420111222333"],
"otherNumbers": ["+420111222444"]
}
}
Všechny níže uvedené příklady se týkají atributu recipients
při zaslání zprávy přes API. Ostatní položky jsou pro zjednodušení odstraněny.
Request parametry
Parametr | Typ | Význam |
---|---|---|
recipients | string, pole, objekt | Buď přímo čísla příjemců, nebo objekt s využitím kontaktů z adresáře |
groups | string, pole | Jména skupin z adresáře |
contacts | string, pole | Čísla kontaktů z Vašeho adresáře |
otherNumbers | string, pole | Čísla mimo kontaktní adresář |
Co když chci zaslat zprávu jen jednomu kontaktu, skupině… Musím poslat pole?
Ne. U všech příjemců můžete použít zjednodušení, že místo pole čísel/skupin pošlete pouze jeden textový řetězec.
Můžu poslat více čísel/skupin jako jeden řetězec?
Ne. Pokud chcete zaslat zprávu více číslům/skupinám, tak každé číslo/skupiny vložte do pole. Pokud byste zaslali např.
recipients: "+420111222333,+420111222444"
tak by API vrátilo chybu, že zpráva neobsahuje žádného platného příjemce, protože by bralo vstup +420111222333,+420111222444
jako jedno číslo!
Blokování příjemců
GoSMS umožňuje blokování odesílání zpráv na konkrétní čísla. Blokování realizujeme vždy na přání konkrétního příjemce. V praxi to znamená, že pokud odešlete zprávu na telefonní číslo, které je vedené jako zablokované, nebude na něj zpráva odeslána.
úspěšné odeslání zprávy
Zablokovaná čísla najdete v odpovědi API spolu s nevalidními čísly v recipients.invalid
.
neúspěšné odeslání zprávy
Zablokovaná čísla najdete v poli chyb jako Blocked recipients: +420....
Testovací vytvoření zprávy bez odeslání
curl -X POST "https://app.gosms.cz/api/v1/messages/test" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{"message":"Češi","recipients":"+421555222333","channel":1}'
Pokud je zpráva odesílatelná, tak API vrátí neúplný detail zprávy
{
"messageType": "SMS",
"message": {
"fulltext": "Češi",
"parts": ["Češi"]
},
"channel": 1,
"stats": {
"price": 1.452,
"hasDiacritics": true,
"smsCount": 1,
"messagePartsCount": 1,
"recipientsCount": 1,
"numberTypes": {
"czMobile": 0,
"czOther": 0,
"sk": 1,
"pl": 0,
"hu": 0,
"ro": 0,
"other": 0
}
},
"sendingInfo": {
"status": "CONCEPT",
"expectedSendStart": "2015-08-10T21:23:00+02:00",
"sentStart": "",
"sentFinish": ""
},
"reply": {
"hasReplies":true,
"repliesCount":0
}
}
POST https://app.gosms.cz/api/v1/messages/test
Otestuje, kolik bude zpráva stát, zda obsahuje diakritiku, kolik bude mít částí, kolik SMS půjde na Slovensko, … Testovací metoda vrací vrací stejné chyby a při úspěchu detail zprávy jako při skutečném odesílání. Z detailu jsou pouze odstraněny údaje, které vzniknou až při odeslání (příjemci recipients
, informace o doručení delivery
a odkazy links
).
Smazání zprávy
curl -X DELETE "https://app.gosms.cz/api/v1/messages/{id}" \
-H "Authorization: Bearer {token}"
DELETE https://app.gosms.cz/api/v1/messages/{id}
Request parametry
Parametr | Typ | Význam |
---|---|---|
id | int | ID zprávy, které není přímo vraceno při vytvoření zprávy, protože jako unikátní identifikátor slouží URL adresa (např. /api/v1/messages/1 ) |
Návratové hodnoty
Kód | Význam |
---|---|
200 OK | Zpráva byla smazána |
401 Unauthorized | Nemáte přístup, musíte mít platný access token |
403 Forbidden | Ke zprávě nelze přistoupit přes API (přístup lze nastavit u kanálu v samoobsluze) |
404 Not Found | Zpráva v rámci organizace neexistuje |
Detail zprávy
curl "https://app.gosms.cz/api/v1/messages/1"
{
"messageType": "SMS",
"message": {
"fulltext": "Hello World!",
"parts": ["Hello World!"]
},
"recipients": {
"sent": ["+420111222333", "+420111222444"],
"notSent": ["+420111222555"],
"invalid": ["+420111222666"]
},
"channel": 1,
"stats": {
"price": 0.739,
"hasDiacritics": false,
"smsCount": 1,
"messagePartsCount": 1,
"recipientsCount": 1,
"numberTypes": {
"czMobile": 1,
"czOther": 0,
"sk": 0,
"pl": 0,
"hu": 0,
"ro": 0,
"other": 0
}
},
"sendingInfo": {
"status": "IN_PROGRESS|FAILED|SENT",
"expectedSendStart": "2014-12-24T21:23:00+02:00",
"sentStart": "2014-12-24T21:23:00+02:00",
"sentFinish": "2014-12-24T21:23:01+02:00"
},
"delivery": {
"isDelivered": false,
"smsCount": 3,
"deliveredSmsCount": 1,
"recipients": {
"delivered": {
"+420111222333": "2014-12-24T21:23:00+02:00"
},
"undelivered": {
"+420111222444": "2014-12-24T21:24:00+02:00"
},
"delivering": {
"+420111222555": {
"deliveredCount": 0,
"undeliveredCount": 0,
"deliveringCount": 1
}
}
}
},
"reply": {
"hasReplies": true,
"repliesCount": 0
},
"links": {
"self": "api/v1/messages/1",
"replies": "api/v1/messages/1/replies"
}
}
GET https://app.gosms.cz/api/v1/messages/{id}
Po úspěšném vytvoření zprávy v JSON odpovědi najdete link
k detailu zprávy. Ten samý odkaz najdete i na detailu zprávy v links
v self
. Neukládajte ID zprávy, ale odkaz :) Pokud listujete zprávami v GoSMS samoobsluze, tak id zprávy uvidíte v url. K Vaším zprávám můžete přistoupit přes API, i pokud jste je odeslali v samoobsluze.
Request parametry
Parametr | Typ | Význam |
---|---|---|
id | int | ID zprávy, které není přímo vraceno při vytvoření zprávy, protože jako unikátní identifikátor slouží URL adresa (např. /api/v1/messages/1 ) |
Návratové hodnoty
Kód | Význam |
---|---|
200 OK | Zpráva v organizaci existuje |
401 Unauthorized | Nemáte přístup, musíte mít platný access token |
403 Forbidden | K detailu zprávy nelze přistoupit přes API (přístup lze nastavit u kanálu v samoobsluze) |
404 Not Found | Zpráva v rámci organizace neexistuje |
Statistiky
Parametr | Význam |
---|---|
price | cena včetně DPH v Kč |
hasDiacritics | zda zpráva obsahuje diakritiku |
smsCount | kolik bylo celkově odesláno SMS (odpovídá počtu příjemců krát počet částí zprávy) |
messagePartsCount | na kolik částí byla zpráva rozdělena (velikost jedné SMS závisí na tom, zda má diakritiku) |
recipientsCount | počet unikátních příjemců, kterým byla zpráva odeslána |
numberTypes | počet příjemců rozdělený podle typu telefonních čísel |
Typy čísel
Počty se správně zobrazí až po interním zpracování zprávy. Může nastat situace, že několik sekund po vytvoření bude počet příjemců u každého typu roven 0.
Parametr | Význam |
---|---|
czMobile | mobilní sítě v ČR |
czOther | ostatní sítě v ČR (pevná linka, …) |
sk | slovenská čísla |
pl | polská čísla |
hu | maďarská čísla |
ro | rumunská čísla |
other | ostatní země |
Zjištění doručení zprávy
{
"delivery": {
"isDelivered": false,
"smsCount": 2,
"deliveredSmsCount": 1,
"recipients": {
"delivered": {
"+420111222333": "2014-12-24T21:23:00+02:00"
},
"undelivered": [],
"delivering": {
"+420111222555": {
"deliveredCount": 0,
"undeliveredCount": 0,
"deliveringCount": 1
}
}
}
}
}
V detailu zprávy zjistíte stav doručení pro všechny příjemce. Pomocí webhooku Vás můžeme informovat, když byla zpráva doručena příjemcům.
Celkový stav doručení zprávy
Nejprve jsou obsaženy informace o celkovém stavu doručení celé zprávy
Parametr | Význam |
---|---|
isDelivered | zda byla zpráva doručena všem příjemcům |
smsCount | kolik bylo celkově odesláno SMS (odpovídá počtu příjemců krát počet částí zprávy) |
deliveredSmsCount | kolik SMS bylo doručeno |
Doručení zprávy jednotlivým příjemcům
Poté následují údaje pro jednotlivé příjemce. Příjemci jsou rozděleni podle stavu doručení. Pro konečné stavy, tj. doručeno, nebo nedoručeno, je k číslu připojen čas (ne)doručení. U doručované zprávy se zobrazí přehled počtu částí zpráv podle stavu doručení.
Parametr | Význam |
---|---|
delivered | příjemce obdržel všechny části zprávy |
undelivered | nepodařilo se doručit ani jednu část zprávy příjemci |
delivering | ještě není znám stav doručení všech částí pro daného příjemce |
Jak zjistím, že příjemce, např. +420111222444, dostal mojí zprávu?
Příjemce dostal zprávu, pokud se jeho číslo nachází jako klíč v delivery.recipients.delivered
. V uvedeném příkladu vidím, že +420111222444 obdržel zprávu 24.prosince 2014 v 21:23.
Příjem odpovědí
V detailu zprávy zjistíte počet odpovědí, na seznamu odpovědí je můžete zobrazit. Pomocí webhooku Vás můžeme informovat, když přijde nová odpověď.
Odpovědi v detailu zprávy
{
"reply": {
"hasReplies": true,
"repliesCount": 0
},
"links": {
"replies": "api/v1/messages/1/replies"
}
}
Detail zprávy obsahuje blok reply
se základními informacemi o odpovědích:
hasReplies
- zda byla zpráva odeslaná přes kanál s odpovědírepliesCount
- celkový počet odpovědí k dané zprávě
Kdo a kdy odpověďěl zjistíte na nové stránce, odkaz naleznete v links.replies
.
Poslal jsem zprávu přes kanál, který nepřijímá odpovědí, ale vidím, že počet odpovědí je nenulový. Co to znamená?
Kdykoliv použijete kanál, který podporuje odpovědi, tak se může stát, že Vám příjemce SMS odpoví. V takovém případě odpověď přiřadíme ke zprávě, ale v detailu ani ve webhooku ji neuvidíte. Jestliže chcete odpovědi zobrazit, tak nás kontaktujte na podpora@gosms.cz
.
Seznam odpovědí u zprávy
curl "https://app.gosms.cz/api/v1/messages/1/replies"
{
"reply": {
"hasReplies": true,
"repliesCount": 1,
"recipients": {
"+420111222333": [{
"id": 1,
"message": "odpoved",
"sourceNumber": "+420799507467",
"received": "2016-05-04T21:23:00+02:00"
}]
}
},
"links": {
"message": "api/v1/messages/1",
"replies": "api/v1/messages/1/replies"
}
}
GET https://app.gosms.cz/api/v1/messages/{id}/replies
Response atributy
Parametr | Význam |
---|---|
reply | blok obsahující informace o odpovědích |
hasReplies | zda byla zpráva odeslaná přes kanál s odpovědí |
repliesCount | počet přijatých odpovědí k dané zprávě, může být nenulový, i když hasReplies=false |
id | unikátní ID odpovědi v rámci GoSMS |
message | text odpovědi |
sourceNumber | číslo na které bylo odeslaná odpověď |
received | datum přijetí odpovědi |
Webhooky
V samoobsluze můžete vložit URL adresy, které zavoláme, pokud nastane požadovaná událost. U webhooků bude moci nastavit, zda chce přijímat doručenky, odpovědi nebo informace o výpadcích. Typ reportu poznáte podle atributu event
:
event | Popis | Co pošleme webhookem |
---|---|---|
delivery | doručenky | Doručenky všech příjemců |
reply | odpovědi | Nově příchozí odpovědi |
outage | výpadky | Informace o výpadcích |
Jaké URL adresy můžu použít?
Lze použít http
i https
adresy. URL může obsahovat i HTTP Basic autentizaci, např. http(s)://user:pass@example.com
. Takový webhook bude zavolán s hlavičkou Authorization: Basic ...
, takže user:pass
nebude přímo v URL adrese.
Jak často se posílají reporty?
Abychom Vás nezahltili posíláním informací o každé doručence (že jednomu příjemci přišla jedna část zprávy), tak vždy za 10 sekund zagregujeme všechny změny v doručenkách v rámci celé organizace a pak POST požadavkem na zvolenou URL pošleme JSON report.
Co když bude moje URL nedostupná
Pokud vaše URL vrátí status kód z intervalu <400, 5XX>
, tak se třikrát pokusíme zopakovat zaslání doručenky.
Doručenky
curl -X POST "http://example.com/delivery.php" \
-H "Content-Type: application/json" \
-d '[{"event":"delivery","delivery":{},"links":{}}]'
[
{
"event": "delivery",
"delivery": {
"isDelivered": false,
"smsCount": 2,
"deliveredSmsCount": 1,
"recipients": {
"delivered": {
"+420111222333": "2014-12-24T21:23:00+02:00"
},
"undelivered": {},
"delivering": {
"+420111222555": {
"deliveredCount": 0,
"undeliveredCount": 0,
"deliveringCount": 1
}
}
}
},
"links": {
"message": "api/v1/messages/1"
}
}
]
V reportu Vám zašleme stejné informace jako v detailu zprávy (s opraveným mapováním prázdných příjemců), pouze k nim připojíme název eventu a odkaz na detail zprávy.
Odpovědi
curl -X POST "http://example.com/reply.php" \
-H "Content-Type: application/json" \
-d '[{"event":"reply","reply":{},"links":{}}]'
Odpovědi jsou ve webhooku agregovány podle zpráv
[
{
"event": "reply",
"reply": {
"hasReplies": true,
"repliesCount": 1,
"recipients": {
"+420111222333": [{
"id": 1,
"message": "odpoved",
"sourceNumber": "+420799507467",
"received": "2016-05-04T21:23:00+02:00"
}]
}
},
"links": {
"message": "api/v1/messages/1",
"replies": "api/v1/messages/1/replies"
}
},
{
"event": "reply",
"reply": {
"hasReplies": true,
"repliesCount": 2,
"recipients": {
"+420999888777": [
{
"id": 2,
"message": "odpoved",
"sourceNumber": "+420799507467",
"received": "2016-05-04T21:23:00+02:00"
},
{
"id": 3,
"message": "oprava, tohle je správně",
"sourceNumber": "+420799507467",
"received": "2016-05-04T23:09:00+02:00"
}
]
}
},
"links": {
"message": "api/v1/messages/2",
"replies": "api/v1/messages/2/replies"
}
}
]
Webhook nepřiřazené odpovědi
[
{
"event": "reply",
"reply": {
"hasReplies": true,
"repliesCount": 1,
"recipients": {
"+420111222333": [{
"id": 1,
"message": "odpoved",
"sourceNumber": "+420799507467",
"received": "2016-05-04T21:23:00+02:00"
}]
}
},
"links": {}
}
]
Webhooky vrací stejná data ve stejném formátu jako detail odpovědí, ale webhookem pošleme jen nové odpovědi a odpověď nemusí být přiřazená ke zprávě!
Nepřiřazené odpovědi ve webhooku
Narozdíl od detailu zprávy může webhook, vrátit odpověď, která není přiřazena k žádné zprávě. Lze ji poznat podle links
, kde nepřiřazená zpráva neobsahuje žádné odkazy.
V jakých případech mi může přijít nepřiřazená odpověď?
Když používáte vlastní telefonní číslo v kanálu, tak Vám pošleme informace o všech odpovědích, které na Vaše číslo přijdou. Může se stát, že se nám nepodaří spojit odpověď s původní zprávu.
Jak můžu pracovat s nepřiřazenou odpovědí?
V samoobsluze lze odpověď smazat nebo přiřadit ke zprávě. Po přiřazení ke zprávě Vám pošleme znovu webhook, tentokrát už bude odpověď přiřazená ke zprávě.
Informace o výpadcích
curl -X POST "http://example.com/outage.php" \
-H "Content-Type: application/json" \
-d '[{"event":"outage","outage":{}}]'
Nahlášení probíhajícího nebo plánovaného výpadku
[
{
"event": "outage",
"outage": {
"id": 1,
"status": "IN_PROGRESS|SCHEDULED",
"message": "informace o výpadku"
}
}
]
Ukončení probíhajícího výpadku
[
{
"event": "outage",
"outage": {
"id": 1,
"status": "FINISHED"
}
}
]
Webhooky informují o probíhajících nebo naplánovaných výpadcích, které by měly za příčinu omezenou možnost doručování SMS.
Probíhající výpadek
Webhook zasíléme ve chvíli, kdy se dozvíme o omezené možnosti/nemožnosti doručování SMS a to jak na straně aplikace GoSMS, tak na straně některého z operátorů.
Ukončení výpadku
Informace o ukončení probíhajícího výpadku. Neobsahuje message
a id
odpovídá id
probíhajícího výpadku, který webhook ukončuje.
Naplánovaný výpadek
Datum, čas a další informace ohledně výpadku jsou popsány v message
. V případě naplánovaného výpadku již dále neinformujeme o ukončení výpadku. Naplánovaný výpadek může být doplněn probíhajícím výpadkem.
Správa přes API
Seznam webhooků
curl -X GET "https://app.gosms.cz/api/v1/webhooks/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}"
{
"webhooks": [
{
"id": 1,
"url": "http://www.example.com/webhook",
"type":"DELIVERY"
}
]
}
Vytvoření webhooku
curl -X POST "https://app.gosms.cz/api/v1/webhooks/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{"url":"http://www.example.com","type":"DELIVERY"}'
{
"url": "http://www.example.com",
"type": "DELIVERY|REPLY|OUTAGE"
}
Detail webhooku
curl -X GET "https://app.gosms.cz/api/v1/webhooks/{id}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}"
Úprava webhooku
curl -X PUT "https://app.gosms.cz/api/v1/webhooks/{id}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{"url":"http://www.example.com","type":"DELIVERY"}'
{
"url": "http://www.example.com",
"type": "DELIVERY|REPLY|OUTAGE"
}
Odstranění webhooku
curl -X DELETE "https://app.gosms.cz/api/v1/webhooks/{id}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}"
Kromě samoobsluhy lze spravovat webhooky i přes API.
Typ webhooku rozeznáváme podle atributu type
:
type | Popis |
---|---|
DELIVERY | doručenky |
REPLY | odpovědi |
OUTAGE | výpadky |
REST API pod lupou
Datumy
Jaký formát datumu příjímá API?
API nevyžaduje specifický formát datumu. Můžete použít různé formáty, ale pro absolutní formát datumu doporučujeme formát ISO 8601 i s časovou zónou. Nebo použijte relativní formát jako tomorrow
apod. Ukázky několika příkladů přijímaných dat:
tomorrow midnight
10.10.2014 17:00
2014-09-11T07:20:21+0200
V jakém formátu vrací API datumy?
API vždy vrací datum ve formátu ISO 8601 (přesná definice: Y-m-d\TH:i:sO
).
Formát chyb
Chyba při zaslání zprávy přes neexistující kanál
{
"type": "",
"title": "Non-existent channel",
"status": 400,
"detail": "Channel '12345' doesn't exist in your organization"
}
Ukázka pole chyb po neúspěšném pokusu o odeslání zprávy
{
"type":"",
"title":"Invalid Message",
"status":400,
"detail":"Message contains invalid fields and cannot be sent",
"errors":[
"Invalid Recipients: hello,4207396asdfasdfasf",
"Message cannot be scheduled back in time. Send start date must be greater than current date 2014-09-11T07:20:21+0200"
]
}
Formát chybových zpráv vychází z JSON API problem. Pokud není vyplněn atribut type, tak HTTP status kód popisuje dostatečně chybu. V těle zprávy je také název chyby, stavový kód, případně zpráva obsahuje i textový popis chyby.
Parametr | Význam |
---|---|
type | URL adresa odkazující na chybu, nebo prázdný řetězec, pokud je HTTP dostatečně popisný. |
title | Základní popisek problému |
status | Stavový kód, který odpovídá kódu v HTTP hlavičce |
detail | Podrobnější popis chyby |
errors | Pole chyb |
Změny v API od července 2017
Změny 10.7.2017
Výpis dostupných komunikačních kanálů
Výpis detailu organizace nově obsahuje i výpis dostupných komunikačních kanálů
Informace o výpadcích
Zasílání informací o výpadcích pomocí webhooku
Správa webhooků
Vytváření, editace a mazání webhooků přes API
Změny 19.7.2016
Blokování příjemců
GoSMS nově dovoluje zablokovat číslo příjemce. V praxi to znamená, že pokud odešlete zprávu na telefonní číslo, které je vedené jako zablokované, nebude na něj zpráva odeslána.
úspěšné odeslání zprávy
Zablokovaná čísla najdete v odpovědi API spolu s nevalidními čísly v recipients.invalid
.
neúspěšné odeslání zprávy
Zablokovaná čísla najdete v poli chyb jako Blocked recipients: +420...
.
Přidání příkladu použití GoSMS API
Změny 6.6.2016
Ukázka smazání zprávy
curl -X DELETE "https://app.gosms.cz/api/v1/messages/{id}" \
-H "Authorization: Bearer {token}"
Změny 9.5.2016
- Informace o odpovědích v detailu zprávy
- Endpoint se seznam všech odpovědí u zprávy
- Webhook pro zasílání nových odpovědí
Změny 24.11.2015
Ukázka rozšířených statistik v detailu zprávy
{
"stats": {
"price": 0.739,
"hasDiacritics": false,
"smsCount": 1,
"messagePartsCount": 1,
"recipientsCount": 1,
"numberTypes": {
"czMobile": 1,
"czOther": 0,
"sk": 0,
"pl": 0,
"hu": 0,
"ro": 0,
"other": 0
}
}
}
Přidání Polska, Maďarska, Rumunska do statistik počtu příjemců
Změny 5.8.2015
Ukázka nových statistik v detailu zprávy
{
"stats": {
"price": 0.739,
"hasDiacritics": false,
"smsCount": 1,
"messagePartsCount": 1,
"recipientsCount": 1,
"numberTypes": {
"czMobile": 1,
"czOther": 0,
"sk": 0,
"other": 0
}
}
}
- Otestování vytvoření zprávy bez odeslání
- Rozšíření detailu zprávy - cena zprávy, počty příjemců, diakritika, …
Změny 27.3.2015
curl "https://app.gosms.cz/api/v1/messages/1" \
-H "X-gosms-version: 2015-03-27"
{
"messageType": "SMS",
"delivery": {
"isDelivered": false,
"smsCount": 3,
"deliveredSmsCount": 1,
"recipients": {
"delivered": {
"+420111222333": "2014-12-24T21:23:00+02:00"
},
"undelivered": {},
"delivering": {}
}
},
"links": {
"self": "api/v1/messages/1"
}
}
[
{
"event": "delivery",
"delivery": {
},
"links": {
}
},
{
"event": "delivery",
"delivery": {
},
"links": {
}
}
]
Oprava mapování prázdných příjemců
Webhooky
Webhooky vždy vrací správné mapování, tj. {}
pro prázdné příjemce ( old-webhook.php
proxy vrací špatné mapování).
Detail zprávy
Detail zprávy stále defaultně vrací špatné mapování. Pro vrácení správně namapovaných příjemců je potřeba k requestu připojit hlavičku X-gosms-version: 2015-03-27
.
Webhook - agregace pro celou organizace
Agregace webhooku probíhá pro celou organizaci. Reporty jsou v poli, jinak struktura jednoho reportu zůstává stejná.
Související změny
- Čas čekání na Vaší odpověď (
timeout
) bude zvýšen na 10s. Pokud neodpovíte v daném čase, tak se požadavek požaduje za neúspěšný. - Nově kontrolujeme změnu v reportech, takže Vám pošleme report, pouze pokud v něm došlo ke změně.
Co když nejsem připravený na novou verzi webhooků?
Pro již implementované webhooky můžete použít proxy url, která odešle reporty po jednom: https://app.gosms.cz/old-webhook.php?url=http://example.com/delivery.php
. Existující webhooky takto upravíme při nasazení nové verze API.
Webhook proxy byla odstraněna 1.července 2015!