API для отправки SMS сообщений
Добавлено: 20 сен 2010, 14:47Обращение к API происходит по протоколу HTTP(S) (методы POST или GET) по адресу:
В дополнение к адресу необходимо передавать следующие параметры:
Обработка результата запроса
После обработки запроса API вернет согласно запрашиваемому действию те или иные данные. Ниже приведен пример ответа при отправке одиночного SMS сообщения:
При проверке статуса ответ будет таким:
Поле code указывает код выполнения операции:
Поле status при проверке статуса сообщения означает следующее:
Обновлено: 28 Июня 2012
Внимание: Старое API больше не поддерживается, однако будет продолжать работать еще некоторое время. Поэтому прошу не сильно медлить при переходе на новое API.
- Код: Выделить всё
http://api.comtube.ru/scripts/api/sms.php
В дополнение к адресу необходимо передавать следующие параметры:
- action - Действие. Возможны следующие варианты:
- send – отправить SMS,
- terminate – отменить отправку (пока не поддерживается),
- resume – возобновить рассылку, если она была прервана пользователем с помощью terminate или автоматически сервером приложений,
- start – запустить выполнение черновика,
- state – получить статус отправки SMS,
- statistics – получить статистику по отправленным SMS,
- getsmses – получить список SMS (входящих и исходящих),
- mark – пометить входящее сообщение прочитанным или не прочитанным,
- listsenderids – получить список разрешенных номеров отправителей (она же: SenderID?, подпись),
- getlimits – получить лимиты по рассылкам SMS,
- listsenttasks – получить список отправленных рассылок (можно использовать совместно с параметрами fromdttm, untildttm, count),
- listplannedtasks – получить список запланированных рассылок,
- listsenderids - получить список разрешенных SenderIDs.
- listdrafts – получить список черновиков,
- delete – удалить задание на рассылку (удалить можно только выполненные, прекращенные задания или черновики)
- uid - идентификатор сообщения. Используется при проверке статуса, удалении, остановке, запуске, получении статистики
- number - номер телефона получателя. Разрешается указывать несколько номеров, разделенных ";" или ","
- numfile - файл с номерами телефонов или с номерами телефонов и текстом сообщений. Этот параметр не должен участвовать в формировании подписи.
- when - Указывает дату/время начала отправки SMS(-ов). Формат параметра следующий: YYYY-MM-DD HH:MM:SS. Пример: 2012–12–31 12:00:00. Если параметр не указан, то SMS отправляется сразу. Для action = send
- upto - Указывает дату/время завершения отправки SMS(-ов). Формат параметра следующий: YYYY-MM-DD HH:MM:SS. Пример: 2011–11–11 11:11:11. Если параметр не указан, то верхнего лимита времени по отправке SMS не существует. Желательно использовать в тех случаях, когда нужно отправлять очень много SMS. Если до указанного времени SMS отправить не удалось, то он никогда не отправится. Для action = send
- starttime - Время суток, когда разрешается начало отправки SMS. Формат параметра следующий: HH:MM:SS. Использовать тогда, когда указаны when и upto. Для action = send
- stoptime - Время суток, когда отправка SMS заканчивается. Формат параметра следующий: HH:MM:SS. Использовать тогда, когда указаны when и upto. Для action = send
- days - Тип дней недели, когда необходимо выполнять отправку SMS: 0 – все дни (по умолчанию), 1 – рабочие дни, 2 – выходные и праздничные дни. Для action = send
- senderid - Номер телефона (длиной не более 20 цифр) или текст (не более 11 символов), который будет виден принимающей стороне. По умолчанию, 'Comtube.com'. Для action = send
- name - Название задания на отправку SMS. Если параметр не указан, то используется стандартное название “New sms task”. Допустимая длина параметра от 1 до 64 символов. Для action = send.
- message - Текстовое сообщение для отправки. Может быть пустым. В этом случае, текст сообщения будет браться из файла с номерами телефонов. Для action = send. В тексте сообщения разрешается использовать следующие переменные:
- %CT_N% – имя получателя из адресной книги пользователя,
- %CT_F% – фамилия получателя,
- %CT_M% – отчество получателя,
- %CT_FN% – отображаемое имя получателя,
- %CT_COL_N% – номер колонки в текстовом файле, где N – номер от 1 (на данный момент еще не поддерживается).
- who - Для action = getsmses указывает номер телефона, для которого нужно получить статистику
- fromdttm - Для action = getsmses указывает дату и время, после которой необходимо получить список SMS
- untildttm - Для action = getsmses указывает дату и время, до которой необходимо получить список SMS
- incl - Для action = getsmses указывает включать или нет дату и время для параметров fromdttm и untildttm (то есть, использовать “<"/">" или "<="/">=")
- what - Для action = getsmses указывает, какие SMS требуется получить:
- 0 – все (входящие и исходящие),
- 1 – входящие прочитанные,
- 2 – входящие не прочитанные,
- 3 – все входящие,
- 4 – исходящие
- count - Для action = getsmses указывает количество SMS, которые нужно получить
- charset - кодировка, в которой передается параметр message (koi8-r, utf-8). Не обязательный параметр.
- username – логин пользователя. Обязательный параметр.
- type – тип возвращаемого результата: xml (по умолчанию), html, csv, json. Необязательный параметр.
- signature – подпись запроса. Обязательный параметр. Как создать подпись смотрите раздел "Создание подписи (signature)"
- isread - Указывает, пометить ли сообщение как прочитанное: 1 - да, 0 - не прочитанное. Для действия action = mark
- report_to - Адрес электронной почты, куда следует отправлять отчет о выполнении задания.
- group - Название группы контактов адресной книги, которым необходимо отправить SMS сообщения. У контакта адресной книги берется контакт с типом "Мобильный телефон". Если его нет, то сообщение ему не будет отправлено. Если их несколько, то сообщение отправляется на первый указанный мобильный телефон.
- asdraft - Указывает, что вместо отправки сообщения(-ий) следует создать черновик (=1), который можно будет запустить отдельно. Для action = send
Обработка результата запроса
После обработки запроса API вернет согласно запрашиваемому действию те или иные данные. Ниже приведен пример ответа при отправке одиночного SMS сообщения:
- Код: Выделить всё
<?xml version="1.0" encoding="utf-8"?>
<result>
<id>99221559</id>
<uid>2c51сa5e-b7bd-45ad-a119-6dadca63e131</uid>
<count>1</count>
<code>200</code>
<desc>OK</desc>
</result>
При проверке статуса ответ будет таким:
- Код: Выделить всё
<?xml version="1.0" encoding="utf-8"?>
<result>
<numbers>
<item>
<id>99221559</id>
<sent_at>2012-06-28 11:12:00</sent_at>
<number>79261112233</number>
<parts_cnt>1</parts_cnt>
<parts_sent>1</parts_sent>
<status>12</status>
<desc>No error</desc>
</item>
</numbers>
<code>200</code>
<desc>OK</desc>
</result>
Поле code указывает код выполнения операции:
- 200 – OK – Операция прошла успешно. В случаях, когда запрашивается статистика в формате csv, html и операция прошла успешно, код ошибки не возвращается.
- 204 – No Content – возвращается в случаях, когда запрашиваемая информация не найдена. Например, если при запросе статистики по указанному фильтру ничего не найдено, то вернется именно этот код
- 400 – Bad Request – указывает, что один или несколько параметров указаны не верно или отсутствуют. В поле desc, как правило, возвращается название параметра, который указан не правильно
- 401 – Authorization Failed – Неправильно указан логин/пароль или неправильно сформирована подпись signature
- 402 – Not enough money OR Payment required – Указывает, что для совершения операции недостаточно денег. Требуется пополнить счет
- 403 – Account Blocked OR User Blocked – Указывает, что учетная запись пользователя заблокирована по тем или иным причинам
- 500 – Internal Server Error – Возникла внутренняя ошибка.
- 501 – Not Implemented – Указывает, что запрашиваемая функциональность еще не реализована.
- 503 – Service Unavailable – Указывает, что не удалось подключится к серверу приложения для выполнения операции. Однако операция может быть выполнена чуть позже.
Поле status при проверке статуса сообщения означает следующее:
- 10 - Отправлено
- 12 - Доставлено
- 20 - В очереди на отправку
- 0 - Не удалось отправить/доставить
Обновлено: 28 Июня 2012
Внимание: Старое API больше не поддерживается, однако будет продолжать работать еще некоторое время. Поэтому прошу не сильно медлить при переходе на новое API.
