SMS un atbalstīto MMS sūtīšana

Pirms sūtīšanas

Nosūtiet SMS vai atbalstītu MMS, izmantojot jūsu kontā konfigurētu sūtīšanas numuru. Tā ir darbība reālajā vidē, kas var sazināties ar saņēmējiem un radīt izmaksas. Sūtiet tikai pilnvarotiem saņēmējiem un tikai apstiprinātu ziņojumu plūsmu; tālāk norādītie piemēra numuri un atsauces vērtība ir izdomāti.

Jūsu kontam ir nepieciešams izejošo ziņojumu sūtīšanas apstiprinājums un attiecīgās sūtītāja, valsts un ziņojumu plūsmas atļaujas. Personīgo kontu un patērētāju kontu lietotāju tiešie piekļuves dati nav piemēroti šai API. Apstiprinātiem, īpaši API paredzētiem piekļuves datiem ir atsevišķa atbilstības noteikšanas kārtība; mobilajiem P2P sūtītājiem var būt nepieciešamas papildu P2P un ASV/Kanādas atļaujas. Saskaņojiet pareizo konta konfigurāciju ar MultiTEL, nevis uzskatiet API piekļuves datus par automātisku atļauju sūtīt jebkādu ziņojumu plūsmu.

Sūtīšanas pieprasījums

Autentificējieties, izmantojot HTTPS un iespējotu API kontu, no šim kontam atļautās avota IP adreses. Glabājiet piekļuves datus servera puses slepeno datu glabātuvē. Izmantojiet POST ar veidlapas formātā kodētiem laukiem vai JSON objektu, ja nav norādīti ne veidlapas, ne vaicājuma lauki. Neiekļaujiet piekļuves datus vai ziņojuma tekstu URL adresē.

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

Ja izmantojat JSON masīvu, laukā to norādiet īstu masīvu; neievietojiet JSON masīva teksta virkni veidlapas laukā. Sākotnējā integrācijas testā sūtiet vienam saņēmējam. Grupu sūtīšanas un MMS atbalsts dažādos maršrutos atšķiras, tāpēc pirms lietošanas noskaidrojiet, kāda kombinācija tiek atbalstīta.

Izlasiet visu rezultātu

Ilustrācijai parādīti tikai atsevišķi lauki; norādītā maksa nav cenas piedāvājums.

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

Pārbaudiet HTTP statusu, JSON status.code un atbildes status/message kopā. Rezultātu kodi var būt virknes. Saglabājiet sms_log_id_ori un atgrieztās ziņojuma un atsauces vērtības, lai atbalsta dienests varētu sasaistīt datus. Mantotās uniqueid un pid vērtības dažādos maršrutos atšķiras; neizdariet secinājumus par to formātu un nepieņemiet, ka tās ir klienta idempotences marķieri.

Success vai Message queued parasti nozīmē pieņemšanu izvēlētajā maršrutā, nevis saņemšanu personas tālrunī. Sākotnējā atpakaļizsaukuma statuss, piemēram, sent, pats par sevi neapstiprina galīgo piegādi.

Segmenti un maksas

Izmantojiet rīku SMS garuma analīze visam galīgajam tekstam pirms sūtīšanas. SMS cenas ir atkarīgas no adresāta un konta pakalpojuma; piemērojamās operatora maksas tiek pieskaitītas par katru segmentu. Sūtīšanas apstrādes ceļš saskaita saņēmēju cenas un piemērojamās maksas un tad reizina ar aprēķināto SMS segmentu skaitu. Šajā aprēķinā MMS pieprasījums tiek uzskatīts par vienu ziņojumu.

cost un permsg mantotajā atbildē ir formatētas naudas summu virknes. carrier_fee_usd norāda operatora maksas daļu USD valūtā, un tā jau ir iekļauta aprēķinātajā kopējā sūtīšanas maksā; nepieskaitiet to otrreiz. Jūsu kontam ir jāpārbauda faktiskās cenas un maršrutu pieejamība. Šis pieprasījums nav paredzēts tikai cenas noskaidrošanai.

