2. Запросы


2.1. Отправить сообщения

URL: http://stream.ibatelecom.ru:8083/broker-api/send 

Запрос используется для отправки сообщений по различным каналам.

2.1.1 Тело запроса

Приведенный JSON демонстрирует все доступные в запросе параметры. Примеры запросов для разных задач доступны в разделе 3.

{
   	 "template-id": "",
   	 "priority": "",
   	 "blacklist-id": "",
 "external-id1": "",
 "external-id2": "",
 "external-id3": "",
   	 "timing": {
"localtime": "",
   	 	"start-datetime": "",
   	 	"end-datetime": "",
   		"allowed-starttime": "",
   		"allowed-endtime": "",
   		"send-evenly": "",
		"allowed-days": ""
},
"viber": {
"originator": "viberSender",
"ttl": "300",
   		"content": {
   			 "text" : "Test text",
   			 "image-url": "test.domain/picture.jpg",
   			 "button-name": "button",
   			 "button-url": "test.domain"
   			 }
   		 },
   	 "sms": {
   		"originator": "smsSender",
   		"ttl": "300",
   		"content": {
   			"text": "Test text"
   			}
   		},
   	"push": {
   		 "application": "pushApp",
   		 "ttl": "300",
   		 "content": {
   			"title": "",
   			"text": "Test text",
   			"extra-content": "",
			"additional-data" : {}
   			}
   		},
   	 "call": {
   		"originator": "79009009090",
   		"ttl": "300",
   		"content": {
   			"text": "Test text",
"menu": "Test",
"file": ""
   			},
   		"retry-attempts": "",
   		"retry-timeout": ""
   		},
"ussd": {
   		"originator": "150",
"ttl": "300",
   		"content": {
"text": "Test text",
   			 "menu": "Test"
   			}
   		},
   	"email": {
   		"originator": "emailSender@example.com",
   		"ttl": "300",
   		"content": {
   			"subject": "",
   			"text": "Test text",
   			"attached-files": [{"name.txt": "iwuanaUajwm"}, {"name.pdf": "iwuanaUajwm"}]
   			}
   		},
   	 "messages":
   		 [
   		 {
   		 "recipient": "79990009900",
   		 "email-address": "test@example.com",
   		 "message-id": "2017-11-07-18-29-30",
   		 "template-id": "",
   		 "priority": "",
 "variables": [],
   		 "timing": {		
"localtime": "",
   		 	"start-datetime": "",
   		 	"end-datetime": "",
   		 	"allowed-starttime": "",
   		 	"allowed-endtime": "",
"allowed-days": ""
},
   		 "viber": {
"originator": "viberSender",
"ttl": "300",
   			"content": {
   				 "text": "Test text",
   				 "image-url": "test.domain/picture.jpg",
   				 "button-name": "button",
   				 "button-url": "test.domain"
   				 }
   			 },
   		 "sms": {
   			"originator": "smsSender",
   			"ttl": "300",
   			 "content": {
   				"text": "Test text"
   				}
   			},
   		"push": {
   			 "application": "pushApp",
   			 "ttl": "300",
   			 "content": {
   				"title": "",
   				"text": "Test text",
   				"extra-content": "",
				"additional-data" : {}
   				}
   			},
   		 "call": {
   			"originator": "79009009090",
   			"ttl": "300",
   			"content": {
   				"text": "Test text",
"menu": "Test",
				"file": ""
   				},
   			"retry-attempts": "",
   			"retry-timeout": ""
   			},
   		 "ussd": {
   			"originator": "150",
"ttl": "300",
   			"content": {
 "text": "Test text",
   				 "menu": "Test"
   				}
   			}
   			},
   		 "email": {
   			"originator": "emailSender@example.com",
   			"ttl": "300",
   			"content": {
   				"subject": "",
   				"text": "Test text",
   				"attached-files": [],
   				}
   			}
   		]
}
JSON

2.1.2 Параметры запроса

2.1.2.1 Общие параметры

Название

Тип

Обязательность

Описание

1

template-id

string

Нет

Идентификатор шаблона для отправки сообщения

2

priority

string

Нет

Приоритет (указывается в цифровой форме):
2 - low - низкий,
4 - normal - обычный,
6 - high - высокий,
8 - realtime - наивысший.

3

blacklist-id

string

Нет

Идентификатор черного списка

4

external-id1

string

Нет

Дополнительный параметр, как правило не учитывается

5

external-id2

string

Нет

Дополнительный параметр, как правило не учитывается

6

external-id3

string

Нет

Дополнительный параметр, как правило не учитывается

7

timing

object

Нет

Временные настройки

8

viber

object

Нет

Параметры для отправки по каналу viber

9

sms

object

Нет

Параметры для отправки по каналу sms

10

push

object

Нет

