Руководство по взаимодействию с сервисом на основе HTTPS протокола, методом GET

Запросы необходимо отправлять в UTF-8 кодировке. Не стоит использовать URL длиной более 2,000 символов. Но этот параметр зависит от многих факторов и может различаться в большую или меньшую сторону. Одинаковые запросы можно отправлять не чаще 1 раза в 1 минуту. В случае ошибки вернется:

Запрос на отправку сообщения

Отправляется GET-запрос по адресу:

Пример:

Где:

• login – Логин пользователя;

• password – Пароль;

• phone

  • Номер абонента, которому адресовано сообщение. Можно несколько телефонов через запятую. Номера в международном формате, например, 

  79000000001 (для России), 380442589632 (для Украины);

• send_viber – Отправлять ли VIBER сообщение. Также является порядком сортировки отправки VIBER сообщения (от меньшего к большему). Может принимать значение от 0 до 9, где 0 - не отправлять VIBER сообщение;

• sender_viber – Имя отправителя VIBER. Именно это значение будет выводиться на телефоне абонента в поле от кого сообщение;

• text_viber – Текст VIBER сообщения. Не должен превышать более 1000 символов. Обязательный параметр;

• button_text – Текст кнопки. Не более 19 символов. Необязательный параметр. При добавлении, обязательно чтоб была указана ссылка кнопки в параметре button_url;

• button_url – Ссылка кнопки. Необязательный параметр. При добавлении, обязательно чтоб было указано название кнопки в параметре button_text;

• image_url – Ссылка на изображение. Необязательный параметр. В случае добавления изображения, также необходимо наличие кнопки (button_text и button_url);

• send_sms – Отправлять ли SMS. Также является порядком сортировки отправки SMS (от меньшего к большему). Может принимать значение от 0 до 9, где 0 - не отправлять SMS;

• sender_sms

  • Отправитель SMS. Именно это значение будет выводиться на телефоне абонента в поле от кого SMS;

• text_sms

  • Текст SMS.

• validity_period_viber – Время жизни VIBER сообщения. За этот период, система делает попытки доставить сообщение абоненту. Если за указанный период не будет доставлено сообщение, оно профинализируется со статусом просрочено либо не доставлено. Необязательный параметр. Указывается в минутах, например "60" - что значит 1 час. Если не указано, по умолчанию будет "60";

• finale_viber_read – Считать финальным доставленным VIBER сообщением статус "прочитано". В системе VIBER существуют статусы как доставлено и прочитано. В случае если в данном поле указали "1", то в VIBER сообщении, в котором фигурирует статус доставлено, но не прочитано, по истечению время жизни VIBER сообщения - будет попытка переотправки сообщения по другой системе (например через SMS), если в самом XML запросе фигурирует каскадная отправка (send_viber и send_sms);

• send_vk

  • Отправлять ли VK сообщение. Также является порядком сортировки отправки VK сообщения (от меньшего к большему). Может принимать значение от 0 до 9, где 0 - не отправлять VK сообщение. Для открытия данного направления для вас, свяжитесь с вашим менеджером;

• templateId

  • Идентификатор шаблона в системе. Можете посмотреть Идентификатор шаблона в личном кабинете;

• templateData

  • Значения параметров шаблона. Шаблон должен быть согласован VK. В GET запросе должен быть в виде JSON-данных. Можете использовать php функцию urlencode() для этих данных, во избежание ошибок;

В данном примере, первым будет попытка отправки VIBER сообщения, и в случае недоставки, будет попытка инициализация отправки VK сообщения, далее SMS;

В случае успешной отправки сообщения

Возвращается ID сообщения в plainText. Пример:

В случае отправки на несколько номеров возращается ID сообщения через запятую в plaintText. Пример:

В случае ошибки

В случае возникновения ошибки возращается текст ошибки в plainText.

Проверка статуса сообщения

Отправляетя GET-запрос по адресу:

Пример:

