Před odesláním
Odešlete SMS nebo podporovanou MMS pomocí čísla pro odesílání nakonfigurovaného pro váš účet. Jde o operaci v ostrém provozu, která může kontaktovat příjemce a vést k účtování poplatků. Odesílejte pouze oprávněným příjemcům a pouze schválený provoz; níže uvedená ukázková čísla a reference jsou smyšlené.
Váš účet potřebuje schválení odchozích zpráv a příslušná oprávnění pro odesílatele, zemi a provoz. Přímé přihlašovací údaje uživatelů typu Personal/Consumer nejsou pro toto API způsobilé. Schválené vyhrazené přihlašovací údaje pro API mají samostatný postup posuzování způsobilosti; mobilní odesílatelé P2P mohou vyžadovat další oprávnění pro P2P a USA/Kanadu. Správné nastavení účtu si ověřte u MultiTEL; nepovažujte přihlašovací údaje pro API za automatické oprávnění k odesílání libovolného provozu.
Požadavek na odeslání
Ověřte se přes HTTPS pomocí povoleného účtu API z jeho povolené zdrojové IP adresy. Přihlašovací údaje uchovávejte v úložišti tajných údajů na serveru. Použijte POST s poli kódovanými jako formulář, nebo objekt JSON, pokud nejsou zadána žádná formulářová pole ani parametry dotazu. Přihlašovací údaje ani text zprávy nevkládejte do 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| Pole | Povinné | Význam |
|---|---|---|
| from | Ano | Vaše nakonfigurované číslo pro odesílání, nejlépe jako úplné mezinárodní číslo zapsané číslicemi. |
| to | Ano | Jeden cíl, cíle oddělené čárkami nebo pole JSON. Upřednostňujte úplná mezinárodní čísla zapsaná číslicemi. Skupinový požadavek může být odmítnut kvůli příslušným limitům P2P nebo limitům pro danou zemi; nejde o neomezené API pro hromadné odesílání. |
| text | Pro SMS | Text zprávy v UTF-8. Je vyžadován alespoň neprázdný text nebo média. Odesílejte skutečné znaky a zalomení řádků místo HTML nebo textu kódovaného pomocí procentních sekvencí. Některé cesty přes operátory normalizují doslovně zapsané escape sekvence. |
| media | Pro MMS obsahující pouze média | Obsah médií kódovaný v Base64, nikoli URL nebo cesta k souboru. Dostupnost MMS, formát a velikost závisí na nakonfigurované trase. Podporovaná média si ověřte u MultiTEL; tato obslužná rutina nestanovuje žádný univerzální limit velikosti médií. |
| reference | Doporučené | Váš identifikátor pro propojení souvisejících údajů, který se uchovává v záznamech a zpětných voláních. Uvádějte jej pro usnadnění řešení problémů. Nejde o klíč idempotence. |
| notifyurl | Ne | Váš přijímací endpoint pro zpětná volání přes HTTPS. Obslužná rutina na něj může po zpracování odeslat počáteční výsledek metodou POST. Musí jít o přijímač pod vaší kontrolou a nesmí to být URL interní služby. |
Chcete-li použít pole JSON, zadejte do to skutečné pole; nevkládejte řetězec představující pole JSON do formulářového pole. Jako první integrační test použijte odeslání jedinému příjemci. Podpora skupin a MMS se liší podle trasy, proto si před jejich použitím ověřte podporovanou kombinaci.
Přečtěte si celý výsledek
Jde pouze o vybraná pole pro ilustraci; zobrazená cena není cenovou nabídkou.
{
"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"
}
}Vyhodnocujte společně stav HTTP, status.code v JSON a pole status/message v odpovědi. Kódy výsledků mohou být řetězce. Uchovejte sms_log_id_ori a vrácené hodnoty zprávy a reference, aby je podpora mohla propojit se souvisejícími záznamy. Hodnoty starších polí uniqueid a pid se liší podle trasy; neodvozujte jejich formát ani nepředpokládejte, že jde o klientské tokeny idempotence.
Success nebo Message queued obvykle označuje přijetí vybranou trasou, nikoli přijetí zprávy telefonem příjemce. Stav počátečního zpětného volání, například sent, sám o sobě nepotvrzuje konečné doručení.
Segmenty a poplatky
Použijte Analýzu délky SMS na úplný konečný text před odesláním. Ceny SMS závisí na cíli a službě účtu; příslušné poplatky operátorů se připočítávají za každý segment. Postup odesílání sečte ceny pro příjemce a příslušné poplatky a poté součet vynásobí vypočteným počtem segmentů SMS. Pro tento výpočet považuje požadavek MMS za jednu zprávu.
cost a permsg jsou ve starší podobě odpovědi formátované řetězce s peněžními částkami. carrier_fee_usd uvádí složku poplatku operátora v USD, která je již zahrnuta ve vypočtené celkové ceně odeslání; nepřičítejte ji podruhé. Skutečné ceny a dostupnost tras je nutné ověřit pro váš účet. Požadavek neslouží pouze ke zjištění ceny.
Prověřený kód odečítá částku po úspěšném průchodu odesíláním přes operátora, ale přijetí operátorem, místní trvalé uložení a účtování netvoří jednu transakci. K chybě nebo vypršení časového limitu může dojít až poté, co navazující systém požadavek přijal. Klientský klíč idempotence není k dispozici: opakování stejné reference může vést k opětovnému odeslání a naúčtování.
Místní doručení a smíšené výsledky
Místně hostovaná čísla mohou být přijata (accepted) do toku příchozích zpráv MultiTEL bez odeslání přes externího operátora. U požadavku se všemi příjemci v místním systému může odpověď obsahovat accepted, message_id, provider a delivery_status. Místní přijetí nezaručuje, že nakonfigurovaný cíl přeposílání příjemce fungoval.
Zkontrolujte local_delivery_results a partial, pokud jsou přítomny. U příjemce může být uvedeno accepted true, i když přeposlání skončilo neúspěšně. Smíšený požadavek může mít příjemce přijaté operátorem (accepted) a neúspěšnou místní část. Neopakujte automaticky celou dávku: nejprve ověřte a vyhodnoťte výsledek každého příjemce.
Přijetí všech příjemců v místním systému vykazuje v tomto postupu nulovou cenu odchozího provozu, příjemcům však mohou být nadále účtovány běžné poplatky za příchozí zprávy. Nulovou cenu odchozího provozu nepovažujte za záruku, že žádnému účtu nebudou účtovány poplatky.
Zpětná volání a propojení souvisejících údajů
Pokud je zadáno notifyurl, počáteční zpětné volání obsahuje obálku status a pole odpovědi včetně message_id, reference, from, to, status, status_text, error_code, timestamp a accepted. Mohou být přítomny také místní výsledky. Ukládejte informace pro propojení souvisejících údajů, aniž byste do protokolů zapisovali přihlašovací údaje pro API nebo zbytečný obsah zpráv.
Tato obslužná rutina do počátečního zpětného volání nepřidává pole pro podpis. Nepoužívejte neověřené zpětné volání jako samostatné oprávnění k další akci. Ověřte si podporované nastavení integrace nebo webhooku pro svůj účet a nejasné výsledky porovnejte se záznamy na portálu nebo je vyjasněte s podporou. Nepředpokládejte, že zpětná volání přicházejí pouze jednou nebo v pořadí konečného doručení.
Chyby a bezpečný postup nápravy
Chyby validace mohou používat kód API 403. Zamítnutí kvůli schválení účtu, pravidlům P2P nebo pravidlům pro zemi mohou také nastavit HTTP 403 a obsahovat strojově čitelné response.code. Omezení četnosti požadavků mohou používat 429 s informacemi pro opakování. Nedostupná pravidla nebo selhání odesílání či místního trvalého uložení mohou používat 503 nebo 500; nedostatečný zůstatek může ve starším zpracování také vracet 500.
Při 429 respektujte Retry-After i případnou hodnotu response.retry_after. Při zamítnutí účtu, odesílatele, země nebo příjemce nejprve odstraňte příčinu a teprve poté požadavek opakujte. Při vypršení časového limitu nebo nejasném výsledku odeslání uchovejte čas požadavku, referenci a vrácené identifikátory, zkontrolujte portál a před opětovným odesláním kontaktujte podporu. Samotná nepřítomnost záznamu v protokolu nedokazuje, že požadavek nepřijal žádný operátor.