Параметры для отправки по каналу push

11

call

object

Нет

Параметры для отправки по каналу call

12

email

object

Нет

Параметры для отправки по каналу email

13

ussd

object

Нет

Параметры для отправки по каналу ussd

14

messages

array

Да

Параметры получателей

2.1.2.2 Параметры объекта timing

Название

Тип

Обязательность

Описание

1

localtime

number

Нет

Отправлять по местному времени
0 - получателя
1 - системы

2

start-datetime

datetime

Нет

Дата начала отправки. Формат YYYY-MM-DD hh:mm. Если не указана, то сообщения отправляются сразу же.

3

end-datetime

datetime

Нет

Дата завершения отправки. Формат YYYY-MM-DD hh:mm. Если не указана, то система не стремится отправиться все сообщения до определенного времени.

4

allowed-starttime

datetime

Нет

Время, с которого разрешена отправка. Формат hh:mm

5

allowed-endtime

datetime

Нет

Время, до которого разрешена отправка. Формат hh:mm

6

send-evenly

number

Нет

Равномерно распределять отправку
1 - распределять
0 - не распределять

7

allowed-days

string

Нет

Разрешенные для отправки дни недели. Передаются как строка MON, TUE, WED, THU, FRI, SAT, SUN. Если не переданы, то отправка разрешена во все дни.

2.1.2.3 Параметры объектов каналов (viber, sms, push, call, email, ussd)

Название

Тип

Обязательность

Описание

1

originator

string

Нет

Адрес отправителя
Не используется для канала Push
Для канала Email адрес может быть указан следующим образом: <имя> адрес

2

application

string

Нет

Название приложения, куда будет отправлено уведомление Используется только для канала Push

3

ttl

Number

Нет

Время жизни сообщения в секундах. По истечении данного времени сообщению присваивается статус expired и производится отправка сообщения по альтернативному каналу, если он задан

4

content

object

Нет

Параметры для отправки контента

2.1.2.4 Параметры объекта content для viber

Название

Тип

Обязательность

Описание

1

text

string

Нет

Текст сообщения, максимальная длина 1000 символов.

2

image-url

string

Нет

Ссылка на картинку

3

button-name

string

Нет

Название кнопки

4

button-url

string

Нет

Ссылка для перехода по кнопке

2.1.2.5 Параметры объекта content для sms

Название

Тип

Обязательность

Описание

1

text

string

Нет

Текст сообщения, максимальная длина 70 символов кириллицей, 160 символов латиницей. Если длина сообщения больше указанных, то сообщение разбивается (при формировании user-сообщения) на несколько частей, каждая часть тарифицируется отдельно.

2.1.2.6 Параметры объекта content для push

Название

Тип

Обязательность

Описание

1

title

string

Нет

Заголовок сообщения.

2

text

string

Нет

Текст сообщения, максимальная длина 1000 символов.

3

extra-content

string

Нет

Дополнительный контент (строковый).

4

additional-data

object

Нет

Объект для передачи пользовательских параметров в виде пар ключ:значение, разделенных запятой. Значение должно иметь строковый тип.

2.1.2.7 Параметры объекта content для call

Название

Тип

Обязательность

Описание

1

text

string

Нет

Текст сообщения для синтеза TTS, до 2000 байт (1000 символов). Используется один из трех параметров: text, file,  ivrmenu. Запрос с с более чем одним параметром считается некорректным.

2

file

string

Нет

Название аудиофайла. Используется один из трех параметров: text, file, ivrmenu. Запрос с с более чем одним параметром считается некорректным.

3

menu

string

Нет

Название IVR-меню. Используется один из трех параметров: text, file, ivrmenu. Запрос с с более чем одним параметром считается некорректным.

4

retry-attempts

Number

Нет

Количество попыток повторного звонка. Допустимы только неотрицательные числа.

5

retry-timeout

Number

Нет

Интервал, через который будет произведен повторный звонок, в миллисекундах

2.1.2.8 Параметры объекта content для email

Название

Тип

Обязательность

Описание

1

subject

string

Нет

Тема письма.

2

text

string

Нет

Текст письма.

3

attached-files

array

Нет

Ассоциативный массив ссылок на прикрепленные файлы. Формат: Имя файла: файл. Файл может быть передан следующими способами:

-- В base64 не более 1 мб. Пример: YxuJsafH
-- HTTP(s) ссылка. Пример: http://domain.com/file.pdf
-- FTP ссылка. Пример:
ftp://login:pass@server/path.to.file.txt
-- Ссылка на локальный файл.
Пример: path://home/user/file.pdf

Передаваемое имя файла используется только если файл передан в base64. В остальных случаях переданное имя будет игнорироваться.

2.1.2.9 Параметры объекта content для ussd

Название

Тип

Обязательность

Описание

1

text

string

Нет