Где: login – Логин пользователя; password – Пароль; * id_message – ID сообщения.

В случае успешного запроса

В случае успешного запроса возращается статус сообщения в plainText:

• send

  • Статус сообщения не получен;

• not_deliver

  • Сообщение не было доставлено. Конечный статус (не меняется со временем);

• expired

  • Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем);

• deliver

  • Сообщение доставлено. Конечный статус (не меняется со временем);

• partly_deliver

  • Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки.

Пример:

В случае ошибки

В случае возникновения ошибки возвращается текст ошибки в plainText.

Руководство по взаимодействию с сервисом на основе JSON документов, методом POST

Общие принципы отправки

На определенный адрес сервера отправляются JSON документы (описание JSON документов, их назначение и адреса сервера приведены ниже). При этом используется POST метод.

Заголовки отправляемых данных должны содержать:

Кодировка JSON документов UTF-8.

Пример передачи JSON документа на php

Отправка сообщения

Адрес сервера:

JSON-документ:

PHP-данные:

Где:

• login – Логин пользователя;

• password – Пароль;

• message – Сообщения;

  • name_delivery – Название рассылки. Если поле является пустым, по умолчанию - "Шлюз";

  • time_send – Желательное время отправки сообщения, в формате: YYYY-MM-DD hh:mm где, YYYY-год, MM-месяц, DD-день, hh-часы, mm-минуты. Например 2017-11-23 13:00. Если поле является пустым, то отправка сообщения происходит сразу;

  • send_viber – Отправлять ли VIBER сообщение. Также является порядком сортировки отправки VIBER сообщения (от меньшего к большему). Может принимать значение от 0 до 9, где 0 - не отправлять VIBER сообщение;

  • sender_viber – Имя отправителя VIBER. Именно это значение будет выводиться на телефоне абонента в поле от кого сообщение;

  • text_viber – Текст VIBER сообщения. Не должен превышать более 1000 символов. Обязательный параметр;

  • button_text – Текст кнопки. Не более 19 символов. Необязательный параметр. При добавлении, обязательно чтоб была указана ссылка кнопки в параметре button_url;

  • button_url – Ссылка кнопки. Необязательный параметр. При добавлении, обязательно чтоб было указано название кнопки в параметре button_text;

  • image_url – Ссылка на изображение. Необязательный параметр. В случае добавления изображения, также необходимо наличие кнопки (button_text и button_url);

  • validity_period_viber – Время жизни VIBER сообщения. За этот период, система делает попытки доставить сообщение абоненту. Если за указанный период не будет доставлено сообщение, оно профинализируется со статусом просрочено либо не доставлено. Необязательный параметр. Указывается в минутах, например "60" - что значит 1 час. Если не указано, по умолчанию будет "60";

  • finale_viber_read – Считать финальным доставленным VIBER сообщением статус "прочитано". В системе VIBER существуют статусы как доставлено и прочитано. В случае если в данном поле указали "1", то в VIBER сообщении, в котором фигурирует статус доставлено, но не прочитано, по истечению время жизни VIBER сообщения - будет попытка переотправки сообщения по другой системе (например через SMS), если в самом JSON запросе фигурирует каскадная отправка (send_viber и send_sms);

  • send_sms – Отправлять ли SMS. Также является порядком сортировки отправки SMS (от меньшего к большему). Может принимать значение от 0 до 9, где 0 - не отправлять SMS;

  • sender_sms

    • Отправитель SMS. Именно это значение будет выводиться на телефоне абонента в поле от кого SMS;

  • text_sms

    • Текст SMS;

  • send_vk

    • Отправлять ли VK сообщение. Также является порядком сортировки отправки VK сообщения (от меньшего к большему). Может принимать значение от 0 до 9, где 0 - не отправлять VK сообщение. Для открытия данного направления для вас, свяжитесь с вашим менеджером;

  • templateId

    • Идентификатор шаблона в системе. Можете посмотреть Идентификатор шаблона в личном кабинете;

  • templateData

    • Значения параметров шаблона. Шаблон должен быть согласован VK;

  • phones

    • Получатели сообщений;

    • phone – Номер абонента, которому адресовано сообщение. В международном формате, например, 79000000001 (Для России), 380442589632 (Для Украины) и т.д.;

    • client_id_message

      • ID сообщения на стороне клиента. Число. Необязательный параметр, позволяет избежать повторной отправки. Если раннее с этого аккаунта уже было отправлено сообщение с таким номером, то повторная отправка не производится.

