Enne saatmist
Saatke SMS või toetatud MMS oma konto jaoks seadistatud saatjanumbrilt. See on toiming tootmiskeskkonnas, mis võib saajatega ühendust võtta ja tasusid tekitada. Saatke sõnumeid ainult lubatud saajatele ning kasutage ainult heakskiidetud sõnumiliiklust; allpool toodud näidisnumbrid ja viide on väljamõeldud.
Teie kontol peab olema väljaminevate sõnumite saatmise heakskiit ning asjakohased saatja-, riigi- ja sõnumiliikluse load. Personal/Consumer-kasutaja otsesed autentimisandmed ei sobi selle API kasutamiseks. Heakskiidetud spetsiaalsete API autentimisandmete kasutusõigust hinnatakse eraldi; mobiilsete P2P-saatjate puhul võidakse nõuda täiendavaid P2P- ning USA ja Kanada lube. Kinnitage MultiTEL-iga konto õige seadistus, selle asemel et pidada API autentimisandmeid automaatseks loaks mis tahes sõnumiliikluse saatmiseks.
Saatmispäring
Autentige HTTPS-i kaudu lubatud lähte-IP-aadressilt, kasutades aktiveeritud API kontot. Hoidke autentimisandmeid serveripoolses saladuste hoidlas. Kasutage meetodit POST vorminguga form-encoded kodeeritud väljadega või JSON-objekti, kui vormi- ega päringustringi välju pole esitatud. Ärge lisage autentimisandmeid ega sõnumi teksti URL-i.
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| Väli | Kohustuslik | Tähendus |
|---|---|---|
| from | Jah | Teie seadistatud saatjanumber, eelistatavalt täielikul rahvusvahelisel kujul numbritena. |
| to | Jah | Üks sihtnumber, komadega eraldatud sihtnumbrid või JSON-massiiv. Eelistage täielikku rahvusvahelist kuju numbritena. Rühmapäring võidakse sellele kehtivate P2P- või riigipiirangute tõttu tagasi lükata; see ei ole piiranguteta hulgisaatmise API. |
| text | SMS-i korral | Sõnumi tekst UTF-8 kodeeringus. Nõutav on vähemalt mittetühi tekst või meediasisu. Saatke tegelikud märgid ja reavahetused, mitte HTML-i ega protsentkodeeritud teksti. Mõned operaatori töötlusvood normaliseerivad sõnasõnalisi paojadasid. |
| media | Ainult meediasisu sisaldava MMS-i korral | Base64-kodeeritud meediasisu, mitte URL ega failitee. MMS-i saadavus, vorming ja suurus sõltuvad seadistatud marsruudist. Küsige MultiTEL-ilt, millist meediasisu toetatakse; see päringutöötleja ei kehtesta universaalset meediasisu suuruse piirangut. |
| reference | Soovitatav | Teie seostamismärgis, mis säilitatakse kirjetes ja tagasikutsetes. Lisage see tõrkeotsingu hõlbustamiseks. See ei ole idempotentsusvõti. |
| notifyurl | Ei | Teie HTTPS-tagasikutsete vastuvõtja. Päringutöötleja võib pärast töötlemist saata esialgse tulemuse meetodiga POST. Vastuvõtja peab olema teie kontrolli all ning see ei tohi olla siseteenuse URL. |
JSON-massiivi kasutamisel esitage väljal to tegelik massiiv; ärge lisage vormiväljale JSON-massiivi sisaldavat stringi. Esmase integratsioonitestina kasutage saatmist ühele saajale. Rühmasaatmise ja MMS-i tugi erineb marsruuditi, seega kinnitage enne nende kasutamist, et vajalikku kombinatsiooni toetatakse.
Lugege kogu tulemust
Näidatud on ainult valitud näitlikud väljad; kuvatud maksumus ei ole hinnapakkumine.
{
"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"
}
}Kontrollige koos HTTP olekut, JSON-i välja status.code ning vastuse välju status/message. Tulemuskoodid võivad olla stringid. Säilitage välja sms_log_id_ori väärtus ning tagastatud sõnumi- ja viiteväärtused, et klienditugi saaks need omavahel seostada. Pärandväljade uniqueid ja pid väärtused erinevad marsruuditi; ärge tuletage nende vormingut ega eeldage, et need on kliendi idempotentsustõendid.
Success või Message queued tähendab tavaliselt, et valitud marsruut võttis sõnumi vastu, mitte seda, et sõnum jõudis inimese telefoni. Esialgse tagasikutse olek, näiteks sent, ei tõenda iseenesest lõplikku kohaletoimetamist.
Segmendid ja tasud
Kasutage SMS-i pikkuse analüüsi enne saatmist kogu lõpliku teksti jaoks. SMS-i hinnad sõltuvad sihtkohast ja kontol kasutatavast teenusest; asjakohased operaatoritasud lisanduvad iga segmendi kohta. Saatmise töötlusvoog liidab saajate hinnad ja asjakohased tasud ning korrutab seejärel tulemuse arvutatud SMS-segmentide arvuga. Selles arvutuses käsitletakse MMS-päringut ühe sõnumina.
cost ja permsg on pärandvastuses vormindatud rahasummade stringid. carrier_fee_usd näitab operaatoritasu osa valuutas USD ja sisaldub juba arvutatud saatmise kogusummas; ärge lisage seda teist korda. Tegelikud hinnad ja marsruutide saadavus tuleb kontrollida teie konto puhul. Päring ei ole pelgalt hinnapäring.
Ülevaadatud kood debiteerib kontot pärast operaatori kaudu saatmise töötlusvoo edukat läbimist, kuid operaatori vastuvõtt, kohalik püsisalvestus ja arveldus ei moodusta üht tehingut. Viga või ajalõpp võib tekkida pärast seda, kui ülesvoolu teenus on päringu vastu võtnud. Kliendile ei pakuta idempotentsusvõtit: sama viite korduv kasutamine võib põhjustada uue saatmise ja tasu.
Kohalik kohaletoimetamine ja segatulemused
Kohalikult hallatavate numbrite sõnumid võidakse võtta MultiTEL-i sissetulevate sõnumite töötlusvoogu olekuga accepted, ilma et neid saadetaks välise operaatori kaudu. Ainult kohalikke saajaid sisaldava päringu vastus võib sisaldada välju accepted, message_id, provider ja delivery_status. Kohalik vastuvõtt ei taga, et saaja seadistatud edasisuunamise sihtkoht toimis.
Kontrollige välju local_delivery_results ja partial, kui need on olemas. Saaja puhul võib välja accepted väärtus olla true, kuigi edasisuunamine ebaõnnestus. Segapäringus võivad operaatori kaudu saadetavate sõnumite saajad olla olekus accepted, samal ajal kui kohalik osa ebaõnnestub. Ärge korrake kogu partiid automaatselt: selgitage esmalt välja iga saaja tulemus.
Ainult kohalike saajatega päringu vastuvõtu korral näitab see töötlusvoog väljamineva saatmise maksumuseks nulli, kuid saajatele võivad endiselt rakenduda nende tavapärased sissetulevate sõnumite tasud. Ärge tõlgendage väljamineva saatmise nullmaksumust tagatisena, et üheltki kontolt tasu ei võeta.
Tagasikutsed ja seostamine
Kui notifyurl on esitatud, sisaldab esialgne tagasikutse välist status-struktuuri ja vastusevälju, sealhulgas message_id, reference, from, to, status, status_text, error_code, timestamp ja accepted. Esineda võivad ka kohalikud tulemused. Salvestage seostamiseks vajalik teave, logimata API autentimisandmeid ega tarbetut sõnumisisu.
See päringutöötleja ei lisa esialgsele tagasikutsele allkirjastamisvälja. Ärge kasutage kontrollimata tagasikutset iseseisva volitusena mõne muu toimingu tegemiseks. Tutvuge oma konto toetatud integratsiooni- või veebikonksu seadistusega ning selgitage ebaselged tulemused välja portaali kirjete või klienditoe abil. Ärge eeldage, et tagasikutsed saabuvad ainult ühe korra või lõpliku kohaletoimetamise järjekorras.
Tõrked ja ohutu taastumine
Valideerimisvigade korral võidakse kasutada API koodi 403. Konto heakskiidust, P2P-reeglitest või riigireeglitest tulenevate keeldude korral võidakse samuti määrata HTTP olek 403 ja lisada masinloetav response.code. Päringusageduse piirangute korral võidakse kasutada koodi 429 koos korduskatse teabega. Kui reeglistik pole kättesaadav või saatmine või kohalik püsisalvestus ebaõnnestub, võidakse kasutada koodi 503 või 500; ka pärandsüsteemi ebapiisava saldo tõrge võib tagastada koodi 500.
Koodi 429 korral järgige päise Retry-After ja võimaliku välja response.retry_after väärtust. Kui keeldumine on seotud konto, saatja, riigi või saajaga, kõrvaldage põhjus enne uut katset. Ajalõpu või ebaselge saatmistulemuse korral säilitage päringu aeg, viide ja tagastatud identifikaatorid ning kontrollige portaali ja võtke enne uuesti saatmist ühendust klienditoega. Üksnes logikirje puudumine ei tõenda, et ükski operaator ei võtnud päringut vastu.