Prije slanja
Pošaljite SMS ili podržanu MMS poruku s broja za slanje konfiguriranog za vaš račun. Ovo je operacija u produkcijskom okruženju koja može kontaktirati primatelje i uzrokovati troškove. Šaljite samo ovlaštenim primateljima i samo odobreni promet; brojevi i referenca u primjeru u nastavku izmišljeni su.
Vaš račun mora imati odobrenje za slanje odlaznih poruka i odgovarajuća dopuštenja za pošiljatelja, državu i promet. Izravne korisničke vjerodajnice za osobne/potrošačke račune ne ispunjavaju uvjete za upotrebu ovog API-ja. Odobrene namjenske API vjerodajnice podliježu zasebnom postupku provjere uvjeta; mobilnim P2P pošiljateljima mogu biti potrebna dodatna dopuštenja za P2P i za SAD/Kanadu. Ispravnu konfiguraciju računa potvrdite s MultiTEL-om umjesto da API vjerodajnicu smatrate automatskim dopuštenjem za slanje bilo kakvog prometa.
Zahtjev za slanje
Autentificirajte se putem HTTPS-a s omogućenim API računom s njegove dopuštene izvorne IP adrese. Vjerodajnice čuvajte u spremištu tajni na poslužitelju. Upotrijebite POST s poljima kodiranima kao obrazac ili JSON objekt ako nisu navedena polja obrasca ni parametri upita. Ne stavljajte vjerodajnice ni tekst poruke u URL.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| Polje | Obvezno | Značenje |
|---|---|---|
| from | Da | Vaš konfigurirani broj za slanje, po mogućnosti zapisan svim znamenkama u međunarodnom obliku. |
| to | Da | Jedno odredište, odredišta odvojena zarezima ili JSON niz. Po mogućnosti navedite sve znamenke u međunarodnom obliku. Grupni zahtjev može biti odbijen zbog primjenjivih P2P ograničenja ili ograničenja za državu; ovo nije API za neograničeno masovno slanje. |
| text | Za SMS | Tekst poruke u kodiranju UTF-8. Potreban je barem neprazan tekst ili medijski sadržaj. Šaljite stvarne znakove i prijelome redaka umjesto HTML-a ili teksta kodiranog postotnim zapisom. Neki tijekovi obrade kod operatera normaliziraju doslovno zapisane escape-sekvence. |
| media | Za MMS samo s medijskim sadržajem | Medijski sadržaj kodiran u Base64, a ne URL ili putanja datoteke. Dostupnost, format i veličina MMS-a ovise o konfiguriranoj ruti. Podržane medijske sadržaje potvrdite s MultiTEL-om; ovaj obrađivač ne utvrđuje univerzalno ograničenje veličine medijskog sadržaja. |
| reference | Preporučeno | Vaša oznaka za povezivanje podataka, koja se zadržava u zapisima i povratnim pozivima. Navedite je radi otklanjanja poteškoća. Ona nije ključ idempotentnosti. |
| notifyurl | Ne | Vaš HTTPS prijamnik povratnih poziva. Obrađivač nakon obrade može poslati početni rezultat metodom POST. To mora biti prijamnik pod vašom kontrolom i ne smije biti URL interne usluge. |
Za JSON niz upotrijebite pravi niz u polju to; ne stavljajte znakovni niz koji predstavlja JSON niz u polje obrasca. Kao početni test integracije zadržite slanje jednom primatelju. Podrška za grupno slanje i MMS razlikuje se ovisno o ruti, pa prije upotrebe potvrdite podržanu kombinaciju.
Pročitajte cjelovit rezultat
Prikazana su samo odabrana polja radi ilustracije; prikazani trošak nije ponuda cijene.
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}Zajedno provjerite HTTP status, JSON polje status.code i polja status/message u odgovoru. Kodovi rezultata mogu biti znakovni nizovi. Sačuvajte sms_log_id_ori i vraćene vrijednosti poruke/reference radi povezivanja podataka pri pružanju podrške. Vrijednosti uniqueid i pid iz naslijeđenog sustava razlikuju se ovisno o ruti; nemojte izvoditi zaključke o njihovu formatu niti pretpostavljati da su to klijentski tokeni idempotentnosti.
Success ili Message queued obično označava prihvat na odabranoj ruti, a ne primitak na mobilnom uređaju osobe. Početni status povratnog poziva poput sent sam po sebi ne potvrđuje konačnu dostavu.
Segmenti i troškovi
Upotrijebite Analizu duljine SMS-a na cjelovitom konačnom tekstu prije slanja. Cijene SMS-a ovise o odredištu i usluzi na računu; primjenjive naknade operatera dodaju se za svaki segment. Tijek slanja zbraja cijene za primatelje i primjenjive naknade, a zatim ih množi izračunatim brojem SMS segmenata. Za potrebe tog izračuna MMS zahtjev smatra se jednom porukom.
cost i permsg formatirani su znakovni nizovi s novčanim iznosima u naslijeđenom odgovoru. carrier_fee_usd iskazuje dio koji se odnosi na naknadu operatera u valuti USD i već je uključen u izračunati ukupni iznos slanja; nemojte ga dodavati drugi put. Za svoj račun morate provjeriti stvarne cijene i dostupnost ruta. Zahtjev nije operacija namijenjena samo provjeri cijene.
Pregledani kod tereti račun nakon uspješnog tijeka slanja putem operatera, ali prihvat kod operatera, lokalno trajno spremanje i naplata nisu jedna transakcija. Pogreška ili istek vremena mogu se dogoditi nakon što je zahtjev prihvaćen u uzvodnom sustavu. Klijentski ključ idempotentnosti nije dostupan: ponavljanje iste reference može ponovno poslati poruku i ponovno uzrokovati naplatu.
Lokalna dostava i mješoviti rezultati
Lokalno smješteni brojevi mogu dobiti oznaku accepted i biti prihvaćeni u MultiTEL-ov tijek dolaznih poruka bez slanja putem vanjskog operatera. Za zahtjev koji obuhvaća samo lokalne brojeve odgovor može sadržavati accepted, message_id, provider i delivery_status. Lokalni prihvat ne jamči da je konfigurirano odredište prosljeđivanja primatelja funkcioniralo.
Provjerite local_delivery_results i partial kada su prisutni. Za primatelja može biti prikazano accepted true iako rezultat njegova prosljeđivanja nije uspješan. Mješoviti zahtjev može sadržavati primatelje koje je operater prihvatio s oznakom accepted i neuspješan lokalni dio. Nemojte automatski ponavljati cijelu skupinu: najprije uskladite rezultate za svakog primatelja.
Prihvat zahtjeva koji obuhvaća samo lokalne brojeve u ovom tijeku iskazuje nulti trošak odlaznih poruka, dok primateljima i dalje mogu biti naplaćene njihove uobičajene naknade za dolazne poruke. Nulti trošak odlaznih poruka nemojte tumačiti kao jamstvo da nijedan račun neće biti terećen.
Povratni pozivi i povezivanje podataka
Kada je naveden notifyurl, početni povratni poziv sadrži omotnicu status i polja odgovora, uključujući message_id, reference, from, to, status, status_text, error_code, timestamp i accepted. Mogu biti prisutni i lokalni rezultati. Pohranite podatke za povezivanje bez bilježenja API vjerodajnica ili nepotrebnog sadržaja poruka u zapisnike.
Ovaj obrađivač ne dodaje polje za potpisivanje tom početnom povratnom pozivu. Ne upotrebljavajte neprovjeren povratni poziv kao samostalno ovlaštenje za drugu radnju. Provjerite podržanu konfiguraciju integracije/webhooka za svoj račun i uskladite nejasne rezultate sa zapisima na portalu ili uz pomoć podrške. Nemojte pretpostavljati da povratni pozivi stižu samo jednom ili redoslijedom konačne dostave.
Neuspjesi i siguran oporavak
Neuspjesi provjere valjanosti mogu koristiti API kod 403. Odbijanja zbog odobrenja računa, pravila za P2P i pravila za državu također mogu postaviti HTTP 403 i uključivati strojno čitljivo polje response.code. Ograničenja učestalosti zahtjeva mogu koristiti 429 s informacijama o ponovnom pokušaju. Nedostupno pravilo ili neuspjeh slanja odnosno lokalnog trajnog spremanja mogu koristiti 503 ili 500; nedostatan saldo u naslijeđenom sustavu također može vratiti 500.
Za 429 poštujte Retry-After i svaku navedenu vrijednost response.retry_after. Ako je zahtjev odbijen zbog računa, pošiljatelja, države ili primatelja, otklonite uzrok prije ponovnog pokušaja. U slučaju isteka vremena ili nejasnog rezultata slanja sačuvajte vrijeme zahtjeva, referencu i vraćene identifikatore, provjerite portal i kontaktirajte podršku prije ponovnog slanja. Sam izostanak zapisa u zapisniku nije dokaz da nijedan operater nije prihvatio zahtjev.