Назад
Регистрация Войти
Войти через VK Войти через FB Войти через Google Войти через Яндекс




Поиск по сайту




Наш Telegram бот: @htmlweb_bot

API Отправки СМС сообщений (SMS API)

Форма отправки СМС сообщения с сайта здесь.

Приложение SMS-шлюз на телефон для получения и отправки СМС здесь.

SMS отправить

Простой способ отправить СМС сообщение с помощью GET-запроса:

http://htmlweb.ru/sendsms/api.php?send_sms
    &sms_text=ТЕКСТ_СООБЩЕНИЯ
    &sms_to=ТЕЛЕФОН
    &api_key=API_KEY_из_профиля

В ответ Вы получите структуру формата html или xml или json содержащую следующие поля:
Если ошибка, то:
error=текст ошибки

Если успешно, то для каждого отправленного сообщения возвращается объект содержащий следующие поля:
'phone'=>номер телефона,'sms_id'=>ID сообщения для проверки его доставки,'cost'=>стоимость отправки в рублях

Если информация запрашивается в формате html, то возвращается общая информация о пакете отправленных SMS, содержащая общую стоимость отправленного сообщения, список номеров и текст сообщения

Например:

http://htmlweb.ru/sendsms/api.php?send_sms&sms_text=test&sms_to=79123456789&api_key=XXXYYYZZZ

Параметры можно передавать как GET так и POST запросом. Можно комбинировать, часть параметров через GET, часть через POST. Рекомендуем использовать POST, т.к. он не сохраняется в кеше браузера и в логах прокси-серверов.

sms_to - Можно указать номер телефона получателя или USSD запрос в формате *ТТТТТ#.
Чтобы отключить проверку корректности номера, длины сообщения и период повтора добавьте перед номером телефона символ тильды ~
sms_text - Текст сообщения в кодировке UTF-8 длиной от 1 до 606 символов

Вы можете использовать дополнительные необязательные параметры:

translit=1 - преобразовать текст СМС в латиницу для уменьшения стоимости
priority=1 - приоритетная отправка СМС. Если у Вас смс, требующая подтверждения со стороны пользователя и скорость её доставки наиболее важный критерий - установите этот параметр.
sms_from=ИМЯ_ОТПРАВИТЕЛЯ
html или xml или json - в каком формате получить ответ
charset=utf-8 - кодировка ответа, по умолчанию utf-8, также поддерживаются: windows-1251, koi-8, ISO-8859-1, ISO-8859-15, cp866, cp1251, cp1252, KOI8-R
send_datetime="2012-10-18 18:00:00" GMT время отложенной отправки сообщения, в формате YYYY-MM-DD HH:MM:SS или в UNIXSTAMP Также можно задавать диапазон времени отправки в формате 10:00-22:30. Время в этом формате задается по МСК. Если время начала больше времени конца, то подразумевается что это следующие сутки, например: 16:30-05:22 - до 05:22 сегодня и с 16:30 сегодня до 05:22 завтра.
service=ID_ШЛЮЗА - если вы хотите отправить СМС через конкретный ваш шлюз. ID можно посмотреть на странице ваших шлюзов.
repeat_limit=1440 - время в минутах проверки на повтор СМС. Уменьшайте хоть до 0, если Вы уверены в работе ваших скриптов и хотите очень часто отправлять одинаковые СМС на один и тот же номер.
marker=XXXXXXX - Метка для учета в статистике или для передачи вашего внутреннего id, не более 32х символов. С помощью метки вы можете раздельно учитывать отправленные СМС в разрезе своих проектов и выставлять счета своим клиентам. Так же ее можно использовать как идентификатор заказа, по которому вы отправили уведомление клиенту.

Примеры

