MENU
curl

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

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í:

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

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.

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)

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)

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:

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

Další informace o webhoocích.

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:

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

Možnost smazání SMS

Změny 9.5.2016

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

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

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!

curl