Innan du skickar
Skicka ett SMS eller ett MMS som stöds med ett avsändarnummer som är konfigurerat för ditt konto. Detta är en åtgärd i produktionsmiljön som kan kontakta mottagare och medföra avgifter. Skicka endast till mottagare som du har tillstånd att kontakta och använd endast godkänd trafik; exempelnumren och referensen nedan är fiktiva.
Ditt konto behöver vara godkänt för utgående meddelanden och ha de tillstånd som krävs för avsändare, länder och trafik. Användaruppgifter för direkt användning av personliga konton eller konsumentkonton är inte behöriga för detta API. Godkända, särskilda API-inloggningsuppgifter omfattas av en separat behörighetsprövning; mobila P2P-avsändare kan behöva ytterligare tillstånd för P2P och USA/Kanada. Bekräfta rätt kontokonfiguration med MultiTEL i stället för att betrakta API-inloggningsuppgifter som ett automatiskt tillstånd att skicka all slags trafik.
Skicka anropet
Autentisera över HTTPS med ett aktiverat API-konto från dess tillåtna käll-IP-adress. Förvara inloggningsuppgifterna i ett hemlighetslager på serversidan. Använd POST med formulärkodade fält, eller ett JSON-objekt när inga formulärfält eller frågeparametrar anges. Lägg inte inloggningsuppgifter eller meddelandetext i en 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| Fält | Obligatoriskt | Betydelse |
|---|---|---|
| from | Ja | Ditt konfigurerade avsändarnummer, helst med alla siffror i internationellt format. |
| to | Ja | En destination, kommaseparerade destinationer eller en JSON-array. Använd helst alla siffror i internationellt format. Ett gruppanrop kan avvisas på grund av tillämpliga P2P- eller landsbegränsningar; detta är inte ett API för obegränsade massutskick. |
| text | För SMS | Meddelandetext i UTF-8. Minst en icke-tom text eller medieinnehåll krävs. Skicka faktiska tecken och radbrytningar i stället för HTML eller procentkodad text. Vissa operatörsvägar normaliserar escape-sekvenser som angetts som bokstavlig text. |
| media | För MMS med enbart medieinnehåll | Base64-kodat medieinnehåll, inte en URL eller filsökväg. Tillgänglighet, format och storlek för MMS beror på den konfigurerade rutten. Bekräfta vilka medier som stöds med MultiTEL; denna hanterare fastställer ingen generell storleksgräns för medieinnehåll. |
| reference | Rekommenderas | Din korrelationsetikett, som sparas i poster och återanrop. Ange en sådan för felsökning. Den är inte en idempotensnyckel. |
| notifyurl | Nej | Din HTTPS-mottagare för återanrop. Hanteraren kan skicka ett inledande resultat med POST efter bearbetningen. Det måste vara en mottagare som du kontrollerar, och adressen får inte vara en URL till en intern tjänst. |
För en JSON-array ska du använda en riktig array i to; lägg inte en sträng som innehåller en JSON-array i ett formulärfält. Använd sändning till en enda mottagare som det första integrationstestet. Stödet för grupper och MMS skiljer sig mellan rutter, så bekräfta vilken kombination som stöds innan du använder dem.
Läs hela resultatet
Endast utvalda fält visas som illustration; den visade kostnaden är ingen offert.
{
"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"
}
}Kontrollera HTTP-status, status.code i JSON och svarets status/message tillsammans. Resultatkoder kan vara strängar. Spara sms_log_id_ori och de returnerade meddelande- och referensvärdena så att supporten kan koppla ihop uppgifterna. Värdena för de äldre fälten uniqueid och pid varierar mellan rutter; dra inga slutsatser om deras format och anta inte att de är idempotens-token för klienten.
Success eller Message queued beskriver normalt att den valda rutten har accepterat meddelandet, inte att det har tagits emot på en persons mobiltelefon. En status i ett inledande återanrop, såsom sent, fastställer inte i sig att slutlig leverans har skett.
Segment och avgifter
Använd Analys av SMS-längd på hela den slutliga texten innan du skickar. SMS-priser beror på destinationen och kontots tjänst; tillämpliga operatörsavgifter läggs till per segment. Sändningsflödet summerar mottagarpriser och tillämpliga avgifter och multiplicerar sedan summan med det beräknade antalet SMS-segment. I denna beräkning behandlas ett MMS-anrop som ett meddelande.
cost och permsg är formaterade strängar med penningbelopp i det äldre svarsformatet. carrier_fee_usd anger operatörsavgiftens del i USD och ingår redan i den beräknade totalkostnaden för sändningen; lägg inte till den en gång till. Du måste kontrollera vilka faktiska priser och tillgängliga rutter som gäller för ditt konto. Anropet är inte en åtgärd som enbart hämtar ett pris.
Den granskade koden debiterar efter att sändningsflödet till operatören har lyckats, men operatörens acceptans, lokal lagring och debitering utgör inte en enda transaktion. Ett fel eller en timeout kan inträffa efter att ett anrop till en uppströms tjänst har accepterats. Ingen idempotensnyckel görs tillgänglig för klienten: om samma referens används igen kan meddelandet skickas och debiteras på nytt.
Lokal leverans och blandade resultat
Nummer som hanteras lokalt kan tas emot med accepted i MultiTELs flöde för inkommande meddelanden utan sändning via en extern operatör. För ett anrop med enbart lokala mottagare kan svaret innehålla accepted, message_id, provider och delivery_status. Lokal acceptans garanterar inte att mottagarens konfigurerade destination för vidarebefordran fungerade.
Granska local_delivery_results och partial när de finns. En mottagare kan visa accepted true samtidigt som vidarebefordran misslyckas. Ett blandat anrop kan ha operatörsmottagare med accepted och en misslyckad lokal del. Försök inte automatiskt skicka hela gruppen igen: stäm först av resultatet för varje mottagare.
När enbart lokala mottagare accepteras rapporteras ingen utgående kostnad i detta flöde, men mottagarna kan fortfarande debiteras sina normala avgifter för inkommande meddelanden. Tolka inte en utgående kostnad på noll som en garanti för att inget konto debiteras.
Återanrop och korrelation
När notifyurl anges har det inledande återanropet ett omslutande status-objekt och svarsfält som inkluderar message_id, reference, from, to, status, status_text, error_code, timestamp och accepted. Lokala resultat kan också finnas med. Spara korrelationsinformation utan att logga API-inloggningsuppgifter eller onödigt meddelandeinnehåll.
Denna hanterare lägger inte till något signeringsfält i det inledande återanropet. Använd inte ett overifierat återanrop som enda behörighetsgrund för en annan åtgärd. Ta reda på vilken konfiguration för integrationer och webhooks som stöds för ditt konto och stäm av osäkra resultat mot poster i portalen eller med supporten. Anta inte att återanrop kommer exakt en gång eller i samma ordning som den slutliga leveransen.
Fel och säker återhämtning
Valideringsfel kan använda API-kod 403. Avslag som gäller kontogodkännande, P2P eller landspolicy kan också sätta HTTP 403 och inkludera en maskinläsbar response.code. Begränsningar av anropsfrekvensen kan använda 429 med information om nya försök. En otillgänglig policy eller ett fel vid sändning eller lokal lagring kan använda 503 eller 500; äldre hantering av otillräckligt saldo kan också returnera 500.
Vid 429 ska du följa Retry-After och eventuella värden i response.retry_after. Vid avvisning som gäller konto, avsändare, land eller mottagare ska du åtgärda orsaken innan du försöker igen. Vid timeout eller ett oklart sändningsresultat ska du spara anropstidpunkten, referensen och returnerade identifierare, granska portalen och kontakta supporten innan du skickar igen. Att en loggpost saknas är inte i sig ett bevis på att ingen operatör accepterade anropet.