Før sending
Send en SMS eller en støttet MMS med et avsendernummer som er konfigurert for kontoen din. Dette er en operasjon i produksjon som kan kontakte mottakere og påføre kostnader. Bruk bare mottakere du har tillatelse til å kontakte, og godkjent trafikk; eksempelnumrene og referansen nedenfor er fiktive.
Kontoen din må være godkjent for utgående meldinger og ha de nødvendige tillatelsene for avsender, land og trafikk. Brukerpåloggingsopplysninger direkte fra personlige kontoer eller forbrukerkontoer kan ikke brukes med dette API-et. Godkjente, dedikerte API-påloggingsopplysninger har en egen prosess for å kvalifisere til bruk; mobile P2P-avsendere kan kreve ytterligere tillatelser for P2P og USA/Canada. Bekreft riktig kontooppsett med MultiTEL i stedet for å behandle API-påloggingsopplysninger som automatisk tillatelse til å sende all slags trafikk.
Send forespørsel
Autentiser over HTTPS med en aktivert API-konto fra kontoens tillatte kilde-IP-adresse. Oppbevar påloggingsopplysninger i et hemmelighetslager på serversiden. Bruk POST med skjemakodede felt, eller et JSON-objekt når ingen skjema- eller spørringsfelt er angitt. Ikke legg påloggingsopplysninger eller meldingstekst 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åkrevd | Betydning |
|---|---|---|
| from | Ja | Det konfigurerte avsendernummeret ditt, helst med alle sifrene i internasjonalt format. |
| to | Ja | Én mottaker, kommaseparerte mottakere eller en JSON-liste. Bruk helst alle sifrene i internasjonalt format. En gruppeforespørsel kan bli avvist på grunn av gjeldende P2P- eller landsbegrensninger; dette er ikke et API for ubegrenset masseutsending. |
| text | For SMS | Meldingstekst i UTF-8. Det kreves minst enten tekst som ikke er tom, eller medieinnhold. Send faktiske tegn og linjeskift i stedet for HTML eller prosentkodet tekst. Noen operatørruter normaliserer bokstavelige escape-sekvenser. |
| media | For MMS med bare medieinnhold | Base64-kodet medieinnhold, ikke en URL eller filsti. Tilgjengelighet, format og størrelse for MMS avhenger av den konfigurerte ruten. Bekreft støttede medier med MultiTEL; denne behandleren fastsetter ingen universell størrelsesgrense for medier. |
| reference | Anbefalt | Din etikett for å koble sammen opplysninger, som beholdes i oppføringer og tilbakemeldingskall. Ta med en slik etikett for feilsøking. Den er ikke en idempotensnøkkel. |
| notifyurl | Nei | Din HTTPS-mottaker for tilbakemeldingskall. Behandleren kan sende et innledende resultat med POST etter behandling. Dette må være en mottaker du kontrollerer, og URL-en må ikke peke til en intern tjeneste. |
For en JSON-liste må du bruke en faktisk liste i to; ikke legg en streng som inneholder en JSON-liste, i et skjemafelt. Bruk sending til én mottaker som den første integrasjonstesten. Støtte for grupper og MMS varierer mellom rutene, så bekreft at kombinasjonen støttes før du bruker den.
Les hele resultatet
Bare utvalgte felt vises som illustrasjon; den viste kostnaden 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"
}
}Kontroller HTTP-status, JSON-feltet status.code og svarets status/message samlet. Resultatkoder kan være strenger. Ta vare på sms_log_id_ori og de returnerte meldings- og referanseverdiene slik at kundestøtte kan koble sammen opplysningene. Verdiene i de eldre feltene uniqueid og pid varierer mellom rutene; ikke utled formatet deres eller anta at de er idempotenstokener for klienten.
Success eller Message queued beskriver vanligvis at den valgte ruten har akseptert meldingen, ikke at den er mottatt på en persons mobiltelefon. En innledende status i et tilbakemeldingskall, som sent, bekrefter ikke i seg selv endelig levering.
Segmenter og kostnader
Bruk Analyse av SMS-lengde på hele den endelige teksten før sending. SMS-priser avhenger av mottakerstedet og kontotjenesten; gjeldende operatørgebyrer legges til per segment. Sendingsløpet summerer mottakerprisene og gjeldende gebyrer og multipliserer deretter med det beregnede antallet SMS-segmenter. I denne beregningen behandles en MMS-forespørsel som én melding.
cost og permsg er formaterte strenger med pengebeløp i det eldre svarformatet. carrier_fee_usd oppgir operatørgebyrdelen i USD, og denne er allerede inkludert i den beregnede totalsummen for sendingen; ikke legg den til på nytt. Du må kontrollere de faktiske prisene og tilgjengelige rutene for kontoen din. Forespørselen er ikke en operasjon som bare henter pris.
Den gjennomgåtte koden belaster kontoen etter en vellykket operatørsending, men operatørens aksept, lokal lagring og fakturering utgjør ikke én transaksjon. En feil eller et tidsavbrudd kan oppstå etter at en forespørsel er akseptert av en oppstrømstjeneste. Ingen idempotensnøkkel er tilgjengelig for klienten: gjentatt bruk av samme referanse kan føre til ny sending og ny belastning.
Lokal levering og blandede resultater
Numre som driftes lokalt, kan få statusen accepted i MultiTELs flyt for innkommende meldinger uten sending via en ekstern operatør. For en forespørsel med bare lokale mottakere kan svaret inneholde accepted, message_id, provider og delivery_status. Lokal aksept garanterer ikke at mottakerens konfigurerte mål for videresending fungerte.
Undersøk local_delivery_results og partial når de finnes. En mottaker kan vise accepted med verdien true selv om videresendingen mislyktes. En blandet forespørsel kan ha operatørmottakere med statusen accepted og en mislykket lokal del. Ikke prøv hele gruppen på nytt automatisk: avstem resultatet for hver mottaker først.
Når en forespørsel med bare lokale mottakere aksepteres, rapporteres null utgående kostnad i dette behandlingsløpet, mens mottakerne fortsatt kan bli belastet sine vanlige kostnader for innkommende meldinger. Ikke tolk null utgående kostnad som en garanti for at ingen konto blir belastet.
Tilbakemeldingskall og sammenkobling av opplysninger
Når notifyurl er angitt, har det innledende tilbakemeldingskallet en omsluttende status-struktur og svarfelt som inkluderer message_id, reference, from, to, status, status_text, error_code, timestamp og accepted. Lokale resultater kan også være med. Lagre opplysninger som gjør det mulig å koble sammen hendelser, uten å logge API-påloggingsopplysninger eller unødvendig meldingsinnhold.
Denne behandleren legger ikke til et signaturfelt i det innledende tilbakemeldingskallet. Ikke bruk et ubekreftet tilbakemeldingskall som eneste autorisasjon for en annen handling. Se oppsettet for integrasjoner og webhooks som støttes for kontoen din, og avstem usikre resultater mot oppføringer i portalen eller med kundestøtte. Ikke anta at tilbakemeldingskall kommer bare én gang eller i rekkefølgen for endelig levering.
Feil og trygg gjenoppretting
Valideringsfeil kan bruke API-kode 403. Avslag knyttet til kontogodkjenning, P2P og landregler kan også sette HTTP 403 og inkludere en maskinlesbar response.code. Frekvensbegrensninger kan bruke 429 med informasjon om nytt forsøk. Et utilgjengelig regelsett eller en feil ved sending eller lokal lagring kan bruke 503 eller 500; utilstrekkelig saldo i eldre behandling kan også returnere 500.
Ved 429 må du følge Retry-After og en eventuell verdi i response.retry_after. Ved avslag knyttet til konto, avsender, land eller mottaker må du rette årsaken før du prøver på nytt. Ved tidsavbrudd eller et uklart sendingsresultat må du ta vare på tidspunktet for forespørselen, referansen og de returnerte identifikatorene, undersøke portalen og kontakte kundestøtte før du sender på nytt. En manglende loggoppføring er ikke alene bevis for at ingen operatør aksepterte forespørselen.