Обращение к API происходит по протоколу HTTP(S) (методы POST или GET) по адресу:
- Код: Выделить всё
http://api.comtube.ru/scripts/api/vmsg.php
В дополнение к адресу необходимо передавать следующие параметры:
- action – Действие.
- send – отправить голосовое сообщение (по умолчанию),
- terminate – отменить отправку (пока не поддерживается),
- state – получить статус отправки сообщения,
- statistics – получить статистику по отправленным голосовых сообщений,
- getvmsgs – получить список сообщений (входящих, исходящих, пользовательских),
- mark – пометить входящее сообщение прочитанным или не прочитанным,
- getvmsg – получить сообщение в виде файла или проиграть его позвонив на указанный номер телефона,
- upload – загрузить на сервер пользовательское сообщение,
- update – изменить параметры пользовательского сообщения или задания на отправку сообщения,
- delete – удалить сообщения (входящие, отправленные, пользовательские),
- record – записать пользовательское сообщение через телефон,
- resume – продолжить выполнение после остановки (пока не поддерживается),
- resend – отправить заново на все номера (пока не поддерживается),
- complete – повторить только те, на которые сообщения не были отправлены (пока не поддерживается)
- uid - Идентификатор входящего/отправляемого/отправленного/пользовательского голосового сообщения. Для action = getvmsgs, getvmsg, statistics, state, update, delete, mark указывает идентификатор задания, для которого нужно получить статистику или другую информацию. В остальных случаях указывает идентификатор голосового сообщения. Как правило, используется вместе с параметром what для уточнения о каком сообщении идет речь.
- number - Номер телефона или список телефонов, разделенных точкой с запятой, куда необходимо отправить голосовое сообщение. Для action = send, state, getvmsgs, getvmsg, record
- numfile - Текстовый файл с номерами телефонов, куда следует отправить голосовые сообщения. Файл должен быть обычным текстовым. Для action = send
- vmsgfile - Файл с записанным голосовым сообщением. Поддерживаются файлы в форматах: WAV и MP3. При загрузке файл автоматически конвертируется в формат "WAV 8КГц, 16 бит, Моно". Для action = send, upload
- when - Указывает дату/время начала отправки голосового(-ых) сообщения(-ий). Формат параметра следующий: YYYY-MM-DD HH:MM:SS. Пример: 2011–11–11 11:11:11. Если параметр не указан, то сообщение(-я) отправляется сразу. Для action = send
- upto - Указывает дату/время завершения отправки голосовых сообщений. Формат параметра следующий: YYYY-MM-DD HH:MM:SS. Пример: 2011–11–11 11:11:11. Если параметр не указан, то верхнего лимита времени по отправке факса не существует. Желательно использовать в тех случаях, когда нужно отправлять много голосовых сообщений. Если до указанного времени факс отправить не удалось, то он никогда не отправится. Для action = send
- starttime - Время суток, когда разрешается начало отправки голосовых сообщений. Формат параметра следующий: HH:MM:SS. Использовать тогда, когда указаны when и upto. Для action = send
- stoptime - Время суток, когда отправка голосовых сообщений заканчивается. Формат параметра следующий: HH:MM:SS. Использовать тогда, когда указаны when и upto. Для action = send
- days - Тип дней недели, когда необходимо выполнять отправку голосовых сообщений: 0 – все дни, 1 – рабочие дни, 2 – выходные и праздничные дни. Для action = send
- attempts - Количество попыток установить соединение с абонентом для проигрывания ему голосового сообщения. Диапазон допустимых значений от 1 до 10, по умолчанию – 2
- busyrecalltime - Время в секундах, через которое необходимо повторить попытку в случае, если абонент был занят. Диапазон допустимых значений от 5 до 86400 секунд, по умолчанию – 300
- noanswrecalltime - Время в секундах, через которое необходимо повторить попытку в случае, если абонент не ответил. Диапазон допустимых значений от 5 до 86400 секунд, по умолчанию – 3600
- asdraft - Указывает, что задание на отправку голосового сообщения нужно создать в виде черновика (то есть, не запускать на выполнение) . 1 - черновик. По умолчанию 0 - не черновик.
- lang - Идентификатор языка, на котором будут произносится числительные (дата/время/числа/номера телефонов/валюта). Допустимые значения: rus, eng. По умолчанию – не задан. Если параметр не задан, то используется язык пользователя, указанный в его настройках.
- callerid - Номер телефона, который будет виден принимающей стороне. По умолчанию, '+74959568262'. Для action = send. Пока не поддерживается.
- name - Название задания на отправку голосового(-ых) сообщения(-ий) либо название пользовательского голосового сообщения. Если параметр не указан, то используется стандартное название “New voice message task”. Допустимая длина параметра от 1 до 64 символов. Для action = send, upload, update, record. В интерфейсе для отправки можно разрешить пользователю указывать это название, тогда в общей статистике будет понятна суть задания на рассылку.
- message - Идентификатор пользовательского голосового сообщения для отправки (на сайте его можно посмотреть на странице "Голосовые сообщения". Необходимо щелкнуть по названию сообщение и в адресной строке в параметре id_item= будет указан идентификатор сообщения). Также может представлять собой строку, в которой указано, какие сообщения и в какой последовательности проигрывать. Может быть пустым. В этом случае, идентификатор сообщения будет браться из файла с номерами телефонов. Для action = send, update. В сообщение можно указывать числительные для проигрывания. Поддерживаются: номера телефонов (ph:), дата (в формате ГГГГММДД, например, 20121221 - 21 декабря 2012 года) (dt:), время (в формате ЧЧММ, например, 2012 - это 8 часов 12 минут) (tm:), валюта (рубли = R123, доллары - $123) (cur:), числа (num:), цифры (dig:), голосовое сообщение (b:). Можно указывать несколько значений для проигрывания, например: b:12345,tm:12:55. Тут b:12345 - сообщение, в котором записана фраза "Сейчас ", а tm:12:55 - это время. В итоге система проиграет: Сейчас 12 часов 55 минут.
- who - Для action = getvmsgs указывает номер телефона, для которого нужно получить статистику
- fromdttm - Для action = getvmsgs, statistics указывает дату и время, после которой необходимо получить список голосовых сообщений
- untildttm - Для action = getvmsgs, statistics указывает дату и время, до которой необходимо получить список голосовых сообщений
- incl - Для action = getvmsgs, statistics указывает включать или нет дату и время для параметров fromdttm и untildttm (то есть, использовать “<"/">" или "<="/">=")
- what - Для action = getvmsgs, getvmsg, update, delete: 0 – все (входящие и исходящие), 1 – входящие прочитанные, 2 – входящие не прочитанные, 3 – все входящие, 4 – исходящие, 5 – пользовательские
- count - Для action = getvmsgs, statistics указывает количество голосовых сообщений, которые необходимо получить
- how - Указывает, каким образом необходимо получить голосовое сообщение. Для действия action = getvmsg. Возможные значения: file – получить в виде файла, call – в виде телефонного звонка на указанный номер
- group - Название группы контактов адресной книги, которым необходимо отправить голосовые сообщения. У контакта адресной книги берется первый контакт с одним из типов "Телефон", "Домашний телефон", "Рабочий телефон", "Мобильный телефон". Если его нет, то сообщение ему не будет отправлено. Если их несколько, то сообщение отправляется на первый указанный телефон.
- report_to - Адрес электронной почты, куда следует отправлять отчет о выполнении задания.
- username – логин пользователя. Обязательный параметр.
- type – тип возвращаемого результата: xml (по умолчанию) или html, json. Необязательный параметр.
- signature – подпись запроса. Обязательный параметр. Как создать подпись смотрите раздел "Создание подписи (signature)"
Поле 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 – Указывает, что не удалось подключится к серверу приложения для выполнения операции. Однако операция может быть выполнена чуть позже.
Статусы заданий на голосовую рассылку:
- 0 - не удалось выполнить
- 10 - выполнено
- 11 - выполнено частично (не на все номера в задании удалось дозвониться)
- 30 - выполняется (идет обзвон)
- 40 - прекращено системой (из-за нехватки средств, например)
- 50 - приостановлено пользователем
Обращаю ваше внимание на то, что API не рассчитывает, сколько денег может понадобиться. Поэтому, если у вас слишком мало денег, то задание прервется. Вы об этом получите уведомление по email, если его указали.
