VK#

Особенности отправки VK-сообщений#

При отправке VK-сообщений следует учитывать следующие особенности:

Партнёр может отправлять только текстовые сообщения длиной не более 2048 символов.
Сообщения могут содержать ссылки. При необходимости, ссылки могут быть сокращены, см. Сервис сокращения ссылок.
Сообщения отправляются от имени группы «ВКонтакте» произвольному пользователю «ВКонтакте» по его номеру телефона.
Партнёр может отправлять не более 50 сообщений в секунду от одной группы «ВКонтакте».
Партнёр может отправлять не более 5 сообщений в сутки одному пользователю от одной группы «ВКонтакте».
Все группы «ВКонтакте» и примеры текстов сообщений проходят предварительную модерацию с предъявлением договора на оказание услуг, товарного знака и прочих необходимых документов.
Сообщения доставляются в рамках времени жизни от 1 минуты до 24 часов. Если уведомление не получено устройством пользователя в течение времени жизни, оно не будет доставлено и показано пользователю.
Тарифицируются только доставленные сообщения.
Сообщения доставляются только активным пользователям «ВКонтакте». Активными пользователями считаются те, что заходили на сайт в течение последних 7 дней (мобильная или веб-версия социальной сети).

Подключение сервиса отправки VK-сообщений#

Для подключения сервиса отправки VK-сообщений Партнёр должен дополнительно сообщить Сервис-провайдеру:

URL группы “ВКонтакте“ (от имени которой будет осуществляться отправка);
примеры текстовых сообщений для модерации.

Правила модерации сети «Вконтакте»#

Настоящие правила модерации применяются ко всем шаблонам сообщений, направляемым на согласование для дальнейшей рассылки пользователям проектов Mail.Ru Group.

Модерацию проходит отправитель (компания) и текст (шаблон) сообщения. При проверке компании принимается во внимание отрасль, к которой относится компания, тип компании, ее репутация на рынке.

К рассмотрению не принимаются сообщения от следующих компаний:

Микрофинансовые организации.
Коллекторские агентства (в том числе соответствующие отделы банков).
Букмекерские конторы.
Online казино.
Ювелирные магазины.
Производители сигарет.
Производители лекарственных препаратов.
Производители алкогольной продукции.

При модерации текста действуют следующие правила:

К рассмотрению не принимаются тексты рекламного характера. Рекламой признаются любые сообщения, адресованные неопределенному кругу лиц и направленные на привлечение внимания к объекту рекламирования, формирование или поддержание интереса к нему и его продвижение на рынке.
В случае, если шаблон сообщения, поданного на модерацию, содержит и сервисную составляющую, и рекламную, он не проходит модерацию.
Все шаблоны сообщений должны отвечать требованиям законодательства Российской Федерации и законодательству той страны, в которой находятся пользователи, которым адресуется сообщение, а также существующим этическим нормам и принципам (шаблоны не должны содержать сообщений, оскорбляющих человеческое достоинство, пропагандирующих насилие, расовую или национальную вражду и т.п.).
Шаблоны сообщений не могут содержать информацию прямо или косвенно компрометирующую Mail.Ru Group и все проекты и продукты, входящие в состав группы компаний, а также в шаблонах сообщений не должна содержаться информация, которая может рекламировать продукты, конкурирующие по ценовым или потребительским свойствам с услугами и сервисами, оказываемыми проектами и сервисами Mail.Ru Group.
Шаблоны сообщений должны содержать исключительно информацию, которая касается взаимодействия пользователя с владельцем официальной группы, от имени которой происходит отправка сообщения.
Шаблоны сообщений должны содержать информацию исключительно в отношении заказов и/или действий пользователей, совершенных непосредственно перед отправкой информационного сообщения.
Наличие ссылок на веб-страницы и сайты в шаблонах сообщений допускается только по индивидуальному согласованию.

Запрос на отправку#

Для отправки сообщения Партнёру следует установить соединение с сервером и передать Сервис-провайдеру пакет submit_sm, в котором содержатся все необходимые параметры сообщения (опционально, также и TLV-параметры).

