API для отправки голосовых сообщений

В данном форуме описаны все API, поддерживаемые нашими услугами.

API для отправки голосовых сообщений

Сообщение sd » 05 июл 2011, 13:52

Обновлено 03 Сентября 2014 года

Обращение к 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, если его указали.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

Re: API для отправки голосовых сообщений

Сообщение WhiteDemon » 14 янв 2012, 00:40

Здравствуйте. Столкнулся со следующей проблемой.
Сообщения доставляются только в дневное время(11:00-23:00), даже если явно указать время или использовать now.
Мешает какое-то расписание, можно ли его отключить или как-то избежать, приходится вручную его менять чтобы сообщение ушло в рассылку. Прикладываю скриншот, на всякий случай.
И еще один вопрос, можно ли использовать больше чем 2 попытки в случае неудачного звонка.
Спасибо.
13.01.2012 22.35.48.png
13.01.2012 22.35.48.png (23.05 Кб) Просмотров: 124640
WhiteDemon
 
Сообщения: 7
Зарегистрирован: 01 янв 2012, 20:37

Re: API для отправки голосовых сообщений

Сообщение sd » 14 янв 2012, 15:11

WhiteDemon писал(а):Здравствуйте. Столкнулся со следующей проблемой.
Сообщения доставляются только в дневное время(11:00-23:00), даже если явно указать время или использовать now.
Мешает какое-то расписание, можно ли его отключить или как-то избежать, приходится вручную его менять чтобы сообщение ушло в рассылку. Прикладываю скриншот, на всякий случай.
И еще один вопрос, можно ли использовать больше чем 2 попытки в случае неудачного звонка.
Спасибо.
13.01.2012 22.35.48.png

Постараемся разобраться, что там происходит. Могу сказать точно, что раньше 9 и позже 23 часов рассылать сообщения вам система не должна позволять (если где-то нет багов. Только в новый год ограничение снимается). Мы сейчас думаем, не отказаться ли от таких ограничений. Но пока мешает то, что есть достаточно неадекватных пользователей, из-за которых и пришлось вводить ограничения.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

Re: API для отправки голосовых сообщений

Сообщение WhiteDemon » 14 янв 2012, 19:04

Возможно ли сделать выборочную активацию данной опции? Мы, например, делаем сервис отправки поздравлений и розыгрышей и пользователи сами выбирают время доставки сообщений, соответственно проблем это не должно вызывать.
WhiteDemon
 
Сообщения: 7
Зарегистрирован: 01 янв 2012, 20:37

Re: API для отправки голосовых сообщений

Сообщение sd » 14 янв 2012, 20:41

WhiteDemon писал(а):Возможно ли сделать выборочную активацию данной опции? Мы, например, делаем сервис отправки поздравлений и розыгрышей и пользователи сами выбирают время доставки сообщений, соответственно проблем это не должно вызывать.

Вот как раз и могут возникнуть проблемы. Особенно, если ваши клиенты будут злоупотреблять такой услугой. В общем, надо подумать. Как вариант, можно попробовать использовать наше API.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

Re: API для отправки голосовых сообщений

Сообщение WhiteDemon » 14 янв 2012, 21:37

Ну услуга то платная, поэтому злоупотреблять не должны, и как показывает практика не особо и заказывают по ночам, но такое бывает. Вот, к примеру, на одном из самых крупных сайтов с открытками можно отправлять и ночью voicecards.ru
В любом случае, будем ждать вашего решения.
P.S. Задания формируются по API описанному в этой теме, или вы имели ввиду что-то другое?
WhiteDemon
 
Сообщения: 7
Зарегистрирован: 01 янв 2012, 20:37

Re: API для отправки голосовых сообщений

Сообщение alexsong » 14 янв 2012, 21:41

А Comtube сам не хочет развить свой сервис рассылки путем добавления шаблонов голосовых розыгрышей и поздравлений к различным праздникам? А то я, к примеру, на НГ замучился выискивать и конвертировать файлы в текущем варианте реализации. Думаю, совместно с пользователями пополняли бы данную коллекцию и услуга была востребована по приемлемой цене, а если по ценам обычных звонков - так вообще шоколадно. А то у специализированных на этом контор цены кусачие :)
Аватара пользователя
alexsong
 
Сообщения: 518
Зарегистрирован: 08 дек 2010, 15:14

Re: API для отправки голосовых сообщений

Сообщение sd » 14 янв 2012, 22:30

alexsong писал(а):А Comtube сам не хочет развить свой сервис рассылки путем добавления шаблонов голосовых розыгрышей и поздравлений к различным праздникам? А то я, к примеру, на НГ замучился выискивать и конвертировать файлы в текущем варианте реализации. Думаю, совместно с пользователями пополняли бы данную коллекцию и услуга была востребована по приемлемой цене, а если по ценам обычных звонков - так вообще шоколадно. А то у специализированных на этом контор цены кусачие :)

Мы думали на эту тему, но руководство не шибко хотело затевать эту тему. Тут много вопросов сразу поднимается. Если брать базу поздравлений у кого-то, то такая услуга будет стоить дорого (всякие там лицензионные отчисления). Если дать пользователям самим заполнять базу поздравлений и розыгрышей, то надо их модерировать во избежании загрузки нелегального контента (мы, как юр.лицо можем пострадать). А так, мне сама идея симпатична.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

Re: API для отправки голосовых сообщений

Сообщение alexsong » 15 янв 2012, 01:40

А может быть знаете какой то сторонний сайт с поздравлялками и розыгрышами, которые можно свободно скачать и попробовать использовать на вашем сервисе? ;)
Аватара пользователя
alexsong
 
Сообщения: 518
Зарегистрирован: 08 дек 2010, 15:14

Re: API для отправки голосовых сообщений

Сообщение sd » 15 янв 2012, 12:18

alexsong писал(а):А может быть знаете какой то сторонний сайт с поздравлялками и розыгрышами, которые можно свободно скачать и попробовать использовать на вашем сервисе? ;)

Не, к сожалению, не знаю. Честно говоря особо сильно этим и не занимался. В любом случае, реально классные поздравления/приколы просто так не получится использовать. В лучшем случае попросят удалить их с нашего сайта.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

След.

Вернуться в API

Просмотр страницы «Кто сейчас на форуме COMTUBE»

Сейчас этот форум просматривают: нет зарегистрированных пользователей и гости: 4

cron