Текст сообщения.

2

menu

string

Нет

Название USSD-меню

2.1.2.10 Параметры элемента массива messages

Название

Тип

Обязательность

Описание

1

recipient

string

Нет

Адрес получателя (как правило MSISDN). Обязателен, если отправка идет по транспорту отличному Email, или по шаблону отличному от Email.

2

email-address

string

Нет

Email-адрес получателя. Обязателен, если отправка идет по транспорту Email, или по шаблону Email.

3

message-id

string

Да

Уникальный идентификатор сообщения для отправителя сообщения. Максимальная длина 30 символов.

4

template-id

string

Нет

Идентификатор шаблона для отправки сообщения

5

priority

string

Нет

Приоритет:
low - низкий,
normal - обычный,
high - высокий,
realtime - наивысший.

 Если не указан, то используется normal

6

timing

object

Нет

Временные настройки

7

variables

array

Нет

Объект параметров и их значений для подстановки в сообщение (каждый элемент представлен как запись

ПАРАМЕТР:ЗНАЧЕНИЕ, например, {"PARAM1":"VALUE1","PARAM2":"VALUE2"}).

8

viber

object

Нет

Параметры для отправки по каналу viber

9

sms

object

Нет

Параметры для отправки по каналу sms

10

push

object

Нет

Параметры для отправки по каналу push

11

call

object

Нет

Параметры для отправки по каналу call

12

email

object

Нет

Параметры для отправки по каналу email

13

ussd

object

Нет

Параметры для отправки по каналу ussd

Параметры объектов timing и объектов каналов аналогичны параметрам для общей части запроса.

2.1.3 Параметры ответа

При успешном запросе возвращается строка "OK".

2.2 Получить статусы сообщений

URL: http://stream.ibatelecom.ru:8083/broker-api/getStatus

Запрос используется для запроса статусов отправленных сообщений. Статус сообщения доступен не сразу, а только спустя несколько минут после отправки.

На запрос возвращаются только финальные статусы (с учетом возможности переотправки сообщения по другому каналу) или все статусы в зависимости от настроек аккаунта.

2.2.1 Тело запроса

{
	"message-id": []
}
JSON

2.2.2 Параметры запроса

Название

Тип

Обязательность

Описание

1

message-id

Array

Да

Массив идентификаторов сообщений

2.2.3 Тело ответа

{
"messages":
[
{
	"message-id": "",
"channel": "",
	"status": "",
"status-date": "",
	"description": ""
	}
]
}
CODE

2.2.4 Параметры ответа

Название

Тип

Обязательность

Описание

1

message-id

string

Да

Идентификатор сообщения

2

channel

string

Нет

Канал, по-которому было доставлено сообщение

3

status

string

Нет

Статус сообщения:
Transmitted - Отправлено
Delivered - Доставлено
NotDelivered - Не доставлено
Failed - Ошибка при отправке
Rejected - Отклонено системой
Read - Прочитано (только для Viber и Push)
Deferred - отправка сообщения отложена
Buffered - отправка сообщения отложена (только для Call)
Error - Ошибка при отправке (только для Call)
NotAnswered - Не отвечено (только для Call)
Finished - Завершено (только для Call)

4

status-date

datetime

Нет

Дата и время получения статуса

5

description

string

Нет

Описание причины недоставки сообщения,  ошибки, либо "Message not found"

2.3 Автоматическое получение статусов сообщений

На указанный в настройках Системы URL автоматически отправляются статусы отправленных сообщений. Запрос выполняется Системой в сторону системы-отправителя. Выполняется буферизация статусов в 1 секунду.

Системе-отправителю передаются только финальные статусы (с учетом возможности переотправки сообщения по другому каналу) или все статусы в зависимости от настроек аккаунта.

2.3.1 Тело запроса

{
"messages":
[
{
	"message-id": "",
"channel": "",
	"status": "",
"status-date": "",
	"description": ""
	}
]
}
JSON

2.3.2 Параметры запроса

Название

Тип

Обязательность

Описание

1

message-id

string

Да

Идентификатор сообщения

2

channel

string

Нет

Канал, по-которому было доставлено сообщение

3

status

string

Нет

Статус сообщения:
Transmitted - Отправлено
Delivered - Доставлено
NotDelivered - Не доставлено
Failed - Ошибка при отправке
Rejected - Отклонено системой
Read - Прочитано (только для Viber и Push)
Deferred - отправка сообщения отложена
Buffered - отправка сообщения отложена (только для Call)
Error - Ошибка при отправке (только для Call)
NotAnswered - Не отвечено (только для Call)
Finished - Завершено (только для Call)

4

status-date

datetime

Нет

Дата и время получения статуса

5

description

string

Нет

Описание причины недоставки сообщения,  ошибки, либо "Информация отсутствует"