Før afsendelse
Send en SMS eller en understøttet MMS med et afsendernummer, der er konfigureret til din konto. Dette er en handling i produktionsmiljøet, som kan kontakte modtagere og medføre opkrævninger. Brug kun modtagere, du har tilladelse til at kontakte, og godkendt trafik; eksempelnumrene og referencen nedenfor er fiktive.
Din konto skal være godkendt til udgående beskeder og have de relevante tilladelser til afsender, land og trafik. Direkte brugerloginoplysninger til Personal/Consumer kan ikke bruges til denne API. Godkendte, dedikerede API-loginoplysninger har en særskilt adgangsprocedure; mobile P2P-afsendere kan kræve yderligere tilladelser til P2P og USA/Canada. Få MultiTEL til at bekræfte den korrekte kontoopsætning i stedet for at betragte API-loginoplysninger som automatisk tilladelse til at sende enhver form for trafik.
Send anmodning
Autentificer via HTTPS med en aktiveret API-konto fra dens tilladte kilde-IP-adresse. Opbevar loginoplysninger i et hemmelighedslager på serversiden. Brug POST med formularkodede felter eller et JSON-objekt, når der hverken angives formularfelter eller forespørgselsfelter. Anbring ikke loginoplysninger eller beskedtekst 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| Felt | Påkrævet | Betydning |
|---|---|---|
| from | Ja | Dit konfigurerede afsendernummer, helst som alle cifrene i det fulde internationale nummer. |
| to | Ja | Én destination, kommaseparerede destinationer eller et JSON-array. Brug helst alle cifrene i de fulde internationale numre. En gruppeanmodning kan blive afvist på grund af de gældende P2P-/landegrænser; dette er ikke en API til ubegrænset masseafsendelse. |
| text | Til SMS | Beskedtekst i UTF-8. Der kræves som minimum tekst, der ikke er tom, eller medieindhold. Send faktiske tegn og linjeskift frem for HTML eller procentkodet tekst. Nogle operatørforløb normaliserer escape-sekvenser, der er angivet som bogstavelige strenge. |
| media | Til MMS med kun medieindhold | Base64-kodet medieindhold, ikke en URL eller filsti. Tilgængeligheden af MMS samt format og størrelse afhænger af den konfigurerede rute. Få MultiTEL til at bekræfte, hvilke medier der understøttes; denne handler fastlægger ingen universel grænse for mediestørrelse. |
| reference | Anbefalet | Din korrelationsmærkat, som gemmes i registreringer og callbacks. Medtag en til fejlfinding. Den er ikke en idempotensnøgle. |
| notifyurl | Nej | Din HTTPS-modtager til callbacks. Handleren kan sende et indledende resultat med POST efter behandlingen. Det skal være en modtager, du kontrollerer, og det må ikke være en URL til en intern tjeneste. |
Ved brug af et JSON-array skal du bruge et egentligt array i to; anbring ikke en streng med et JSON-array i et formularfelt. Brug afsendelse til én modtager som den første integrationstest. Understøttelse af grupper og MMS varierer mellem ruter, så bekræft den understøttede kombination, før du bruger dem.
Læs hele resultatet
Kun udvalgte felter til illustration; den viste pris er ikke et pristilbud.
{
"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"
}
}Kontrollér HTTP-status, JSON-feltet status.code og svarets status/message samlet. Resultatkoder kan være strenge. Gem sms_log_id_ori og de returnerede besked-/referenceværdier, så support kan sammenholde dem. Værdierne for de ældre felter uniqueid og pid varierer mellem ruter; udled ikke deres format, og antag ikke, at de er idempotens-tokens for klienten.
Success eller Message queued beskriver normalt accept på den valgte rute, ikke modtagelse på en persons mobiltelefon. En indledende callback-status som sent dokumenterer ikke i sig selv endelig levering.
Segmenter og opkrævninger
Brug Analyse af SMS-længde på hele den endelige tekst før afsendelse. SMS-priser afhænger af destinationen og tjenesten på kontoen; relevante operatørgebyrer tilføjes pr. segment. Afsendelsesforløbet lægger modtagerpriser og relevante gebyrer sammen og ganger derefter med det beregnede antal SMS-segmenter. I denne beregning behandles en MMS-anmodning som én besked.
cost og permsg er formaterede beløbsstrenge i det ældre svarformat. carrier_fee_usd angiver operatørgebyrandelen i USD og er allerede inkluderet i det beregnede samlede afsendelsesbeløb; tilføj den ikke igen. De faktiske priser og ruternes tilgængelighed skal kontrolleres for din konto. Anmodningen er ikke en handling, der kun beregner en pris.
Den gennemgåede kode debiterer efter sit vellykkede forløb for afsendelse via operatøren, men operatørens accept, lokal lagring og fakturering udgør ikke én samlet transaktion. En fejl eller timeout kan opstå, efter at en anmodning til et forudgående system er blevet accepteret. Der stilles ingen idempotensnøgle til rådighed for klienten: gentagelse af samme reference kan medføre ny afsendelse og opkrævning.
Lokal levering og blandede resultater
Numre, der hostes lokalt, kan få status accepted i MultiTELs forløb for indgående beskeder uden afsendelse via en ekstern operatør. For en anmodning med udelukkende lokale modtagere kan svaret indeholde accepted, message_id, provider og delivery_status. Lokal accept garanterer ikke, at modtagerens konfigurerede videresendelsesdestination fungerede.
Undersøg local_delivery_results og partial, når de er til stede. En modtager kan vise accepted true, selv om videresendelsen mislykkedes. En blandet anmodning kan have operatørmodtagere med status accepted og en lokal del, der mislykkedes. Forsøg ikke automatisk at sende hele gruppen igen: afstem først resultatet for hver modtager.
Accept af en anmodning med udelukkende lokale modtagere angiver ingen udgående omkostninger i dette forløb, mens modtagerne stadig kan blive pålagt deres normale omkostninger for indgående beskeder. Fortolk ikke udgående omkostninger på nul som en garanti for, at ingen konto debiteres.
Callbacks og korrelation
Når notifyurl angives, har det indledende callback en status-omslutning og svarfelter, herunder message_id, reference, from, to, status, status_text, error_code, timestamp og accepted. Lokale resultater kan også være til stede. Gem korrelationsoplysninger uden at logge API-loginoplysninger eller unødvendigt beskedindhold.
Denne handler tilføjer ikke et signaturfelt til det indledende callback. Brug ikke et ubekræftet callback som eneste autorisation til en anden handling. Se den understøttede integrations-/webhookopsætning for din konto, og afstem usikre resultater med registreringer i portalen eller med support. Antag ikke, at callbacks kun ankommer én gang eller i rækkefølgen for endelig levering.
Fejl og sikker genopretning
Valideringsfejl kan bruge API-kode 403. Afvisninger vedrørende kontogodkendelse, P2P og landepolitikker kan også sætte HTTP 403 og inkludere en maskinlæsbar response.code. Begrænsninger af anmodningsfrekvensen kan bruge 429 med oplysninger om et nyt forsøg. En utilgængelig politik eller en fejl ved afsendelse eller lokal lagring kan bruge 503 eller 500; utilstrækkelig saldo i det ældre forløb kan også returnere 500.
Ved 429 skal du overholde Retry-After og en eventuel værdi i response.retry_after. Ved afvisning af konto, afsender, land eller modtager skal du rette årsagen, før du prøver igen. Ved timeout eller et uklart afsendelsesresultat skal du gemme anmodningstidspunktet, referencen og de returnerede identifikatorer, undersøge portalen og kontakte support, før du sender igen. En manglende logregistrering er ikke i sig selv bevis for, at ingen operatør accepterede anmodningen.