http://htmlweb.ru/sendsms/api.php?send_sms&priority=1&service=0&sms_from=&sms_text=test%209&sms_to=79185558077&xml
<message>
    <sms>
        <msg>
            <time>2014-02-09 17:21:33</time>
            <message>test 9</message>
            <type>0</type>
            <service>4</service>
            <from></from>
            <id>123</id>
            <phone>79185558077</phone>
            <cost>0,25</cost>
        </msg>
    </sms>
    <balans>6104,9</balans>
    <cost>0,15</cost>
</message>

SMS рассылка

Для создания SMS рассылки на множество номеров, укажите все номера через запятую, например:

http://htmlweb.ru/sendsms/api.php?send_sms
    &sms_text=Информационная SMS-рассылка
    &sms_to=79185555555,7926555555
    &api_key=API_KEY_из_профиля

Если в сообщении будут повторяться телефоны - повторы будут автоматически удалены. Телефоны для России можно указывать в любом формате и с '+' в начале и с '8' и с '+7'. Разделителями номеров телефонов могут быть как запятые(,), так и точка с запятой(,). Все лишние символы из номера телефона удаляются автоматически, т.е. Вы можете задавать телефон в любом формате, например: +7(918) 333-22-33,8(918)5558899,8-926-55-55555 - все эти номера будут приведены к стандарту

Если Вы хотите в одном запросе объединить множество различных СМС сообщений, сформируйте следующий пакет в формате XML или JSON:

Формат php до преобразования

'api_key'=>'xxxxx', 'send_sms'=>1, 'json'=>1,
'default'=>array('from'=>'','text'=>'Test Def SMS'),
'sms'=>array(
    array('from'=>'','to'=>'79112224433,79185558077','text'=>'Test SMS1'),
    array('from'=>'','to'=>'79112223333','text'=>'Test SMS2','my_id'=>1234),
    array('to'=>'79123333133,79185558077','text'=>'Test SMS3')
    )

формат JSON:

{"api_key":"aaaaaaaaaaaaa", "cost":1, "json":1,
    "default":{"from":"","text":"Test Def SMS"},
    "sms":[ {"from":"From1","to":"79112223333,79185558077","text":"Test SMS1"},
            {"from":"","to":"79112223333","text":"Test SMS2","my_id":1234},
            {"to":"79113333133,79185558077","text":"Test SMS1"}]}

В разделе "default" Вы можете указать значения по умолчанию для этого пакета СМС.

Пример ответа на запрос отправки СМС:

{"sms":[
    {"from":"From1","time":"2014-02-06 19:13:25","message":"Test SMS1","id":123,"phone":"79112224433","cost":0.25},
    {"time":"2014-02-06 19:13:25","message":"Test SMS1","id":123,"phone":"79185558077","cost":0.25},
    {"my_id":1234,"time":"2014-02-06 19:13:25","message":"Test SMS2","id":123,"phone":"79112223333","cost":0.25},
    {"time":"2014-02-06 19:13:25","message":"Test SMS3","id":123,"phone":"79123333133","cost":0.25},
    {"time":"2014-02-06 19:13:25","message":"Test SMS3","id":123,"phone":"79185558077","cost":0.25}
],
"cost":1,
"balans":2115.36,
"oborot":61.04,
"discount":0.05}

Обратите внимание:

  • если Вы указываете в поле to несколько телефонов, они будут развернуты и показаны отдельно.
  • если Вы указываете номер отправителя или текст в любом другом поле кроме phone, message и т.д., то это поле будет использорванно, но фактический получатель для этой записи будет возвращен в поле phone, сообщение в message.
  • если Вы отправляете множество сообщений, и на балансе не хватит средств, то будут отправлены те, на которые хватит денег.
  • скидка по обороту пересчитывается после отправки всего пакета.

Все дополнительные параметры будут возвращены, например Вы можете передать my_id - номер записи в вашей БД. Не используйте те параметры, которые возвращаются: id, phone, error, status, message, cost, balans, discount, oborot - они будут перезаписаны.

Если сообщение отправлено, то в каждую строку будет добавлен параметр id сообщения. Если в одном сообщении Вы укажете несколько телефонов, они разобьются на отдельные записи.

