1. Hozzáférés és IP-engedélyezés
Az integráció előtt adja meg a küldő szerver nyilvános IP-címét vagy IP-címeit a BitSMS ügyfélszolgálatának. Az elérést ezekre a címekre engedélyezzük. A felhasználónevet és jelszót szintén az ügyfélszolgálattól kapja meg.
Nem engedélyezett IP-cím vagy hibás belépési adatok esetén az API NO ACCESS választ ad. Ilyenkor a kimenő IP-címet és a hozzáférési adatokat ellenőrizze; a kérés változatlan ismétlése nem oldja meg az engedélyezési hibát.
A hozzáférési adatokat kizárólag a saját szerverén tárolja. Ne tegye őket böngészőben futó JavaScriptbe, nyilvános forráskódba vagy naplóba. Az alábbi példák helyőrzőket tartalmaznak, nem működő hozzáféréseket.
2. SMS küldése POST-kéréssel
A küldési végpont pontos HTTPS-címét az ügyfélszolgálat adja meg a hozzáférés beállításakor. A példákban az API_HOST, a KULDESI_VEGPONT és a STATUSZ_VEGPONT helyőrzők szerepelnek, nem tényleges címek. A példa HTTPS POST-kérést és application/x-www-form-urlencoded törzset használ. A json=1 paraméter a válasz JSON-formátumát kéri; nem azt jelenti, hogy a kérés törzsét JSON-ként kell elküldeni.
| Paraméter | Tartalom |
|---|---|
username | Az ügyfélszolgálattól kapott felhasználónév. Kötelező. |
password | A hozzáféréshez tartozó jelszó. Kötelező. |
receiver | Nemzetközi telefonszám, kizárólag számjegyekkel, „+” jel és szóköz nélkül. Szövegként kezelje. Kötelező. |
text | Az SMS szövege. Kötelező. |
charset | 7bit vagy unicode. A példában kifejezetten megadjuk a kívánt kódolást. |
Példa kérés
Az alábbi minta nem fut le ezen az oldalon. A helyőrzőket a saját, biztonságosan kezelt adataival és engedélyezett tesztcímzettel helyettesítse.
POST KULDESI_VEGPONT?json=1 HTTP/1.1
Host: API_HOST
Content-Type: application/x-www-form-urlencoded
username=USERNAME&password=PASSWORD&receiver=RECEIVER_NUMBER&text=Teszt%20uzenet&charset=7bitA paraméterértékeket URL-kódolni kell. A rendszer GET-kérést is támogat, de a POST-minta elkerüli, hogy a jelszó az URL lekérdezési részébe kerüljön.
Példa JSON-válasz
{"messages":["4fd88ad0-b945-11e5-9078-00163e536649"]}Mentse el a visszakapott üzenetazonosítókat. Az azonosító önmagában nem bizonyítja a kézbesítést; ehhez külön státuszlekérdezés szükséges. A válasz feldolgozásakor ellenőrizze, hogy érvényes JSON-t és a várt messages mezőt kapta-e.
3. Kézbesítési státusz lekérdezése
A státusz legkorábban az SMS küldése után 10 másodperccel kérdezhető le az ügyfélszolgálattól kapott státuszvégponton. A dokumentált egyedi lekérdezéshez a username, password és id mezők szükségesek. GET és URL-kódolt POST használható.
POST STATUSZ_VEGPONT HTTP/1.1
Host: API_HOST
Content-Type: application/x-www-form-urlencoded
username=USERNAME&password=PASSWORD&id=4fd88ad0-b945-11e5-9078-00163e536649Az alábbi rövidített válasz a státusz és az üzenetazonosító kapcsolatát szemlélteti:
{"messages":[{"status":"delivered","message_id":"4fd88ad0-b945-11e5-9078-00163e536649"}]}| Státusz | Jelentés |
|---|---|
started | Az üzenet átadása a mobilszolgáltatónak elkezdődött. |
sent | A mobilszolgáltató átvette az üzenetet. Ez még nem kézbesítési igazolás. |
buffered | Az első kézbesítés nem sikerült; a hálózat újra próbálkozik, például kikapcsolt telefon esetén. |
delivered | Az üzenet kézbesült. Ez nem olvasási visszaigazolás. |
undeliverable, rejected | Az üzenet nem kézbesíthető, például hibás vagy nem létező telefonszám miatt. |
expired, deleted | A szolgáltatói várakozási idő alatt nem sikerült kézbesíteni az üzenetet, a hálózat eldobta azt. |
4. Karakterkészlet, hosszú SMS és számlázás
| Kódolás | Egy SMS | Összefűzött üzenet egy része |
|---|---|---|
| 7bit | Legfeljebb 160 karakter | Legfeljebb 153 karakter |
| Unicode | Legfeljebb 70 karakter | Legfeljebb 67 karakter |
A hosszú szöveget a rendszer automatikusan SMS-részekre bontja; ezeket a fogadó készülék összefűzheti. Ahány SMS-rész keletkezik, annyi darabot számlázunk. Például egy 161 egyszerű, 7 bites karakterből álló szöveg két SMS-rész, egy 71 szokásos magyar Unicode-betűből álló szöveg szintén két SMS-rész lehet. A karakterek kódolása befolyásolja a rendelkezésre álló helyet.
A 7bit beállításnál a magyar ékezetes karaktereket a szolgáltatás átalakítja, a nem támogatott karaktereket eltávolíthatja. Ha fontos az ékezetek megtartása, használjon Unicode-kódolást. A pontos szöveget próbálja ki tesztküldéssel; különösen emoji vagy speciális karakter esetén ne pusztán a látható betűk számából becsülje a díjat.
A fogadó készülék is korlátozhatja az összefűzést: a műszaki leírás szerint három SMS-rész felett egyes készülékek eldobhatják az üzenetet. Üzleti értesítésnél ezért érdemes rövid, egyértelmű szöveget használni.
5. Hibakezelés az integrációban
- Állítson be kapcsolódási és válaszidő-korlátot a saját HTTP-kliensében.
- A hálózati hibát, a
NO ACCESSválaszt és az érvénytelen JSON-t kezelje külön. - Ha a küldési kérés után megszakad a kapcsolat, a válasz hiánya nem bizonyítja, hogy nem indult el a küldés. A vak újrapróbálkozás duplikált SMS-t okozhat.
- A kapott azonosítót kapcsolja össze a saját üzleti eseményével, és státuszlekérdezéssel kövesse az eredményt.
- A naplókból hagyja ki a jelszót, és csak a szükséges címzett- és üzenetadatokat őrizze meg.
Az útmutató az egyedi üzenetazonosítós lekérdezést mutatja be. Tömeges státuszlekérdezés, más kérésformátum vagy további integrációs igény esetén egyeztessen az ügyfélszolgálattal.
Kétirányú SMS és beérkező válaszok API-n
Igen. Dedikált magyar mobilszámon kétirányú SMS-váltás is elérhető: ügyfele ugyanarra a számra válaszolhat, amelyről az üzenetet kapta. A beérkező SMS-eket webes felületen, API-n keresztül és e-mailben is megkaphatja. Az igényléskor jelezze, hogy válaszfogadást is szeretne, és melyik módon kezelné a beérkező üzeneteket.
Így a küldés mellett a válaszokat is a saját ügyviteli rendszerében kezelheti. A fogadási API dokumentációját és a beállításokat az induláskor egyeztetjük.