Меню
Здесь находится html-версия inline-документации php-модуля smsimple.class.php
. Библиотека с модулем и примерами использования находится по ссылке выше. Вся приведённая здесь документация имеется в модуле в виде комментариев к методам классов.
Класс исключений. Ошибки происходящие из класса SMSimple выбрасываются в виде этого исключения.
SMSimple() - основной класс для работы с API.
Работа с библиотекой протекает по следующей стандартной схеме:
Таким образом, минимальный блок работы с API выглядит примерно так:
require_once('./smsimple.class.php');
$sms = new SMSimple(array(
'url' => 'http://api.smsimple.ru/',
'username' => 'my_username',
'password' => 'my_password',
));
try {
$sms->connect();
$sms->call_method_1();
$sms->call_method_2();
$sms->call_method_3();
}
catch (SMSimpleException $e) {
echo $e->getMessage();
}
Конструктор класса. Не вызывается напрямую. Вызывается интерпретатором PHP в момент создания класса sms = SMSimple()
.
$params
Массив параметров, обязательные: username
, password
, url
; опциональные: encoding
, new_xmlrpc
.
$params['username']
данные, указанные при регистрации (для входа в ЛК)
$params['password']
данные, указанные при регистрации (для входа в ЛК)
$params['url']
обычно должен быть http://api.smsimple.ru, но может меняться на url beta-api в случае, если Вы будете тестировать новые версии апи
$params['encoding']
важный параметр, если страницы и скрипты Вашего сайта используют кодировку, отличную от utf-8
, например, windows-1251
.
$params['new_xmlrpc']
force-флаг, заставляющий при необходимости насильно использовать встроенный модуль php5-xmlrpc
, а не написанную на PHP библиотеку ./lib/xmlrpc.inc
; может быть true
, false
, 'auto'
.
Возвращает экземпляр класса SMSimple
, с которым производить дальнейшие манипуляции (апи-вызовы).
Соединение с шлюзом SMSimple.ru.
Не имеет аргументов, использует username
и password
, заданные при создании класса SMSimple
.
Возвращает true в случае удачи, в случае неудачи выбрасывает SMSimpleException
.
Отправка одиночного сообщения
$origin_id
$phone
телефонный номер абонента (любой формат с кодом-телефоном, например '8-916-1234567'
или '79161234567'
) или несколько через запятую (пробелы разрешены, например '79031234567, 89161234567'
)
$message
текст SMS-сообщения
$multiple
необязательный параметр, по-умолчанию false
. Если вы отправляете сообщение сразу нескольким адресатам, то им присвоистся один и тот же (false
) или разные (true
) номера.
Возвращает номер (id
) сообщения, по которому потом можно получать статус доставки/недоставки. Для $multiple = false
вернёт одно число, для $multiple = true
-- массив номеров в той последовательности, в которой шли телефоны абонентов.
Проверка статуса доставки сообщения, отправленного с помощью метода send
.
$message_id
номер SMS-сообщения, возвращённый методом send
Возвращает массив вида:
array(
'sms_id' => 12341234, // то, что было передано в параметре $message_id
'sms_count' => 3, // количество SMS-сообщений, соответствующих этому id,
// равное <кол-во_абонентов>*<кол-во_частей_сообщения>.
// Если сообщение состояло из одной части, и был один абонент,
// тут будет 1 (единица).
'sms_delivered' => 2, // количество SMS-сообщений, которые были доставлены
'sms_failed' => 0, // количество SMS-сообщений, которые не были доставлены
// (то есть являются уже окончательно недоставленными по
// тем или иным причинам), в данном случае таких нет
'sms_delayed' => 1, // количество SMS-сообщений, статус доставки которых ещё
// неизвестен (доставка в процессе). Для получения статуса
// следует проверить позже. Сообщения могу быть без статуса
// до двух суток, в зависимости от оператора.
)
Проверка статусов доставки сообщений, отправленного с помощью метода send
. Аналогична функции
check_delivery
с той лишь разницей, что работает с массивом идентификаторов message_id.
$message_ids
номера SMS-сообщения, возвращённые методом send
Возвращает массив массивов вида:
array(
'3333' =>
array(
'sms_id' => 12341234, // то, что было передано в параметре $message_id
'sms_count' => 3, // количество SMS-сообщений, соответствующих этому id,
// равное <кол-во_абонентов>*<кол-во_частей_сообщения>.
// Если сообщение состояло из одной части, и был один абонент,
// тут будет 1 (единица).
'sms_delivered' => 2, // количество SMS-сообщений, которые были доставлены
'sms_failed' => 0, // количество SMS-сообщений, которые не были доставлены
// (то есть являются уже окончательно недоставленными по
// тем или иным причинам), в данном случае таких нет
'sms_delayed' => 1, // количество SMS-сообщений, статус доставки которых ещё
// неизвестен (доставка в процессе). Для получения статуса
// следует проверить позже. Сообщения могу быть без статуса
// до двух суток, в зависимости от оператора.
),
...
)
Если какой-то message_id
из массива переданных не обнаружен (например, ошибочный), то все значения
элементов соотв. массива второго уровня будут равны 0, включая 'sms_count'
и 'sms_id'
.
Создание новой запланированной рассылки
$params
Массив параметров, обязательные: groups
, template
; опциональные: title
, origin_id
, start_date
, start_time
, stop_time
.
$params['groups']
массив с номерами групп, по которым произвести рассылку, например array(123,365,436,2134)
$params['template']
текст SMS-сообщения (называется template, т.к. это шаблон, и в нём могут быть использованы параметры подстановки %title%
, %custom_1%
, %custom_2%
из групп контактов)
$params['title']
называние рассылки (для Вас), это название будет фигурировать только в списке рассылок в ЛК, если его на задать, оно будет создано автоматически
$params['origin_id']
номер подписи (номера можно узнать в личном кабинете на странице "Подписи"); если этот параметр отсутствует, будет взята подпись, заданная как "Основная" в ЛК
$params['start_date']
дата старта рассылки - дата в формате YYYY-MM-DD задаёт день, в который рассылка будет отправлена (если значение start_date
не задано, то оно будет принятj равным текущему дню)
$params['start_time']
время старта рассылки - уточняет время старта в формате HH:MM или HH:MM:SS (если не задано, то будет равно 00:00:00
)
$params['stop_time']
время остановки рассылки - уточняет время остановки в формате HH:MM или HH:MM:SS (если не задано, то будет равно 23:59:59
).
Это время будет использовано только в случае, когда рассылка не успела завершиться. Можно рассматривать его как "аварийное" время завершения.
Это может быть важно по ряду причин, в частности, информация рассылки может потерять актуальность, или время рассылки слишком позднее (ночь).
Возвращает номер (id) новой рассылки.
Создание новой запланированной рассылки, отправляющей по списку телефонов каждому свой собственный текст. Эта фукнция эквивалентна следующим действиям, производимым вручную в ЛК:
$params
Массив параметров, обязательные: messages
; опциональные: title
, origin_id
, start_date
, start_time
, stop_time
, delete_groups
.
$params['messages']
индексированный массив (список) с элементами вида array('phone' => '79991234567', 'text' => 'Текст, который будет отправлен на номер 79991234567')
$params['title']
называние рассылки (для Вас), это название будет фигурировать только в списке рассылок в ЛК, если его на задать, оно будет создано автоматически
$params['origin_id']
номер подписи (номера можно узнать в личном кабинете на странице "Подписи"); если этот параметр отсутствует, будет взята подпись, заданная как "Основная" в ЛК
$params['start_date']
дата старта рассылки - дата в формате YYYY-MM-DD задаёт день, в который рассылка будет отправлена (если значение start_date
не задано, то оно будет принять равным текущему дню)
$params['start_time']
время старта рассылки - уточняет время старта в формате HH:MM или HH:MM:SS (если не задано, то будет равно 00:00:00
)
$params['stop_time']
время остановки рассылки - уточняет время остановки в формате HH:MM или HH:MM:SS (если не задано, то будет равно 23:59:59
).
Это время будет использовано только в случае, когда рассылка не успела завершиться. Можно рассматривать его как "аварийное" время завершения.
Это может быть важно по ряду причин, в частности, информация рассылки может потерять актуальность, или время рассылки слишком позднее (ночь).
$params['delete_groups']
если передать 1, то группа, которая была автоматически создана под эту рассылку, будет удалена сразу по окончании рассылки,
Возвращает номер (id) новой рассылки.
Получение списка подписей: все подписи текущего аккаунта
Нет параметров.
Возвращает список подписей, доступных для использования в качестве поля "отправитель" (origin_id
), массив массивов вида
array(
array(
'id' => 12345, // номер подписи (id) для использования при отправке send()
// или создании рассылки addJob
'title' => 'my_origin', // собственно подпись
'create_date' => '2013-01-22', // дата создания подписи
'is_default' => 1, // эта подпис является подписью по-умолчанию, которая будет
// использована в случае, если подпись не задана ("Основная",
// этот параметр = 1 только у одной подписи, у остальных 0)
),
...
)
Добавление нового контакта в существующую группу
$params
Массив параметров, обязательные: group_id
, phone
; опциональные: title
, custom_1
, custom_2
.
$params['group_id']
номер группы, в которую добавляем контакт
$params['phone']
телефонный номер абонента (контакта)
$params['title']
"Имя" контакта (%title%
в шаблоне)
$params['custom_1']
"Доп.поле 1" контакта (%custom_1%
в шаблоне)
$params['cusomt_2']
"Доп.поле 2" контакта (%custom_2%
в шаблоне)
$params = array(
'group_id' => 1,
'phone' => '7-926-111-22-33',
'title' => 'Василий Пупкин',
'custom_1' => '',
'custom_2' => '',
);
Возвращает номер (id) новой рассылки.
Поиск контакта по телефону. Поиск может осуществляются по всем группам или по избранным (одной или нескольким).
$params
Массив параметров, обязательные: phone
; опциональные: group_id
.
$params['phone']
телефонный номер абонента (контакта), который требуется найти
$params['group_id']
номер группы (int
) или номера групп (array()
из int
), в которой/которых требуется найти контакт (т.е. ограничение поиска на эти группы)
$params = array(
'phone' => '7-926-111-22-33',
'group_id' => array(1,2,3,4), // может также быть = 1 или = null или вообще отсутствовать
);
список найденных контактов, массив массивов вида
array(
array(
'id' => 12345, // номер контакта
'phone' => '...' // |
'title' => '...' // | параметры контакта
'custom_1' => '...' // |
'custom_2' => '...' // |
'group_id' => 222, // номер группы
'group_title' => 'Группа 1', //название группы
),
...
)
Удаление контакта из группы
$params
Массив параметров, два варианта вызова:
1. с обязательным полем contact_id
;
2. с обязательным phone
и необязательным group_id
.
$params['contact_id']
заранее известный номер контакта (или массив номеров), который надо удалить.
Если этот параметр задан, остальные параметры - phone
, group_id
- игнорируются, происходит удаление конкретных контактов по их id
.
Если этот параметр не задан, то происходит поиск (с помощью метода searchContact
) по параметрам phone
, group_id
, затем контактов по найденным номерам (id
)
$params['phone']
телефонный номер абонента (контакта), который требуется найти и удалить
$params['group_id']
номер группы (int
) или номера групп (array()
из int
), в которой/которых требуется найти и удалить контакт (т.е. ограничение поиска и удаления только на этих группы)
Возвращает количество удалённых контактов.
Удаление контактов из заблокированных (участвующих в незавершённых запланированных рассылках) групп невозможно, контакты из таких групп будут молча пропущены.
Удаление группы
$params
Массив параметров, обязательные: group_id
.
$params['group_id']
номер группы (int
) для удаления
$params = array(
'id' => 1234, // номер группы
);
Возвращает true
, если группа обнаружена и удалена. В остальных случаях вызывает исключения: если группы заблрокирована (участвует в незавершённых запланированных рассылках) или вообще не найдена по номеру.
Добавление (создание) группы
$params
Массив параметров, обязательные: title
; опциональные: description
, is_blacklist
.
$params['title']
название группы, заголовок, который будет виден в списке групп
$params['description']
более подробное описание (для комментариев); значение по-умолчанию ''
$params['is_blacklist']
будет ли эта группа использоваться как "чёрный список"; значение по-умолчанию false
$params = array(
'title' => 'Название новой группы',
'is_blacklist' => false, // это будет группа для "чёрного списка"?
'description' => 'Поясняющее описание к группе',
);
Возвращает номер вновь созданной группы.
Объём группы (количество контактов в группе)
$params
Массив параметров, обязательные: id
.
$params['id']
номер группы
$params = array(
'id' => 1234, // номер группы
);
Возвращает количество контактов в группе.
Получение контактов из группы, возможно постранично
$params
Массив параметров, обязательные: id
; опциональные: offset
, limit
;
$params['id']
номер группы
$params['offset']
начинать с этого контакта (по аналогии с SQL-командой OFFSET
); по-умолчанию 0
$params['limit']
ограничить объём выдачи (по аналогии с SQL-командой LIMIT
); по-умолчанию 0
, что означает "не ограничивать"
$params = array(
'id' => 1234, // номер группы
'offset' => 100, // - для постраничного получения
'limit' => 20, // - для постраничного получения
);
Возвращает контакты из группы в виде массива массивов
array(
array(
'id' => 1,
'title' => 'Вася',
'phone' => '79031234567',
'custom_1' => '',
'custom_2' => '',
),
...
)
Получение информации о профиле
Не принимает параметров.
Возвращает доступные данные по Вашему аккаунту в виде массива, например
array(
'id' => 52579,
'username' => 'test',
'title' => 'Василий Васильевич Пупкин',
'ussd_enabled' => 1,
'ussd_balance' => -673,
'ussd_leverate' => 0,
'phone' => '03',
'email' => 'vasya@pupkin.ru',
'billing_type' => 'Предоплата',
'balance' => 966.911,
'leverate' => 0.0,
)
Старт USSD сессии, инициирует начало обмена USSD-сообщениями. Эта функция ещё ничего не посылает на телефон абонента, первая отправка USSD-меню осуществляется Вашим скриптом обратного вызова согласно идентификатору Вашего приложения.
$phone
номер абонента, которому отправляется USSD
$optional
любые данные для дополнительной идентификации, сопровождают сессию до закрытия, обычно ваш внутренний идентификатор сессии
$encoding
'GSM-7'
для меню на латинице (~120 символов) или 'UCS2'
для меню с русскими буквами (~60 символов)
$app_id
идентификатор USSD-приложения согласно вашему ЛК (см. "USSD-приложения" в меню, пункт доступен, если у Вас открыт доуступ к USSD).
Идентификатор можно не задавать, если у Вас одно USSD-приложение (оно и вызовется), если у Вас несколько USSD-приложений и app_id
не указан, будет возвращена ошибка
$this->ussd_session_start(
'79991234567', // phone.
'AF13BC57234', // optional. например, это id сессии, для идентификации диалога на стороне Вашего приложения
'GSM-7', // encoding. при этом значении Ваши скрипты обратного вызова должны отдавать меню в латинице
'my_ussd_app' // app_id. идентификатор USSD-приложения, задаётся Вами самостоятельно в ЛК
);
Если старт сессии прошёл удачно, возвращает номер (id
) сессии (по нумерации SMSimple), иначе false
(например, неверный телефон или не установлено/не отвечает корректно скрипт обратного вызова).
Прерывание USSD сессии. Оставлена для обратной совместимости, ничего реально не делает.
В качестве параметра $ussd_session_id
сюда надо было передавать id
сессии, полученный вызовом ussd_session_start
.
Получение полной статистики SMS-сообщений за указанный период.
$year_begin
год начала периода;
$month_begin
месяц начала периода;
$day_begin
день начала периода;
$year_end
год конца периода;
$month_end
месяц конца периода;
$day_end
день конца периода;
$count
если нужно только количество, передаётся значение true
;
$limit
максимальная длина выборки (по аналогии с SQL-командой LIMIT
); по-умолчанию 0
, что означает "не ограничивать";
$offset
начальный отступ выборки (по аналогии с SQL-командой OFFSET
); по-умолчанию 0
;
$stat = sms->sms_statistic(2014,7,31,2014,7,31);
Возвращает отправленные смс за выбранный период в виде массива массивов
array(
array(
"origin" => "MyOrigin",
"status" => "REJECTD",
"done_date" => "31.07.2014 14:40",
"price" => 1.6,
"app_id" => 0,
"phone" => "79991234567",
"operator" => "BEELINE",
"message" => "Today is 31.07.2014. This is a test message.",
"optional" => "",
"id" => 46370130,
"is_charged" => 0,
"submit_date" => "31.07.2014 14:34",
"error_code" => 11
),
...
)
или число, равное длине этого массива, при передаче параметра $count = true
.
Запрос баланса.
Без параметров.
Возвращает только баланс, по конечному результату эквивалентно вызову get_profile()['balance']
, но выгоднее, если Вам нужен только Ваш SMS-баланс, т.к. не передаёт ничего лишнего.
Заказ на создание новой подписи. Запрос на создание новой подписи проходит обязательную премодерацию менеджером и может быть одобрен или отклонён.
$new_origin
какую подпись Вы желаете заказать, например 'vasyapupkin'
Возвратит номер заказа. Его можно использовать для проверки статуса заказа с помощью originOrderStatus
.
Проверка статуса заказа на создание новой подписи.
Возвращает:
0
при отказеnull
при ожидании (возможен возврат пустой строки ''
)id
новой подписи, если заказ одобрен и подпись создана$message
Текст смс
Возвращённое число равно количеству отдельных SMS, которые необходимы для передачи всего текста на мобильный телефон абонента.
$message
Текст смс
Возвращённое число равно количеству символов, которые будут задействованы при передаче SMS-сообщения. Логика работы примерно такая: если в тексте встречается хотя бы один символ не-латиницы, то все символы SMS буду занимать по 2 символа в конечном PDU, если только латиница - то по одному символу PDU на каждый символ исходного текста.
Под латиницей понимаются также цифры и знаки препинания.
Функция совершает подсчёт символов в сообщении (аналогично getSymbolsCount
), затем по ним считает количество частей (PDU), на которое, возможно, придётся разбить сообщение для отправки,
затем выбирает наилучшую цену из Ваших пакетов и умножает цену одного PDU на их количество и на количество контактов, указанных в $phone
.
$origin_id
id
подписи, 0
для случайно-цифровой
$phone
номер абонента, можно использовать несколько номеров через запятую, например, '89031234567, 79161234567, 89261324354'
$message
Текст сообщения
Возвращает массив вида
array(
'cost' => 1.88, // суммарная стоимость всех SMS, с учётом количества абонентов
// и количества частей сообщений
'sms_count' => 2, // количество всех SMS = количество абонентов * количество частей сообщения
'sms_out_of_balance' => 0 // если баланса достаточно для отправки всех этих сообщений, то
// тут будет 0; в противном случае тут будет количество SMS,
// на которых не хватат баланса; например, если баланс=0, то тут
// будет такое же число, как и в 'sms_count', что значит, что ни
// одно сообщение не может быть отправлено.
)
Цена SMS зависит от подписи.