В ответ может быть выдан один из следующих JSON-документов:

В случае возникновения ошибки в отправляемом JSON-документе

JSON:

PHP (массив, полученный через php функцию json_decode):

В случае получения правильного JSON-документа:

JSON:

PHP (массив, полученный через php функцию json_decode):

Где:

• message – Сообщения;

• id_message

  • ID сообщения в системе для проверки статуса;

• client_id_message

  • ID сообщения на стороне клиента;

• phone – Номер абонента, которому адресовано сообщение;

• count_message

  • Количество частей сообщения. Указано количество частей сообщения в первом указанном направлении (viber, sms);

• id_viber

  • ID VIBER сообщения. 0 - если не было отправлено VIBER сообщение;

• id_sms

  • ID SMS сообщения. 0 - если не было отправлено SMS сообщение;

• id_vk

  • ID VK сообщения. 0 - если не было отправлено VK сообщение;

• error

  • Информация об ошибке, если в процессе отправки сообщения произошла ошибка.

Получение статуса сообщения

Адрес сервера:

JSON-документ:

PHP-данные:

Где:

• login – Логин пользователя;

• password – Пароль;

• state

  • Статусы сообщений:

  • id_message

    • ID сообщения в системе.

В ответ может быть выдан один из следующих JSON-документов:

В случае возникновения ошибки в отправляемом JSON-документе

JSON:

PHP (массив, полученный через php функцию json_decode):

В случае получения правильного JSON-документа:

JSON:

PHP (массив, полученный через php функцию json_decode):

Где:

• id_message

  • ID сообщения в системе;

• time_change_state

  • Время последней смены состояния, в формате: YYYY-MM-DD hh:mm:ss где, YYYY-год, MM-месяц, DD-день, hh-часы, mm-минуты, ss-секунды. Например 2017-11-23 13:15:25. Поле является пустым, если сообщение с указаным ID не обнаружено;

• state – Статус сообщения, может принимать следующие значения:

  • send

    • В процессе работы (не профинализировано);

  • not_deliver

    • Сообщение не было доставлено. Конечный статус (не меняется со временем);

  • expired

    • Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем);

  • deliver

    • Сообщение доставлено. Конечный статус (не меняется со временем);

  • partly_deliver

    • Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки;

  • ДРУГОЕ

    • Если статус сообщения не один из указанных выше, статус означает текст ошибки например "Сообщение с таким ID не принималось";

• state_sms

  • Статус SMS, может принимать следующие значения:

  • send

    • Не было отправлено;

  • not_deliver

    • Сообщение не было доставлено. Конечный статус (не меняется со временем);

  • expired

    • Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем);

  • deliver

    • Сообщение доставлено. Конечный статус (не меняется со временем);

  • partly_deliver

    • Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки;

• state_viber

  • Статус VIBER сообщения, может принимать следующие значения:

  • send

    • Не было отправлено;

  • not_deliver

    • Сообщение не было доставлено. Конечный статус (не меняется со временем);

  • expired

    • Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем);

  • deliver

    • Сообщение доставлено. Конечный статус (не меняется со временем);

  • partly_deliver

    • Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки;

• state_vk

  • Статус VK сообщения, может принимать следующие значения:

  • send

    • Не было отправлено;

  • not_deliver

    • Сообщение не было доставлено. Конечный статус (не меняется со временем);

  • expired

    • Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем);

  • deliver

    • Сообщение доставлено. Конечный статус (не меняется со временем);

  • partly_deliver

    • Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки;

