Перед отправкой
Отправляйте SMS или поддерживаемые MMS с номера отправителя, настроенного для вашей учётной записи. Это операция в рабочей среде, которая может привести к отправке сообщений получателям и списанию средств. Отправляйте сообщения только получателям, которым вы вправе их отправлять, и только в рамках одобренного трафика; приведённые ниже номера и метка для сопоставления вымышлены.
Для вашей учётной записи необходимо одобрение исходящих сообщений и соответствующие разрешения для отправителя, страны и типа трафика. Непосредственное использование учётных данных пользователей категории Personal/Consumer для этого 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 или текст с процентным кодированием. На некоторых операторских маршрутах строки, содержащие буквальные escape-последовательности, нормализуются. |
| 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. При отказе, связанном с учётной записью, отправителем, страной или получателем, устраните причину перед повторной попыткой. При истечении времени ожидания или неясном результате отправки сохраните время запроса, метку для сопоставления и возвращённые идентификаторы, проверьте портал и обратитесь в поддержку перед повторной отправкой. Само по себе отсутствие записи в журнале не доказывает, что ни один оператор не принял запрос.