Voordat jy stuur
Stuur 'n SMS of ondersteunde MMS met 'n versendingsnommer wat vir jou rekening opgestel is. Dit is 'n bewerking in die produksieomgewing wat ontvangers kan kontak en heffings kan veroorsaak. Gebruik slegs gemagtigde ontvangers en goedgekeurde boodskapverkeer; die voorbeeldnommers en verwysing hieronder is fiktief.
Jou rekening benodig goedkeuring vir uitgaande boodskappe en die toepaslike toestemmings vir die sender, land en boodskapverkeer. Direkte aanmeldbesonderhede vir persoonlike/verbruikersgebruikers kwalifiseer nie vir hierdie API nie. Goedgekeurde, toegewyde API-aanmeldbesonderhede het 'n afsonderlike kwalifiseringsproses; mobiele P2P-senders kan bykomende P2P-toestemmings en toestemmings vir die VSA/Kanada benodig. Bevestig die korrekte rekeningopstelling met MultiTEL eerder as om API-aanmeldbesonderhede as outomatiese toestemming te beskou om enige boodskapverkeer te stuur.
Versendingsversoek
Verifieer jou identiteit oor HTTPS met 'n geaktiveerde API-rekening vanaf die toegelate bron-IP-adres daarvan. Bewaar aanmeldbesonderhede in geheimeberging aan die bedienerkant. Gebruik POST met vormgekodeerde velde, of 'n JSON-objek wanneer geen vorm- of navraagvelde verskaf word nie. Moenie aanmeldbesonderhede of boodskapteks in 'n URL plaas nie.
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| Veld | Vereis | Betekenis |
|---|---|---|
| from | Ja | Jou opgestelde versendingsnommer, verkieslik die volledige nommer in internasionale syferformaat. |
| to | Ja | Een bestemming, bestemmings wat deur kommas geskei word, of 'n JSON-skikking. Gebruik verkieslik volledige nommers in internasionale syferformaat. 'n Groepversoek kan weens die toepaslike P2P-/landsbeperkings verwerp word; dit is nie 'n onbeperkte API vir massaversending nie. |
| text | Vir SMS | UTF-8-boodskapteks. Minstens nieleë teks of media word vereis. Stuur werklike karakters en reëlbreuke eerder as HTML of persentgekodeerde teks. Sommige diensverskafferpaaie normaliseer letterlike ontsnapreekse. |
| media | Vir MMS wat slegs media bevat | Base64-gekodeerde media-inhoud, nie 'n URL of lêerpad nie. MMS-beskikbaarheid, -formaat en -grootte hang van die opgestelde roete af. Bevestig ondersteunde media met MultiTEL; hierdie hanteerder stel geen universele mediagroottebeperking vas nie. |
| reference | Aanbeveel | Jou korrelasie-etiket, wat in rekords/terugroepe behou word. Sluit een in vir foutopsporing. Dit is nie 'n idempotensiesleutel nie. |
| notifyurl | Nee | Jou HTTPS-terugroepontvanger. Die hanteerder kan ná verwerking 'n aanvanklike resultaat met POST stuur. Dit moet 'n ontvanger wees waaroor jy beheer het, en mag nie 'n URL van 'n interne diens wees nie. |
Vir 'n JSON-skikking moet jy 'n werklike skikking in to gebruik; moenie 'n JSON-skikking as 'n string in 'n vormveld plaas nie. Gebruik versending aan 'n enkele ontvanger as die aanvanklike integrasietoets. Ondersteuning vir groepe en MMS verskil volgens roete; bevestig dus die ondersteunde kombinasie voordat jy dit gebruik.
Lees die volledige resultaat
Slegs uitgesoekte velde ter illustrasie; die getoonde koste is nie 'n kwotasie nie.
{
"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"
}
}Kontroleer die HTTP-status, JSON se status.code en die antwoord se status/message saam. Resultaatkodes kan stringe wees. Bewaar sms_log_id_ori en die teruggestuurde boodskap-/verwysingswaardes sodat ondersteuning dit kan korreleer. Die ouer uniqueid- en pid-waardes verskil volgens roete; moenie hul formaat aflei of aanvaar dat hulle kliëntidempotensietokens is nie.
Success of Message queued dui gewoonlik op aanvaarding deur die gekose roete, nie op ontvangs deur 'n persoon se selfoon nie. 'n Aanvanklike terugroepstatus soos sent bevestig nie op sigself finale aflewering nie.
Segmente en heffings
Gebruik SMS-lengteontleding op die volledige finale teks voordat jy dit stuur. SMS-pryse hang van die bestemming en rekeningdiens af; toepaslike diensverskafferfooie word per segment bygevoeg. Die versendingspad tel ontvangerpryse en toepaslike fooie bymekaar en vermenigvuldig dit dan met die berekende aantal SMS-segmente. Vir hierdie berekening word 'n MMS-versoek as een boodskap behandel.
cost en permsg is geformateerde geldbedragstringe in die ouer antwoordformaat. carrier_fee_usd rapporteer die diensverskafferfooikomponent in USD en is reeds by die berekende versendingstotaal ingesluit; moenie dit 'n tweede keer bytel nie. Die werklike rekeningpryse en roetebeskikbaarheid moet vir jou rekening nagegaan word. Die versoek is nie 'n bewerking wat slegs 'n prys opvra nie.
Die nagegane kode debiteer ná die suksesvolle versendingspad deur die diensverskaffer, maar aanvaarding deur die diensverskaffer, plaaslike databewaring en fakturering vorm nie een transaksie nie. 'n Fout of uittelling kan voorkom nadat 'n stroomopversoek aanvaar is. Geen idempotensiesleutel word aan die kliënt beskikbaar gestel nie: die herhaling van dieselfde verwysing kan weer 'n boodskap stuur en 'n heffing veroorsaak.
Plaaslike aflewering en gemengde resultate
Nommers wat plaaslik gehuisves word, kan met accepted in MultiTEL se inkomende boodskapvloei aanvaar word sonder versending deur 'n eksterne diensverskaffer. Vir 'n versoek wat geheel en al plaaslik is, kan die antwoord accepted, message_id, provider en delivery_status insluit. Plaaslike aanvaarding waarborg nie dat die ontvanger se opgestelde aanstuurbestemming gewerk het nie.
Ondersoek local_delivery_results en partial wanneer dit teenwoordig is. 'n Ontvanger kan accepted true toon terwyl die aanstuurresultaat onsuksesvol is. 'n Gemengde versoek kan diensverskafferontvangers met accepted en 'n mislukte plaaslike gedeelte hê. Moenie die hele bondel outomaties weer probeer stuur nie: rekonsilieer eers elke ontvanger.
Aanvaarding wat geheel en al plaaslik is, rapporteer nul uitgaande koste in hierdie pad, terwyl ontvangers steeds hul normale heffings vir inkomende boodskappe kan aangaan. Moenie nul uitgaande koste vertolk as 'n waarborg dat geen rekening gedebiteer word nie.
Terugroepe en korrelasie
Wanneer notifyurl verskaf word, het die aanvanklike terugroep 'n status-omhulsel en antwoordvelde wat message_id, reference, from, to, status, status_text, error_code, timestamp en accepted insluit. Plaaslike resultate kan ook teenwoordig wees. Bewaar korrelasie-inligting sonder om API-aanmeldbesonderhede of onnodige boodskapinhoud in logboeke aan te teken.
Hierdie hanteerder voeg nie 'n ondertekeningsveld by daardie aanvanklike terugroep nie. Moenie 'n ongeverifieerde terugroep as selfstandige magtiging vir 'n ander handeling gebruik nie. Raadpleeg die ondersteunde integrasie-/webhaakopstelling vir jou rekening en rekonsilieer onsekere resultate met portaalrekords of met hulp van ondersteuning. Moenie aanvaar dat terugroepe slegs een keer of in die volgorde van finale aflewering aankom nie.
Mislukkings en veilige herstel
Valideringsmislukkings kan API-kode 403 gebruik. Weierings weens rekeninggoedkeuring, P2P en landsbeleid kan ook HTTP 403 stel en 'n masjienleesbare response.code insluit. Tempobeperkings kan 429 gebruik met inligting oor wanneer om weer te probeer. 'n Onbeskikbare beleid of 'n mislukking met versending/plaaslike databewaring kan 503 of 500 gebruik; die ouer hantering van 'n onvoldoende saldo kan ook 500 terugstuur.
By 429 moet jy Retry-After en enige response.retry_after-waarde nakom. By verwerping van 'n rekening, sender, land of ontvanger moet jy die oorsaak regstel voordat jy weer probeer. By 'n uittelling of onduidelike versendingsresultaat moet jy die versoektyd, verwysing en teruggestuurde identifiseerders bewaar, die portaal nagaan en ondersteuning kontak voordat jy weer stuur. Die afwesigheid van 'n loginskrywing alleen is nie bewys dat geen diensverskaffer die versoek aanvaar het nie.