Примечание

При необходимости использования дополнительного функционала следует указать значения соответствующих TLV-параметров, описание которых приведено в следующих разделах сайта:

Основные параметры запроса#

Параметр	Тип	Описание
source_addr	string	Сервисное имя, с которого будет отправлено сообщение. В случае отсутствия параметра отправка производится с номера, заданного по умолчанию на платформе Сервис-провайдера (настройка по желанию Партнёра). Кодировка значения параметра `source_addr` (согласно протоколу SMPP): ASCII.
destination_addr	string	Номер телефона абонента. Длина, символов, не более: 25. Примеры: 79036550550, +79036550550, 8-903-655-05-50, 89036550550.
short_message	string	Текст сообщения для отправки абоненту. Длина сообщения для Viber: не более 1000 символов. Длина пользовательских данных для поля `short_message`: не более 254 октетов. Текстовые сообщения длиной более 254 октетов рекомендуется передавать одной PDU в TLV-параметре message_payload``(id = ``0x0424). Предупреждение Одновременное использование обоих параметров недопустимо. При использовании параметра `message_payload` значение параметра `short_message` указывать не следует.
data_coding	integer	Схема/тип кодирования текста сообщения. Задается в соответствии со стандартом GSM 03.38. Допустимые значения: 0 – DEFAULT, кодировка по умолчанию; 1 – ASCII; 3 – LATIN1; 6 – LATIN_CYR; 8 – UCS2. Если кодировка текста отличается от заявленных выше, сообщение воспринимается платформой как бинарное. Для передачи текста сообщения рекомендуется использовать кодировку `UCS2` (data_coding = 8). Для передачи сообщений в латинице возможно использование `data_coding` = 0, что соответствует кодировке GSM DEFAULT ALPHABET или ASCII – по желанию Партнёра (единая настройка на прием и передачу сообщений).
esm_class	integer	Множество значений этого параметра задается протоколом SMPP версии 3.4, раздел 5.2.12.
registered_delivery	integer	Параметр указывает, необходимы ли Партнёру уведомления о статусе доставки сообщения. Возможные значения: 0 – Партнёру не требуется уведомление о статусе доставки; 1 – Партнёру требуется уведомление о статусе доставки; 2 – Партнёру требуется уведомление о статусе только в случае, если сообщение не доставлено абоненту. Данная опция может быть задана по умолчанию на стороне Сервис-провайдера (по запросу Партнёра).
schedule_delivery_time	string	Дата отправки сообщения. Для даты отправки на платформе Сервис-провайдера установлено ограничение: она не может быть позже определённого срока с текущего момента. Размеры данного ограничения следует уточнять в службе поддержки Сервис-провайдера. Поле `schedule_delivery_time` можно задавать как в относительном, так и в абсолютном формате. Кроме того, поддерживается специальный формат, при помощи которого возможно указать интервал доставки по локальному часовому поясу абонента, вычисленному по его номеру телефона. Формат значения для параметра `YYMMDDhhmmsstnnp`, где: YYMMDDhhmmss – год, месяц, день, часы, минуты, секунды; t – десятые доли секунд; nn – четверти часа (по 15 минут), например, для 8 часов значение будет «32»; p – сдвиг. Возможные значения: “+” и “–” задают сдвиг времени на четверть часа относительно GMT, например, “08+” соответствует GMT+2, а “04–” соответствует GMT–1; “R” – значения t и nn игнорируется, всё остальное прибавляется к текущему локальному времени. “А” – дата и время считаются указанными по локальному времени абонента и задают начало интервала возможной отправки, а четверти задают длину этого интервала. Отправка происходит внутри указанного времени, даже если дата в прошлом, т.е., если «сейчас» 10:00, а интервал задан как «вчера» с 15:00 до 18:00, то сообщение не будет отправлено раньше 15:00. Если в текущих сутках интервал уже закончился, его начало перемещается на следующий день.
validity_period	string	Время жизни сообщения. Диапазон времени жизни для VK: от 60 до 86400 секунд (до 1 суток); Формат значения для параметра `YYMMDDhhmmsstnnp`, где: YYMMDDhhmmss – год, месяц, день, часы, минуты, секунды; t – десятые доли секунд; nn – четверти часа (по 15 минут), например, для 8 часов значение будет «32»; p – сдвиг. Возможные значения: “+” и “–” задают сдвиг времени на четверть часа относительно GMT, например, “08+” соответствует GMT+2, а “04–” соответствует GMT–1; “R” – значения t и nn игнорируется, всё остальное прибавляется к текущему локальному времени.