Пример скрипта СМС рассылки по mySQL базе с сохранением информации об отправленных СМС

$mes='Это тестовое SMS сообщение в формате windows-1251';
// чтобы скрипт отработал полностью
set_time_limit(0); // неограниченное время выполнения скрипта
ignore_user_abort(!0); // игнорировать закрытие окна браузера пользователем
// выбираю все валидные номера телефонов из базы пользователей
$query=mysql_query("SELECT * FROM `users` WHERE `tel` LIKE '79%'");
echo "<br>Отправляю ".mysql_num_rows($query)." SMS.";
$tel='';
$full_cost=0; // считаю общую стоимость
while($data = mysql_fetch_assoc($query)){
    if(strlen($data['tel'])==10){
        $tel.=','.$data['tel'];
        if(strlen($tel>200)){ // в пакете не более 200 номеров
            $full_cost+=SendSms(substr($tel,1),$mes);
            $tel='';
        }
    }else{
        echo "<br>\n".$data['tel']." - неверный номер телефона!";
    }
}
if($tel){ // отправляю на оставшиеся номера
    $full_cost+=SendSms(substr($tel,1),$mes);
}
echo "<br>\nСтоимость СМС рассылки=".$full_cost;

/** Отправка СМС
 * @param $tel список номеров получетелей через ","
 * @param $mes сообщение для отправки в формате windows-1251
 */
