Преди изпращане
Изпратете SMS или поддържан MMS чрез номер за изпращане, конфигуриран за вашия акаунт. Това е операция в реална среда, която може да достигне до получателите и да доведе до начисляване на суми. Изпращайте само до получатели, за които имате разрешение, и само одобрен трафик; примерните номера и референцията по-долу са измислени.
Вашият акаунт трябва да има одобрение за изходящи съобщения и съответните разрешения за подател, държава и трафик. Потребителските идентификационни данни за директен личен/потребителски достъп не отговарят на условията за използване на този API. За одобрените специализирани идентификационни данни за API има отделна процедура за допускане; за мобилните P2P податели може да са необходими допълнителни разрешения за P2P и за САЩ/Канада. Потвърдете правилната настройка на акаунта с MultiTEL, вместо да приемате, че идентификационните данни за API автоматично дават разрешение за изпращане на всякакъв трафик.
Заявка за изпращане
Удостоверете се през HTTPS с активиран API акаунт от разрешения за него изходен IP адрес. Съхранявайте идентификационните данни в хранилище за тайни на сървъра. Използвайте POST с полета, кодирани като формуляр, или JSON обект, когато не са подадени полета във формуляра или в параметрите на URL заявката. Не поставяйте идентификационни данни или текста на съобщението в 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| Поле | Задължително | Значение |
|---|---|---|
| from | Да | Вашият конфигуриран номер за изпращане, за предпочитане с всички цифри в международен формат. |
| to | Да | Един номер на получател, номера на получатели, разделени със запетаи, или JSON масив. За предпочитане използвайте всички цифри в международен формат. Групова заявка може да бъде отхвърлена поради приложимите за нея ограничения за P2P или държава; това не е API за масово изпращане без ограничения. |
| text | За SMS | Текст на съобщението в UTF-8. Необходимо е поне непразно текстово или мултимедийно съдържание. Изпращайте действителни символи и нови редове, а не HTML или текст с процентно кодиране. Някои маршрути през оператори нормализират екраниращите последователности, подадени като буквален текст. |
| media | За MMS само с мултимедийно съдържание | Мултимедийното съдържание, кодирано с Base64, а не URL адрес или път до файл. Наличността, форматът и размерът на MMS зависят от конфигурирания маршрут. Потвърдете поддържаното мултимедийно съдържание с MultiTEL; този обработчик не определя универсално ограничение за размера му. |
| reference | Препоръчително | Вашият етикет за съпоставяне, който се запазва в записите и обратните извиквания. Включете такъв етикет, за да улесните отстраняването на проблеми. Той не е ключ за идемпотентност. |
| notifyurl | Не | Вашият HTTPS приемник за обратни извиквания. След обработката обработчикът може да изпрати първоначален резултат чрез POST. Приемникът трябва да е под ваш контрол и не трябва да е URL адрес на вътрешна услуга. |
За JSON масив използвайте действителен масив в to; не поставяйте низ, съдържащ JSON масив, в поле на формуляр. Използвайте изпращане до един получател за първоначалния тест на интеграцията. Поддръжката на групово изпращане и MMS се различава според маршрута, затова потвърдете поддържаната комбинация, преди да ги използвате.
Прочетете целия резултат
Показани са само избрани полета за илюстрация; посочената цена не е ценова оферта.
{
"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"
}
}Проверявайте заедно HTTP статуса, JSON полето status.code и полетата status/message в отговора. Кодовете на резултатите могат да бъдат низове. Запазвайте sms_log_id_ori и върнатите стойности за съобщението и референцията, за да може поддръжката да съпоставя записите. Стойностите на наследените полета uniqueid и pid се различават според маршрута; не извеждайте правила за формата им и не приемайте, че са клиентски токени за идемпотентност.
Success или Message queued обикновено означава приемане от избрания маршрут, а не получаване на телефона на човека. Първоначален статус в обратно извикване, например sent, сам по себе си не потвърждава окончателна доставка.
Сегменти и начислени суми
Използвайте Анализ на дължината на SMS върху целия окончателен текст преди изпращане. Цените на SMS зависят от дестинацията и услугата по акаунта; приложимите операторски такси се добавят за всеки сегмент. Логиката за изпращане събира цените за получателите и приложимите такси, след което умножава по изчисления брой SMS сегменти. За това изчисление тя третира заявка за MMS като едно съобщение.
cost и permsg са форматирани низове с парични стойности в наследения отговор. carrier_fee_usd показва компонента на операторската такса в USD, който вече е включен в изчислената обща сума за изпращане; не го добавяйте втори път. Трябва да проверите действителните цени и наличността на маршрутите за вашия акаунт. Заявката не е операция само за справка за цена.
Прегледаният код удържа сума след успешно изпълнение на пътя за изпращане през оператор, но приемането от оператора, локалното записване и таксуването не са една транзакция. Грешка или изтичане на времето за изчакване може да настъпи, след като заявката вече е приета от външната система. Не се предоставя клиентски ключ за идемпотентност: повторното използване на същата референция може да доведе до ново изпращане и ново таксуване.
Локална доставка и смесени резултати
Локално хостваните номера могат да бъдат приети (accepted) в потока за входящи съобщения на MultiTEL без изпращане през външен оператор. При заявка само с локални получатели отговорът може да включва accepted, message_id, provider и delivery_status. Локалното приемане не гарантира, че конфигурираната за получателя дестинация за препращане е сработила.
Проверявайте local_delivery_results и partial, когато присъстват. За получател може да е показано accepted true, докато резултатът от препращането към него е неуспешен. Смесена заявка може да има приети (accepted) получатели през оператор и неуспешна локална част. Не повтаряйте автоматично цялата група: първо съпоставете резултатите за всеки получател.
При приемане само на локални получатели този път отчита нулев разход за изходящи съобщения, но на получателите все пак могат да бъдат начислени обичайните им такси за входящи съобщения. Не тълкувайте нулевия разход за изходящи съобщения като гаранция, че никой акаунт няма да бъде таксуван.
Обратни извиквания и съпоставяне
Когато е подаден notifyurl, първоначалното обратно извикване има обвивка status и полета на отговора, включително message_id, reference, from, to, status, status_text, error_code, timestamp и accepted. Могат да присъстват и локални резултати. Съхранявайте информацията за съпоставяне, без да записвате в журналите идентификационни данни за API или ненужно съдържание на съобщенията.
Този обработчик не добавя поле за подпис към първоначалното обратно извикване. Не използвайте непроверено обратно извикване като самостоятелно основание за разрешаване на друго действие. Направете справка с поддържаната настройка за интеграция или уебхук за вашия акаунт и изяснявайте несигурните резултати чрез записите в портала или поддръжката. Не приемайте, че обратните извиквания пристигат само веднъж или в реда на окончателната доставка.
Грешки и безопасно възстановяване
При неуспешна валидация може да се използва API код 403. Откази, свързани с одобрението на акаунта, P2P или правилата за държавата, също могат да зададат HTTP 403 и да включват машинночетимо поле response.code. При ограничения на честотата на заявките може да се използва 429 с информация за повторен опит. При недостъпна политика или неуспешно изпращане или локално записване може да се използва 503 или 500; наследената обработка на недостатъчна наличност по сметката също може да върне 500.
При 429 спазвайте Retry-After и всяка подадена стойност на response.retry_after. При отказ, свързан с акаунта, подателя, държавата или получателя, отстранете причината, преди да опитате отново. При изтичане на времето за изчакване или неясен резултат от изпращането запазете часа на заявката, референцията и върнатите идентификатори, проверете портала и се свържете с поддръжката, преди да изпратите повторно. Липсата на запис в журнала сама по себе си не доказва, че никой оператор не е приел заявката.