Ennen lähettämistä
Lähetä SMS-viesti tai tuettu MMS-viesti tilillesi määritetyllä lähetysnumerolla. Tämä on tuotantotoiminto, joka voi ottaa yhteyttä vastaanottajiin ja aiheuttaa veloituksia. Lähetä vain vastaanottajille, joihin sinulla on lupa ottaa yhteyttä, ja vain hyväksyttyä viestiliikennettä; alla olevat esimerkkinumerot ja viite ovat kuvitteellisia.
Tililläsi on oltava hyväksyntä lähtevälle viestiliikenteelle sekä tarvittavat lähettäjä-, maa- ja liikennekohtaiset luvat. Personal/Consumer-käyttäjän tunnuksia ei voi käyttää suoraan tässä API:ssa. Hyväksyttyjen, erikseen API-käyttöön tarkoitettujen tunnusten käyttökelpoisuus määräytyy erillisen menettelyn kautta; mobiilien P2P-lähettäjien käyttö voi edellyttää lisäksi P2P-lupia sekä Yhdysvaltoja ja Kanadaa koskevia lupia. Varmista tilin oikeat asetukset MultiTELiltä äläkä pidä API-tunnusta automaattisena lupana kaikenlaisen viestiliikenteen lähettämiseen.
Lähetyspyyntö
Tunnistaudu HTTPS-yhteydellä käyttäen käytössä olevaa API-tiliä ja sille sallittua lähde-IP-osoitetta. Säilytä tunnukset palvelinpuolen salaisuuksien säilytyspaikassa. Käytä POST-menetelmää lomakekoodatuilla kentillä tai JSON-objektia, kun lomake- tai kyselykenttiä ei anneta. Älä sisällytä tunnuksia tai viestin tekstiä URL-osoitteeseen.
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| Kenttä | Pakollinen | Merkitys |
|---|---|---|
| from | Kyllä | Määritetty lähetysnumerosi, mieluiten kokonaisena kansainvälisenä numerona pelkillä numeroilla. |
| to | Kyllä | Yksi kohdenumero, pilkuilla erotetut kohdenumerot tai JSON-taulukko. Käytä mieluiten kokonaisia kansainvälisiä numeroita pelkillä numeroilla. Ryhmäpyyntö voidaan hylätä siihen sovellettavien P2P- tai maakohtaisten rajoitusten perusteella; kyseessä ei ole rajoittamaton massalähetysrajapinta. |
| text | SMS-viesteille | Viestin teksti UTF-8-muodossa. Vähintään ei-tyhjä teksti tai mediasisältö vaaditaan. Lähetä varsinaiset merkit ja rivinvaihdot HTML:n tai prosenttikoodatun tekstin sijaan. Jotkin operaattorireitit normalisoivat kirjaimellisia ohjaussekvenssimerkkijonoja. |
| media | Vain mediaa sisältäville MMS-viesteille | Mediasisältö Base64-koodattuna, ei URL-osoite tai tiedostopolku. MMS:n saatavuus, muoto ja koko riippuvat määritetystä reitistä. Varmista tuetut mediasisällöt MultiTELiltä; tämä käsittelijä ei määritä yleispätevää mediasisällön kokorajaa. |
| reference | Suositeltu | Oma viitteesi tietojen yhdistämistä varten; se säilytetään tietueissa ja takaisinkutsuissa. Lisää viite vianmääritystä varten. Se ei ole idempotenssiavain. |
| notifyurl | Ei | Oma HTTPS-takaisinkutsujen vastaanottajasi. Käsittelijä voi lähettää alustavan tuloksen POST-pyynnöllä käsittelyn jälkeen. Vastaanottajan on oltava hallinnassasi, eikä osoite saa olla sisäisen palvelun URL-osoite. |
Kun käytät JSON-taulukkoa, anna to-kenttään oikea taulukko; älä sijoita JSON-taulukkoa merkkijonona lomakekenttään. Tee ensimmäinen integraatiotesti lähettämällä yhdelle vastaanottajalle. Ryhmälähetysten ja MMS-viestien tuki vaihtelee reiteittäin, joten varmista tuettu yhdistelmä ennen niiden käyttöä.
Lue koko tulos
Esimerkissä näytetään vain valikoidut kentät; esitetty hinta ei ole hintatarjous.
{
"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"
}
}Tarkista yhdessä HTTP-tilakoodi, JSON-vastauksen status.code ja vastauksen status/message. Tuloskoodit voivat olla merkkijonoja. Säilytä sms_log_id_ori ja palautetut viesti- ja viitearvot, jotta tuki voi yhdistää tiedot toisiinsa. Vanhan vastausmuodon uniqueid- ja pid-arvot vaihtelevat reiteittäin; älä päättele niiden muotoa tai oleta niiden olevan asiakassovelluksen idempotenssitunnisteita.
Success tai Message queued tarkoittaa tavallisesti, että valittu reitti on hyväksynyt viestin, ei sitä, että viesti olisi saapunut vastaanottajan puhelimeen. Alustavan takaisinkutsun tila, kuten sent, ei yksin osoita lopullista toimitusta.
Viestiosat ja veloitukset
Käytä SMS-pituusanalyysiä koko lopulliseen tekstiin ennen lähettämistä. SMS-hinnat riippuvat kohteesta ja tilin palvelusta; sovellettavat operaattorimaksut lisätään viestiosakohtaisesti. Lähetyksen käsittelypolku laskee yhteen vastaanottajakohtaiset hinnat ja sovellettavat maksut ja kertoo summan sitten lasketulla SMS-viestiosien määrällä. Tässä laskennassa MMS-pyyntö käsitellään yhtenä viestinä.
cost ja permsg ovat muotoiltuja rahasummamerkkijonoja vanhassa vastausmuodossa. carrier_fee_usd ilmoittaa operaattorimaksun osuuden valuutassa USD, ja tämä osuus sisältyy jo laskettuun lähetyksen kokonaissummaan; älä lisää sitä toistamiseen. Tilisi todellinen hinnoittelu ja reittien saatavuus on tarkistettava tilikohtaisesti. Pyyntö ei ole pelkkä hintakysely.
Katselmoitu koodi tekee veloituksen onnistuneen operaattorilähetyksen käsittelypolun jälkeen, mutta operaattorin hyväksyntä, paikallinen pysyväistallennus ja laskutus eivät muodosta yhtä transaktiota. Virhe tai aikakatkaisu voi tapahtua sen jälkeen, kun ylemmälle palvelulle lähetetty pyyntö on hyväksytty. Asiakassovellukselle ei ole tarjolla idempotenssiavainta: saman viitteen käyttäminen uudelleen voi aiheuttaa uuden lähetyksen ja veloituksen.
Paikallinen toimitus ja yhdistelmäpyyntöjen tulokset
Paikallisesti ylläpidettyihin numeroihin lähetetyt viestit voidaan hyväksyä (accepted) MultiTELin saapuvien viestien käsittelyyn ilman lähetystä ulkoiselle operaattorille. Jos kaikki pyynnön vastaanottajat ovat paikallisia, vastaus voi sisältää kentät accepted, message_id, provider ja delivery_status. Paikallinen hyväksyntä ei takaa, että vastaanottajalle määritetty edelleenlähetyskohde toimi.
Tarkista local_delivery_results ja partial, jos ne ovat mukana. Vastaanottajan accepted-kentän arvo voi olla true, vaikka edelleenlähetys epäonnistuisi. Yhdistelmäpyynnössä voi olla operaattorin hyväksymiä (accepted) vastaanottajia ja epäonnistunut paikallinen osuus. Älä yritä koko erää automaattisesti uudelleen: selvitä ensin jokaisen vastaanottajan tulos.
Kun kaikki vastaanottajat ovat paikallisia ja pyyntö hyväksytään, tässä käsittelypolussa ilmoitetaan lähtevän liikenteen kustannukseksi nolla, mutta vastaanottajille voi silti aiheutua tavallisia saapuvien viestien maksuja. Älä tulkitse lähtevän liikenteen nollakustannusta takeeksi siitä, ettei mitään tiliä veloiteta.
Takaisinkutsut ja tietojen yhdistäminen
Kun notifyurl annetaan, alustava takaisinkutsu sisältää status-ylätason rakenteen sekä vastauskenttiä, joihin kuuluvat message_id, reference, from, to, status, status_text, error_code, timestamp ja accepted. Mukana voi olla myös paikallisia tuloksia. Tallenna tietojen yhdistämiseen tarvittavat tiedot kirjaamatta lokiin API-tunnuksia tai tarpeettomia viestisisältöjä.
Tämä käsittelijä ei lisää allekirjoituskenttää kyseiseen alustavaan takaisinkutsuun. Älä käytä todentamatonta takaisinkutsua yksinään valtuutuksena toiselle toiminnolle. Selvitä tilillesi tuetut integraatio- ja webhook-asetukset ja selvitä epävarmat tulokset portaalin tietueiden tai tuen avulla. Älä oleta, että takaisinkutsut saapuvat vain kerran tai lopullisten toimitusten mukaisessa järjestyksessä.
Virheet ja turvallinen palautuminen
Validointivirheet voivat käyttää API-koodia 403. Tilin hyväksyntään, P2P-käytäntöihin ja maakohtaisiin käytäntöihin perustuvat hylkäykset voivat myös asettaa HTTP-tilakoodiksi 403 ja sisältää koneluettavan response.code-kentän. Pyyntötiheyden rajoitukset voivat käyttää koodia 429 ja sisältää uudelleenyritystietoja. Jos käytäntö ei ole saatavilla tai lähetys tai paikallinen pysyväistallennus epäonnistuu, koodi voi olla 503 tai 500; myös vanhan toteutuksen riittämätön saldo voi palauttaa koodin 500.
Noudata koodin 429 yhteydessä Retry-After-otsaketta ja mahdollista response.retry_after-arvoa. Jos hylkäys liittyy tiliin, lähettäjään, maahan tai vastaanottajaan, korjaa sen syy ennen uudelleenyritystä. Jos tapahtuu aikakatkaisu tai lähetyksen tulos on epäselvä, säilytä pyynnön ajankohta, viite ja palautetut tunnisteet, tarkista portaali ja ota yhteyttä tukeen ennen uudelleenlähetystä. Pelkkä lokimerkinnän puuttuminen ei todista, ettei mikään operaattori hyväksynyt pyyntöä.