function SendSms($tel,$mes){
    echo "<br>\n".$tel."\n";
    $full_cost=0;
    $param=array(
        'api_key'=>'xxxxxxxxxxxxxx', // ключ из профиля http://htmlweb.ru/user/
        'to' => $tel,
        'text' => @iconv('windows-1251','utf-8//IGNORE',$mes)
    );
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
    curl_setopt($ch, CURLOPT_TIMEOUT, 600);
    curl_setopt($ch, CURLOPT_URL, 'http://htmlweb.ru/sendsms/api.php?send_sms&json');
    $res = curl_exec($ch);
    $result = json_decode($res,!0);
    $info = curl_getinfo($ch);
    curl_close($ch);
    if(empty($result['sms'])){
        echo "<br>Ошибка отправки:<br>res:"; var_dump($res);
        echo "<br>result:";var_dump($result);
        echo "<br>info:";var_dump($info);
        return 0;
    }else{
        $v=(array)$result['sms'];
        foreach($v as $s){
            // array ( 'id' => 39741, 'phone' => '79281234567', 'cost' => 0.2 )
            echo "<br>\n"; var_export( $s );
            mysql_query("INSERT IGNORE INTO `".db_prefix."sms`
                    ( `id`, `message`, `phone`, `cost`, `status`, `time`)
                    VALUES ( '".addslashes($s['id'])."', '".addslashes($mes)."',".
                    " '".addslashes($s['phone'])."', '".addslashes($s['cost'])."',".
                    " '".addslashes(0)."', '".date('Y-m-d H:i:s')."')");
            $full_cost+=floatval($s['cost']); // считаю общую стоимость
        }
        return $full_cost;
    }
}

SMS стоимость

Структура API запроса для получения стоимости СМС сообщения:

http://htmlweb.ru/sendsms/api.php?cost
    &sms_text=ТЕКСТ_СООБЩЕНИЯ
    &sms_to=ТЕЛЕФОНЫ_ПОЛУЧАТЕЛЕЙ
    &api_key=API_KEY_из_профиля

Вы можете использовать дополнительные параметры:

[translit=1]
[sms_from=ИМЯ_ОТПРАВИТЕЛЯ]
[html|xml|json] - в каком формате получить ответ

SMS статус

Структура API запроса для получения статуса СМС сообщения:

http://htmlweb.ru/sendsms/api.php?sms_id=NNN&api_key=API_KEY_из_профиля
Коды статусов доставки(поле status)

Примеры ответов:

формат html или без параметра формата:

<div class='message'>Статус доставки SMS #16378: <b class="green">доставлено</b><br>
    Сообщение доставлено абоненту.</div>

формат xml:

<message>
    <status>2</status>
    <id>16378</id>
    <message>Статус доставки SMS #16378: <b class="green">доставлено</b><br>
        Сообщение доставлено абоненту.</message>
</message>

формат json:

{"status":2,"id":"16378","message":"Статус доставки SMS #16378: <b class=\"green\">доставлено<\/b><br>\nСообщение доставлено абоненту."}

Возможные ответы при ошибке:

{"error":"Error SMS Api Сообщение шлюза"}
{"error":"Неверный SMS ID!"}

СМС ошибки

$_REQUEST=array(
    'API_KEY'=>'xxxx', 'send_sms'=>1, 'json'=>1,
    'sms'=>array(
        array('sms_from'=>'dima','sms_to'=>'79115558077','text'=>win2utf('Привет'))));

Если такое сообщение уже отправлялось Вы получите следующий ответ:

{"sms":[{"sms_from":"dima",
              "sms_to":"79115558077",
              "text":"Проверка‚",
              "error":"Такое сообщение уже отправлялось 22.02.22 в 12:30 на 79115558077!",
              "id":60,
              "service":1,
              "cost":0.75}],
    "cost":0,"balans":14078.02}

В котором будет id ранее отправленного СМС, его стоимость и сообщение об ошибке

СМС получить

Для получения списка отправленных или полученных СМС используйте следующий запрос:

http://htmlweb.ru/sendsms/api.php?list&json&api_key=API_KEY_из_профиля

Например, для получения до 200 входящих СМС, полученных от номера 900 начиная с 14.03.2022г используйте следующий запрос:

http://htmlweb.ru/sendsms/api.php?list&json&perpage=200&from=900&d_from=14.03.2022&api_key=API_KEY_из_профиля

"Фишка" для перехода с других сервисов SMS рассылок

Для удобства перехода с других сервисов мы поддерживаем все "чужие" параметры запроса:
Формат ответа можно указывать как просто параметром &json, так и &format=json
Номер телефона можно указывать как с помощью параметра &sms_to=NNN , так и &phone=NNN или &destination=NNN или &to=NNN
Отправителя можно указывать как с помощью параметра &sms_from=XXX , так и &sender=XXX или &source=XXX или &from=XXX
Текст сообщения можно указывать как с помощью параметра &sms_text=XXX , так и &text=XXX или &message=XXX

СМС CallBack

После доставки сообщения или при получении входящего СМС, входящего звонка или при получении ответа на HLR-запрос вызывается Url-адрес, указанный в профиле. Обработчик должен завершить свою работу за 10 секунд и вернуть http-код 200.

Возвращаемые поля для отправляемого сообщения:
'type'=>'send' | 'receive' | 'receive call',
'id'=>ID сообщения,
'status'=>STATUS

СМС Статус

Статусы состояния СМС-сообщений:
STATUS_NEW = 0 - создано и передано на СМС шлюз, статус будет изменен
STATUS_SEND = 1 - отправлено адресату, статус будет изменен
STATUS_DELIVERED = 2 - доставлено, статус окончательный
STATUS_DELIVERY_FAILED = 3 - не доставлено, статус окончательный
STATUS_RESEND = 4 - Отправлено повторно
STATUS_SENDED = 5 - Отправлено шлюзом на телефон (только для персональных СМС-шлюзов)
STATUS_FAILED = 6 - отправлено на шлюз, но шлюз не может отправить или ответ не получен, если доступен другой шлюз, будет переотправлять на другой шлюз

СМС Статистика

Для получения статистики в формате json по СМС шлюзам используйте следующий API вызов: https://htmlweb.ru/sendsms/api.php?d_from=01.05.2022&d_to=31.05.2022&json&stat

Для получения статистики по меткам используйте следующий API вызов: https://htmlweb.ru/sendsms/api.php?d_from=01.05.2022&d_to=31.05.2022&marker&json&stat


.