Pārskatītais kods ietur maksu pēc veiksmīgas nosūtīšanas pa operatora apstrādes ceļu, taču operatora pieņemšana, vietējā datu saglabāšana un norēķini nav viena transakcija. Kļūda vai noildze var rasties pēc tam, kad augšupējais pakalpojums jau ir pieņēmis pieprasījumu. Klienta idempotences atslēga netiek nodrošināta: atkārtojot to pašu atsauces vērtību, ziņojums var tikt nosūtīts un maksa ieturēta vēlreiz.

Vietējā piegāde un jaukti rezultāti

Vietēji uzturētiem numuriem ziņojumi var tikt pieņemti (accepted) MultiTEL ienākošo ziņojumu plūsmā bez sūtīšanas caur ārēju operatoru. Ja pieprasījumā ir tikai vietējie adresāti, atbildē var būt iekļauti accepted, message_id, provider un delivery_status. Vietējā pieņemšana negarantē, ka saņēmēja konfigurētais pārsūtīšanas galamērķis darbojās.

Pārbaudiet local_delivery_results un partial, ja tie ir norādīti. Saņēmējam var būt norādīts accepted true, lai gan pārsūtīšana nav izdevusies. Jauktā pieprasījumā operatora saņēmējiem ziņojumi var būt pieņemti (accepted), bet vietējā daļa var būt neizdevusies. Neatkārtojiet visu sūtījumu kopu automātiski: vispirms salīdziniet un noskaidrojiet katra saņēmēja rezultātus.

Ja pieņemti ziņojumi tikai vietējiem adresātiem, šajā apstrādes ceļā tiek norādīta nulles izejošās sūtīšanas maksa, tomēr saņēmējiem joprojām var tikt piemērota parastā maksa par ienākošajiem ziņojumiem. Neuzskatiet nulles izejošās sūtīšanas maksu par garantiju, ka maksa netiek ieturēta nevienā kontā.

Atpakaļizsaukumi un datu sasaiste

Ja ir norādīts notifyurl, sākotnējais atpakaļizsaukums ietver status apvalku un atbildes laukus, tostarp message_id, reference, from, to, status, status_text, error_code, timestamp un accepted. Var būt iekļauti arī vietējie rezultāti. Saglabājiet sasaistes informāciju, neierakstot žurnālos API piekļuves datus vai nevajadzīgu ziņojumu saturu.

Šis apstrādātājs sākotnējam atpakaļizsaukumam nepievieno parakstīšanas lauku. Neizmantojiet nepārbaudītu atpakaļizsaukumu kā patstāvīgu pilnvarojumu citai darbībai. Skatiet savam kontam atbalstīto integrācijas un tīmekļa aizķeru konfigurāciju un neskaidrus rezultātus salīdziniet ar portāla ierakstiem vai noskaidrojiet atbalsta dienestā. Nepieņemiet, ka atpakaļizsaukumi pienāk tikai vienu reizi vai galīgās piegādes secībā.

Kļūmes un droša darbības atjaunošana

Validācijas kļūmēm var tikt izmantots API kods 403. Noraidījumi konta apstiprinājuma, P2P vai valsts politikas dēļ var arī iestatīt HTTP 403 un ietvert mašīnlasāmu response.code. Pieprasījumu biežuma ierobežojumiem var tikt izmantots 429 ar informāciju par atkārtotu mēģinājumu. Ja politika nav pieejama vai rodas sūtīšanas vai vietējās datu saglabāšanas kļūme, var tikt izmantots 503 vai 500; arī nepietiekams atlikums mantotajā apstrādē var atgriezt 500.

Saņemot 429, ievērojiet Retry-After un jebkuru norādīto response.retry_after vērtību. Ja noraidījums attiecas uz kontu, sūtītāju, valsti vai saņēmēju, pirms atkārtota mēģinājuma novērsiet cēloni. Ja iestājusies noildze vai sūtīšanas rezultāts ir neskaidrs, saglabājiet pieprasījuma laiku, atsauces vērtību un atgrieztos identifikatorus, pārbaudiet portālu un pirms atkārtotas sūtīšanas sazinieties ar atbalsta dienestu. Žurnāla ieraksta neesamība pati par sevi nepierāda, ka neviens operators nav pieņēmis pieprasījumu.