Prieš siunčiant
Siųskite SMS arba palaikomą MMS naudodami savo paskyrai sukonfigūruotą siuntėjo numerį. Tai realioje aplinkoje vykdoma operacija, kuri gali išsiųsti pranešimus gavėjams ir sukelti mokesčių. Siųskite tik gavėjams, kuriems turite leidimą siųsti, ir tik patvirtintų tipų pranešimus; toliau pateikti pavyzdiniai numeriai ir susiejimo žyma yra išgalvoti.
Jūsų paskyrai reikia patvirtinimo siųsti išeinančius pranešimus ir atitinkamų leidimų, taikomų siuntėjui, šaliai bei pranešimų srautui. Tiesioginiai asmeninių ar vartotojų paskyrų prisijungimo duomenys netinka šiai API. Patvirtintiems specialiai API skirtiems prisijungimo duomenims taikoma atskira tinkamumo procedūra; mobiliesiems P2P siuntėjams gali reikėti papildomų P2P ir JAV bei Kanados leidimų. Su „MultiTEL“ patikslinkite tinkamą paskyros konfigūraciją ir nelaikykite API prisijungimo duomenų automatiniu leidimu siųsti bet kokius pranešimus.
Siuntimo užklausa
Autentifikuokitės per HTTPS naudodami įjungtą API paskyrą iš jai leidžiamo šaltinio IP adreso. Prisijungimo duomenis laikykite serverio pusėje esančioje slaptų duomenų saugykloje. Naudokite POST su formos kodavimo laukais arba JSON objektą, kai nepateikiami nei formos, nei užklausos eilutės laukai. Nedėkite prisijungimo duomenų ar pranešimo teksto į 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| Laukas | Privalomas | Reikšmė |
|---|---|---|
| from | Taip | Jūsų sukonfigūruotas siuntėjo numeris, pageidautina, užrašytas visais tarptautinio formato skaitmenimis. |
| to | Taip | Vienas gavėjo numeris, kableliais atskirti gavėjų numeriai arba JSON masyvas. Pageidautina naudoti visus tarptautinio formato skaitmenis. Grupinė užklausa gali būti atmesta dėl jai taikomų P2P ar šalies apribojimų; tai nėra neriboto masinio siuntimo API. |
| text | SMS pranešimams | Pranešimo tekstas UTF-8 koduote. Būtina pateikti bent netuščią tekstą arba medijos turinį. Siųskite tikruosius simbolius ir eilučių lūžius, o ne HTML ar procentiniais kodais užkoduotą tekstą. Kai kuriuose operatorių siuntimo keliuose pažodžiui pateiktos kaitos sekos normalizuojamos. |
| media | MMS pranešimams, kuriuose yra tik medijos turinys | Base64 koduote užkoduotas medijos turinys, o ne URL ar failo kelias. MMS prieinamumas, formatas ir dydis priklauso nuo sukonfigūruoto maršruto. Su „MultiTEL“ patikslinkite, koks medijos turinys palaikomas; ši apdorojimo priemonė nenustato universalaus medijos dydžio apribojimo. |
| reference | Rekomenduojamas | Jūsų susiejimo žyma, išsaugoma įrašuose ir atgaliniuose pranešimuose. Pateikite ją, kad būtų lengviau nustatyti triktis. Tai nėra idempotentiškumo raktas. |
| notifyurl | Ne | Jūsų HTTPS atgalinių pranešimų gavimo adresas. Baigusi apdorojimą, apdorojimo priemonė gali nusiųsti pradinį rezultatą metodu POST. Gaviklį turite valdyti jūs, o jo URL negali būti vidinės paslaugos adresas. |
Jei naudojate JSON masyvą, lauke to pateikite tikrą masyvą; nedėkite JSON masyvą vaizduojančios eilutės į formos lauką. Pradinį integracijos bandymą atlikite siųsdami vienam gavėjui. Grupinio siuntimo ir MMS palaikymas skiriasi priklausomai nuo maršruto, todėl prieš naudodami patikslinkite, ar reikalingas derinys palaikomas.
Perskaitykite visą rezultatą
Pateikiami tik pasirinkti pavyzdiniai laukai; rodoma kaina nėra kainos pasiūlymas.
{
"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"
}
}Kartu tikrinkite HTTP būseną, JSON status.code ir atsakymo status/message laukus. Rezultatų kodai gali būti eilutės. Išsaugokite sms_log_id_ori ir grąžintas pranešimo bei susiejimo žymos reikšmes, kad pagalbos tarnyba galėtų susieti duomenis. Senųjų uniqueid ir pid laukų reikšmės priklauso nuo maršruto; nedarykite išvadų apie jų formatą ir nemanykite, kad tai kliento idempotentiškumo žetonai.
Success arba Message queued paprastai reiškia, kad pranešimas priimtas pasirinktu maršrutu, o ne gautas asmens telefone. Vien pradinio atgalinio pranešimo būsena, pavyzdžiui, sent, nepatvirtina galutinio pristatymo.
Segmentai ir mokesčiai
Naudokite SMS ilgio analizę visam galutiniam tekstui prieš siųsdami. SMS kainos priklauso nuo gavėjo šalies ar tinklo ir paskyrai teikiamos paslaugos; taikomi operatoriaus mokesčiai pridedami už kiekvieną segmentą. Siuntimo procesas sudeda gavėjams taikomas kainas bei atitinkamus mokesčius ir gautą sumą padaugina iš apskaičiuoto SMS segmentų skaičiaus. Atliekant šį skaičiavimą MMS užklausa laikoma vienu pranešimu.
cost ir permsg senajame atsakyme yra suformatuotos pinigines sumas vaizduojančios eilutės. carrier_fee_usd nurodo operatoriaus mokesčio dalį USD valiuta, kuri jau įtraukta į apskaičiuotą bendrą siuntimo sumą; nepridėkite jos antrą kartą. Būtina patikrinti faktinius jūsų paskyrai taikomus įkainius ir maršrutų prieinamumą. Ši užklausa nėra vien kainos patikrinimo operacija.
Peržiūrėtame kode lėšos nurašomos sėkmingai užbaigus siuntimą per operatorių, tačiau operatoriaus priėmimas, vietinis duomenų išsaugojimas ir apmokestinimas nėra viena transakcija. Klaida arba laukimo laiko pabaiga gali įvykti po to, kai išorinė sistema jau priėmė užklausą. Klientui nepateikiamas idempotentiškumo raktas: pakartotinai pateikus tą pačią susiejimo žymą, pranešimas gali būti išsiųstas ir apmokestintas dar kartą.
Vietinis pristatymas ir mišrūs rezultatai
Vietoje aptarnaujamų numerių pranešimai gali būti priimti (accepted) į „MultiTEL“ gaunamų pranešimų srautą nesiunčiant per išorinį operatorių. Jei visi užklausos gavėjai yra vietiniai, atsakyme gali būti accepted, message_id, provider ir delivery_status. Vietinis priėmimas negarantuoja, kad gavėjo sukonfigūruotas persiuntimo adresas suveikė.
Patikrinkite local_delivery_results ir partial, jei jie pateikti. Gavėjo lauko accepted reikšmė gali būti true, nors persiuntimas nepavyko. Mišrioje užklausoje operatoriaus aptarnaujami gavėjai gali būti priimti (accepted), o vietinė dalis – nepavykusi. Nekartokite visos grupės siuntimo automatiškai: pirmiausia sutikrinkite kiekvieno gavėjo rezultatą.
Šiame apdorojimo kelyje, kai priimami tik vietiniams gavėjams skirti pranešimai, nurodoma nulinė išeinančio siuntimo kaina, tačiau gavėjams vis tiek gali būti taikomi įprasti gaunamų pranešimų mokesčiai. Nelaikykite nulinės išeinančio siuntimo kainos garantija, kad nebus apmokestinta jokia paskyra.
Atgaliniai pranešimai ir duomenų susiejimas
Kai pateikiamas notifyurl, pradiniame atgaliniame pranešime yra status apvalkalas ir atsakymo laukai, įskaitant message_id, reference, from, to, status, status_text, error_code, timestamp ir accepted. Taip pat gali būti pateikti vietiniai rezultatai. Saugokite susiejimo informaciją, tačiau nerašykite į žurnalus API prisijungimo duomenų ar nebūtino pranešimų turinio.
Ši apdorojimo priemonė į pradinį atgalinį pranešimą neprideda parašo lauko. Nenaudokite nepatikrinto atgalinio pranešimo kaip vienintelio leidimo atlikti kitą veiksmą. Peržiūrėkite jūsų paskyrai palaikomą integracijos ir žiniatinklio pranešimų konfigūraciją, o neaiškius rezultatus sutikrinkite su portalo įrašais arba kreipkitės į pagalbos tarnybą. Nemanykite, kad atgaliniai pranešimai gaunami tik vieną kartą ar galutinio pristatymo tvarka.
Klaidos ir saugus veikimo atkūrimas
Duomenų tikrinimo klaidoms gali būti naudojamas API kodas 403. Atmetus užklausą dėl paskyros patvirtinimo, P2P ar šalies taisyklių, taip pat gali būti nustatyta HTTP būsena 403 ir pateiktas mašininiu būdu nuskaitomas response.code. Viršijus užklausų dažnio ribas gali būti grąžintas 429 su pakartotinio bandymo informacija. Kai taisyklių patikra nepasiekiama arba nepavyksta siuntimas ar vietinis duomenų išsaugojimas, gali būti naudojamas 503 arba 500; pagal senąją elgseną nepakankamas likutis taip pat gali grąžinti 500.
Gavę 429, laikykitės Retry-After ir bet kurios pateiktos response.retry_after reikšmės. Jei užklausa atmesta dėl paskyros, siuntėjo, šalies ar gavėjo, prieš kartodami pašalinkite priežastį. Pasibaigus laukimo laikui arba gavus neaiškų siuntimo rezultatą, išsaugokite užklausos laiką, susiejimo žymą bei grąžintus identifikatorius, patikrinkite portalą ir prieš siųsdami iš naujo kreipkitės į pagalbos tarnybą. Vien tai, kad žurnale nėra įrašo, neįrodo, jog nė vienas operatorius nepriėmė užklausos.