Перед надсиланням
Надішліть SMS або підтримуване MMS з номера відправника, налаштованого для вашого облікового запису. Це операція в робочому середовищі, яка може доставити повідомлення одержувачам і спричинити нарахування. Надсилайте повідомлення лише одержувачам, яким ви маєте право їх надсилати, і лише схвалений трафік; наведені нижче номери та мітка для зіставлення є вигаданими.
Для вашого облікового запису потрібні схвалення вихідних повідомлень і відповідні дозволи для відправника, країни та трафіку. Безпосередні облікові дані користувачів категорії «Особистий/Споживчий» не дають права користуватися цим API. Для схвалених спеціальних облікових даних API діє окрема процедура допуску; для мобільних відправників P2P можуть знадобитися додаткові дозволи P2P та дозволи для США й Канади. Підтвердьте правильність налаштування облікового запису в MultiTEL, а не вважайте облікові дані API автоматичним дозволом надсилати будь-який трафік.
Запит на надсилання
Автентифікуйтеся через HTTPS за допомогою активованого облікового запису API з дозволеної для нього вихідної IP-адреси. Зберігайте облікові дані в серверному сховищі секретів. Використовуйте POST з полями, закодованими у форматі форми, або об’єкт JSON, якщо поля форми чи параметри рядка запиту не передаються. Не розміщуйте облікові дані або текст повідомлення в 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, status.code у JSON і 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. У разі відмови через обліковий запис, відправника, країну чи одержувача усуньте причину перед повторною спробою. У разі перевищення часу очікування або незрозумілого результату надсилання збережіть час запиту, мітку для зіставлення та повернуті ідентифікатори, перевірте портал і зверніться до служби підтримки перед повторним надсиланням. Сама лише відсутність запису в журналі не доводить, що жоден оператор не прийняв запит.