• num_parts_sms

  • Количество частей в SMS, в случае если было отправлено SMS;

• price_sms

  • Списанные средства за SMS, в случае если было отправлено SMS.

• price_viber

  • Списанные средства за VIBER сообщение, в случае если было отправлено VIBER сообщение.

• price_vk

  • Списанные средства за VK сообщение, в случае если было отправлено VK сообщение.

Руководство по взаимодействию с сервисом на основе XML документа, методом POST

Общие принципы отправки

На определенный адрес сервера отправляются XML документы (описание XML документов, их назначение и адреса сервера приведены ниже). При этом используется POST метод.

Заголовки отправляемых данных должны содержать:

Кодировка XML документов UTF-8. Передаваемый XML документ не должен содержать переводов строки. Переводы строк в самих данных должны быть заменены на "\n".

Пример передачи XML документа на php

Отправка сообщения

Адрес сервера:

XML-документ:

Где:

• login – Логин пользователя;

• password – Пароль;

• message – Сообщения;

  • name_delivery – Название рассылки. Если поле является пустым, по умолчанию - "Шлюз";

  • time_send – Желательное время отправки сообщения, в формате: YYYY-MM-DD hh:mm где, YYYY-год, MM-месяц, DD-день, hh-часы, mm-минуты. Например 2017-11-23 13:00. Если поле является пустым, то отправка сообщения происходит сразу;

  • send_viber – Отправлять ли VIBER сообщение. Также является порядком сортировки отправки VIBER сообщения (от меньшего к большему). Может принимать значение от 0 до 9, где 0 - не отправлять VIBER сообщение;

  • sender_viber – Имя отправителя VIBER. Именно это значение будет выводиться на телефоне абонента в поле от кого сообщение;

  • text_viber – Текст VIBER сообщения. Не должен превышать более 1000 символов. Обязательный параметр;

  • button_text – Текст кнопки. Не более 19 символов. Необязательный параметр. При добавлении, обязательно чтоб была указана ссылка кнопки в параметре button_url;

  • button_url – Ссылка кнопки. Необязательный параметр. При добавлении, обязательно чтоб было указано название кнопки в параметре button_text;

  • image_url – Ссылка на изображение. Необязательный параметр. В случае добавления изображения, также необходимо наличие кнопки (button_text и button_url);

  • validity_period_viber – Время жизни VIBER сообщения. За этот период, система делает попытки доставить сообщение абоненту. Если за указанный период не будет доставлено сообщение, оно профинализируется со статусом просрочено либо не доставлено. Необязательный параметр. Указывается в минутах, например "60" - что значит 1 час. Если не указано, по умолчанию будет "60";

  • finale_viber_read – Считать финальным доставленным VIBER сообщением статус "прочитано". В системе VIBER существуют статусы как доставлено и прочитано. В случае если в данном поле указали "1", то в VIBER сообщении, в котором фигурирует статус доставлено, но не прочитано, по истечению время жизни VIBER сообщения - будет попытка переотправки сообщения по другой системе (например через SMS), если в самом XML запросе фигурирует каскадная отправка (send_viber и send_sms);

  • send_sms – Отправлять ли SMS. Также является порядком сортировки отправки SMS (от меньшего к большему). Может принимать значение от 0 до 9, где 0 - не отправлять SMS;

  • sender_sms

    • Отправитель SMS. Именно это значение будет выводиться на телефоне абонента в поле от кого SMS;

  • text_sms

    • Текст SMS;

  • send_vk

    • Отправлять ли VK сообщение. Также является порядком сортировки отправки VK сообщения (от меньшего к большему). Может принимать значение от 0 до 9, где 0 - не отправлять VK сообщение. Для открытия данного направления для вас, свяжитесь с вашим менеджером;

  • templateId

    • Идентификатор шаблона в системе. Можете посмотреть Идентификатор шаблона в личном кабинете;

  • templateData

    • Значения параметров шаблона. Шаблон должен быть согласован VK;

  • abonent

    • Получатели сообщений;

    • phone – Номер абонента, которому адресовано сообщение. В международном формате, например, 79000000001 (Для России), 380442589632 (Для Украины) и т.д.;

    • client_id_message

      • ID сообщения на стороне клиента. Число. Необязательный параметр, позволяет избежать повторной отправки. Если раннее с этого аккаунта уже было отправлено сообщение с таким номером, то повторная отправка не производится.

