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
}

GET https://app.gosms.cz/api/v1/

Detail organizace aktuálně vrací pouze aktuální stav kreditu. 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.

Chybné mapování prázdných příjemců

Pokud existují příjemci, tak odpověď obsahuje objekt {}, kde klíč odpovídá číslu příjemce. Pokud ale neexistují žádná příjemci, tak odpověď je prázdné pole []. Toto chování bude postupně opravováno od verze z 27.3.2015.

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, nebo odpovědi. 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

Jaké URL adresy můžu použít?

Lze použít http i https adresy. 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ě.

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 2016

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}"

Možnost smazání SMS

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!