TLV-параметры запроса#

TLV-параметры для отправки сообщений от Партнёра к Сервис-провайдеру.

TLV-параметр	Поле	Размер (октетов)	Тип	Описание
message_payload	Tag	2	Integer	id = 0x0424
	Length	2	Integer	Длина параметра в октетах.
	Value	до 2048	Octet String	Текст сообщения длиной более 254 октетов (многосегментное сообщение с точки зрения SMPP). SMPP-сервер Сервис-провайдера поддерживает склейку сообщений, разбитых на части, одним из следующих методов: UDH-8; UDH-16; с использованием TLV-параметров. Примечание Текстовые сообщения длиной менее 254 октетов рекомендуется передавать в параметре `short_message`. Одновременное использование параметров `message_payload` и `short_message` недопустимо.
ptag	Tag	2	Integer	id = 0x1411
	Length	2	Integer	Длина параметра в октетах.
	Value	до 1000	Octet String	Идентификатор сообщения в системе Партнёра. Может содержать от 1 до 50 символов. Допустимые символы: 0…9a…zA…Z-. Это может быть любой идентификатор в системе Партнёра. Например, уникальный идентификатор сообщения или идентификатор подразделения, инициирующего запрос на отправку. Сервис-провайдер не контролирует значения, переданные в параметре `ptag` (проверяется только соответствие формату). Сервис-провайдер опционально возвращает Партнёру данный идентификатор в рамках отправки статуса доставки сообщения (см. Сервис получения статусов доставки).

Ответ на запрос#

На пакет submit_sm сервер Сервис-провайдера отвечает пакетом submit_sm_resp с полем command_status.

Если пакет принят и обработан успешно, тело пакета submit_sm_resp будет содержать message_id — уникальный идентификатор (целое положительное число), присвоенный на сервере Сервис-провайдера данному PDU.

В дальнейшем значение message_id используется Партнёром для получения и анализа статусов доставки сообщения.

Возможные значения поля command_status приведены в таблицах ниже.

Ответ при успешной отправке#

В случае успешной отправки возвращается код ответа (HEX) 0x00.

Код (HEX)	Описание	Действие Партнёра
0x00	Пакет принят успешно.	Ошибок нет, штатная работа сервиса.

Ошибки при отправке#

Для ошибочных результатов код ответа (HEX) будет отличный от 0x00.