В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе

error

• Текст ошибки.

В случае получения правильного XML-документа

Где:

• message – Сообщения;

• id_message

  • ID сообщения в системе для проверки статуса;

• client_id_message

  • ID сообщения на стороне клиента;

• phone – Номер абонента, которому адресовано сообщение;

• count_message

  • Количество частей сообщения. Указано количество частей сообщения в первом указанном направлении (viber, sms);

• id_viber

  • ID VIBER сообщения. 0 - если не было отправлено VIBER сообщение;

• id_vk

  • ID VK сообщения. 0 - если не было отправлено VK сообщение;

• id_sms

  • ID SMS сообщения. 0 - если не было отправлено SMS сообщение;

• error

  • Информация об ошибке, если в процессе отправки сообщения произошла ошибка.

Получение статуса сообщения

Адрес сервера:

XML-документ:

Где

• login

  • ваш логин в системе.

• password

  • ваш пароль в системе.

• id_message

  • ID сообщения в системе.

В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:

error

• Текст ошибки.

В случае получения правильного XML-документа:

Где:

• id_message

  • ID сообщения в системе;

• time_change_state

  • Время последней смены состояния, в формате: YYYY-MM-DD hh:mm:ss где, YYYY-год, MM-месяц, DD-день, hh-часы, mm-минуты, ss-секунды. Например 2017-11-23 13:15:25. Поле является пустым, если сообщение с указаным ID не обнаружено;

• Статус – Статус сообщения, может принимать следующие значения:

  • send

    • В процессе работы (не профинализировано);

  • not_deliver

    • Сообщение не было доставлено. Конечный статус (не меняется со временем);

  • expired

    • Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем);

  • deliver

    • Сообщение доставлено. Конечный статус (не меняется со временем);

  • partly_deliver

    • Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки;

  • ДРУГОЕ

    • Если статус сообщения не один из указанных выше, статус означает текст ошибки например "Сообщение с таким ID не принималось";

• state_sms

  • Статус SMS, может принимать следующие значения:

  • send

    • Не было отправлено;

  • not_deliver

    • Сообщение не было доставлено. Конечный статус (не меняется со временем);

  • expired

    • Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем);

  • deliver

    • Сообщение доставлено. Конечный статус (не меняется со временем);

  • partly_deliver

    • Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки;

• state_viber

  • Статус VIBER сообщения, может принимать следующие значения:

  • send

    • Не было отправлено;

  • not_deliver

    • Сообщение не было доставлено. Конечный статус (не меняется со временем);

  • expired

    • Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем);

  • deliver

    • Сообщение доставлено. Конечный статус (не меняется со временем);

  • partly_deliver

    • Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки;

• state_vk

  • Статус VK сообщения, может принимать следующие значения:

  • send

    • Не было отправлено;

  • not_deliver

    • Сообщение не было доставлено. Конечный статус (не меняется со временем);

  • expired

    • Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем);

  • deliver

    • Сообщение доставлено. Конечный статус (не меняется со временем);

  • partly_deliver

    • Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки;

• num_parts_sms

  • Количество частей в SMS, в случае если было отправлено SMS;

• price_sms

  • Списанные средства за SMS, в случае если было отправлено SMS.

• price_viber

  • Списанные средства за VIBER сообщение, в случае если было отправлено VIBER сообщение.

• price_vk

  • Списанные средства за VK сообщение, в случае если было отправлено VK сообщение.