Код (HEX)	Описание	Действие Партнёра
0x01	Превышена допустимая длина текста сообщения.	Партнёр может сократить текст до допустимых значений и повторить попытку отправки сообщения.
0x03	Партнёр передал PDU неподдерживаемого типа (query_sm, submit_multi, data_sm и т.п.).	Партнёр устраняет ошибки на своей стороне.
0x08	Общая системная ошибка на сервере.	Партнёр может повторить попытку отправить сообщение. Если ошибка повторяется, следует прекратить попытки отправить сообщение и обратиться в Службу технической поддержки, предоставив наиболее полную информацию об условиях возникновения данной ошибки.
0x0A	Неверное имя отправителя. Партнёр передал в параметре `source_addr` значение, с которого не разрешена отправка сообщений абонентам.	Партнёр устраняет ошибки на своей стороне, после этого может повторить отправку сообщения с корректным `source_addr`.
0x0B	Неверный номер получателя. Попытка отправить сообщение на номер, для которого запрещена отправка сообщений.	Партнёр не должен повторять отправку сообщения. Партнёру следует обратиться к менеджеру Сервис-провайдера для выяснения возможности отправки сообщений на данный номер.
0x0C	Передано некорректное значение TLV-параметра ptag (id = 0x1411).	Партнёр исправляет значение параметра и может повторить попытку отправки сообщения.
0x14	Очередь на отправку сообщений от Партнёра достигла максимально допустимого значения. Пример. Для сервиса Партнёра установлено максимальное количество сообщений в очереди для отправки абонентам – 100 сообщений. Если в очереди отправки Партнёра скопилось более 100 сообщений, то Сервис-провайдер отвечает этим кодом ошибки пока очередь не уменьшится.	Партнёр приостанавливает процесс отправки SMS (`submit_sm`) на 5 сек, потом возобновляет рассылку. Партнёр может повторить отправку сообщений, на которых возникла ошибка. Если ошибка повторится более пяти разподряд, следует прекратить процесс отправки сообщений и обратиться в Службу технической поддержки, предоставив наиболее полную информацию об условиях возникновения данной ошибки.
0x45	Попытка отправить сообщения после завершения триал-периода или при превышении количества разрешенных для триал-периода сообщений.	Партнёр не должен повторять отправку сообщения.
0x55	Превышен порог максимального количества ответных сообщений для режима «запрос-ответ» или «смешанный».	Партнёр должен дождаться следующего входящего сообщения от абонента.
0x58	Превышена пропускная способность, установленная для Партнёра. Пример. Для сервиса Партнёра установлена допустимая скорость 10 сообщений в секунду. Партнёр отправил 12 сообщений в секунду. Первые 10 сообщений будут успешно обработаны – Сервис-провайдер отправит сообщения абонентам. В ответ на последние два сообщения Сервис-провайдер вернет Партнёру код ошибки `0x58` и не будет отправлять эти два сообщения абонентам.	Партнёр останавливает процесс отправки (`submit_sm`) на 5 сек, потом возобновляет рассылку, не превышая допустимой скорости. Партнёр может повторить отправку сообщений, для которых возникла ошибка.
0x61	Указано некорректное значение параметра `schedule_delivery_time`.	Партнёр устраняет ошибки на своей стороне, после чего может повторить отправку с корректным `schedule_delivery_time`.
0x62	Превышен лимит продолжительности транзакции. Ошибка возникает, если значение, переданное в `schedule_delivery_time`, выходит за допустимые пределы.	Партнёр может повторить отправку с правильным значением параметра `schedule_delivery_time`.
0xAB	Попытка отправить дубликат сообщения. Пример. Для сервиса Партнёра включен функционал блокировки дубликатов. Партнёр отправил в течение суток три запроса на отправку сообщения на один и тот же номер абонента с одинаковым текстом. Первый запрос будет успешно обработан и сообщение будет отправлено абоненту. В ответ на последние два запроса Сервис-провайдер вернет Партнёру код ошибки `0xAB` и не будет отправлять эти два сообщения абоненту. Функционал блокировки дубликатов по умолчанию отключен для Партнёра. Функционал может быть включен по просьбе Партнёра.	Партнёр не должен повторять отправку сообщения.
0xC4	Партнёр передал некорректное значение в одном из TLV-параметров.	Партнёр устраняет ошибки на своей стороне, после чего может повторить отправку сообщения с корректным набором параметров.
0x500	Ошибка будет проявляться при условии, если в настройках интеграционного SMPP-клиента в параметрах протокола “Параметры протокола“ задан определённый метод склейки (“Склеивать через UDH“ или “Склеивать через TLV“), а от SMPP-клиента придет пакет, не соответствующий данному типу обработки. Ошибка не будет проявляться, если выбран параметр «Определять автоматически» (значение по умолчанию). В данном случае при получении от SMPP-клиента автоматически определяется тип пакета и выполняется склейка сообщения по определенному методу.	При проявление данной ошибки Партнёр останавливает процесс отправки сообщений, изменяет метод отправки данных сообщений на своей стороне (TLV или UDH), повторяет отправку данных сообщений. Если ошибка после проделанных изменений проявляется снова, следует обратиться в Службу технической поддержки Сервис-провайдера, предоставив наиболее полную информацию об условиях возникновения данной ошибки.