# Получение массива сообщений
## Получение массива сообщений
`GET` `https://direct.i-dgtl.ru/api/v1/message`
Метод позволяет получить массив объектов сообщений, подходящих под условие параметров фильтрации.
#### Query Parameters
| Name | Type | Description |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page | integer | Запрашиваемая страница
По умолчанию 1
|
| per\_page | integer | Количество сообщений на странице
По умолчанию 100
Должно выполняться ограничение:
page * perPage <= 10000
|
| sort | string | Сортировка |
| time\_from | string | Нижняя граница времени отправки в UTC (либо получения финального статуса unsent)
Пример значения:
2020-01-01T00:00:00Z
|
| time\_to | string | Верхняя граница времени отправки в UTC (либо получения финального статуса `unsent`) |
| dispatch\_id | integer | Идентификатор рассылки
Множественный параметр
|
| message\_uuid | string | Идентификатор сообщения
Параметр можно использовать для фильтрации по message_uuid, а также по external_message_id
Множественный параметр
|
| destination | string | Номер абонента
Множественный параметр
|
| status | string | Статус сообщения
Множественный параметр
|
| traffic\_center\_id | integer | Идентификатор центра разделения трафика
Множественный параметр
|
| tags | string | Тег сообщений
Множественный параметр
|
| sending\_method | string | Способ отправки сообщений
Множественный параметр
|
| channel\_type | string | Канал отправки
Множественный параметр
|
| traffic\_type | string | Тип трафика
Множественный параметр
|
| template\_id | string | Идентификатор шаблона
Множественный параметр
|
| flashcall\_conversion | string | Результат отправки FlashCall
Множественный параметр
|
| content | string | Строка, которую содержит текст сообщения |
| content\_nor | string | Строка, которую не содержит текст сообщения |
| sender\_name | string | Имя отправителя
Множественный параметр
|
| cascade\_message\_uuid | string | Идентификатор корневого каскадного сообщения |
| root | boolean | true- возвращаются только некаскадные и каскадные сообщения первого шага
false- возвращаются только каскадные сообщения, начиная со второго шага
По умолчанию null
|
| ready\_to\_stop | boolean | `true` - возвращаются только те сообщения, для которых можно выполнить команду /stop (см. [Остановка сообщений](stopping.md)) |
| country\_code | string | Двухбуквенный код страны абонента в соответствии с [ISO-3166](https://www.iso.org/iso-3166-country-codes.html) |
| direction | string | Направление сообщения; по умолчанию outbound
Множественный параметр
|
| dispatch | booean | true - возвращаются только сообщения рассылок
false - возвращаются только одиночные сообщения
Применимо только для outbound-сообщений
|
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ----------------- |
| Authorization\* | string | `Basic {TOKEN_1}` |
::::::{tab-set}
:::::{tab-item} 200
```
{
"page": 1,
"perPage": 1,
"total": 100,
"items": [
{
... // объект сообщения
}
]
}
```
:::::
:::::{tab-item} 400
Отсутствие обязательных параметров.
```
{
"error": {
"code": 4000,
"msg": "Required Instant parameter 'time_from' is not present: null"
}
}
```
:::::
:::::{tab-item} 401
Использование невалидного токена / отсутствие заголовка авторизации.
::::{tab-set}
:::{tab-item} 4012
```
{
"error": {
"code": 4012,
"msg": "Bad credentials"
}
}
```
:::
:::{tab-item} 4010
```
{
"error": {
"code": 4010,
"msg": "Not Authenticated"
}
}
```
:::
::::
:::::
:::::{tab-item} 404
Not Found. Сообщение по данному message\_uuid не найдено.
```javascript
{
"error": {
"code": 404,
"msg": "Msg not found"
}
}
```
:::::
::::::
{% hint style="warning" %}
Данный метод позволяет получить не более 10 000 сообщений из одной выборки. Т.е. независимо от значения `total` в ответе, постраничный переход возможен до тех пор, пока не превышено количество 10 000 сообщений.
При необходимости выгрузки большего количества сообщений вы можете воспользоваться:
* экспортом одиночных сообщений в ЛК: [https://direct.i-dgtl.ru/reports/messages](https://direct.i-dgtl.ru/reports/messages)
* экспортом сообщений рассылок в ЛК: [https://direct.i-dgtl.ru/base-dispatch-list](https://direct.i-dgtl.ru/base-dispatch-list?tab=scheduled)
{% endhint %}
{% hint style="warning" %}
При запросе сообщения по message\_uuid непосредственно после отправки в течение 10 секунд может возвращаться ошибка 404.
{% endhint %}
{% hint style="info" %}
Для возможности получения входящих сообщений необходимо обратиться к менеджеру.
{% endhint %}
Возможные варианты перечислений:
| Параметр | Варианты |
| --------------------- | --------------------------------------------------------------------- |
| sort | - sentTime:asc
- sentTime:desc
|
| status | [Статусы сообщений](../extra/references/#message-states) |
| sending\_method | [Способы отправки сообщений](../extra/references/#sending-methods) |
| channel\_type | [Каналы отправки сообщений](../extra/references/#channel-types) |
| traffic\_type | [Типы трафика](../extra/references/#traffic-types) |
| direction | [Направления сообщений](../extra/references/#directions) |
| flashcall\_conversion | [Результат отправки FlashCall](../extra/references/#flashcall-result) |
## Описание объекта ответа
| Параметр | Тип | Описание |
| -------- | ------- | --------------------------------------------------------------------- |
| page | integer | Номер запрошенной страницы |
| perPage | integer | Количество записей на странице |
| total | integer | Общее количество найденных записей, подходящих под условия фильтрации |
| items | array | Массив объектов сообщений (описано ниже) |
## Пример запроса
Позволяет получить сообщения рассылок 1 и 2 в статусах delivered и undelivered, которым был установлен данный статус в интервале с 2020-11-01 21:00:00 UTC до 2020-11-02 21:00:00 UTC
::::::{tab-set}
:::::{tab-item} JSON
```
GET https://direct.i-dgtl.ru/api/v1/message?time_from=2020-11-01T21:00:00Z&time_to=2020-11-02T21:00:00Z&dispatch_id=1&dispatch_id=2&status=delivered&status=undelivered
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
```
:::::
:::::{tab-item} cURL
```
curl -X GET 'https://direct.i-dgtl.ru/api/v1/message?time_from=2020-11-01T21:00:00Z&time_to=2020-11-02T21:00:00Z&dispatch_id=1&dispatch_id=2&status=delivered&status=undelivered' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
```
:::::
::::::
## Получение сообщения по uuid
`GET` `https://direct.i-dgtl.ru/api/v1/message/{message_uuid}`
Метод позволяет получить сообщение по messageUuid
#### Path Parameters
| Name | Type | Description |
| ----------------------------------------------- | ------ | ----------------------- |
| message\_uuid\* | string | Идентификатор сообщения |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ----------------- |
| Authorization\* | string | `Basic {TOKEN_1}` |
::::::{tab-set}
:::::{tab-item} 200 В ответе возвращается объект запрашиваемого сообщения
```
{
"createdTime": "2020-01-01T08:00:00Z",
"channelType": "SMS",
"sendingMethog": "UI",
"trafficType": "SERVICE",
"templateId": 120,
"dispatchId": 123,
"dispatchName": "рассылка 1",
"messageUuid": "9d213ffc-c388-46f5-b42b-01d589d1a815",
"trafficCenterId": 1,
"senderName": "testSender",
"destination": "79818282828",
"brand": "Мобильные ТелеСистемы ПАО",
"country": "Россия",
"region": "Республика Калмыкия",
"content": "текст сообщения",
"tags": [
"tag1",
"tag2"
],
"ttl": 86400,
"hours": [
10,
11,
12
],
"days": [
5,
6
],
"localSendTime": "2021-02-02 15:00:00",
"localCompletionTime": "2021-02-10 15:00:00",
"useLocalTime": true,
"callbackEvents": [
"sent",
"delivered"
],
"callbackUrl": "https://url-for-callbacks",
"totalParts": 1,
"price": {
"totalPrice": 2.5,
"currency": "RUB",
"invoicedParts": 1,
"final": false
},
"sentTime": "2020-01-01T09:00:00Z",
"statusTime": "2020-01-01T10:00:00Z",
"status": "undelivered",
"cascadeMessageUuid": "9d213ffc-c388-46f5-b42b-01d589d1a814",
"cascadeStep": 1,
"errorCode": 7060
}
```
:::::
:::::{tab-item} 401 Использование невалидного токена
```
{
"error": {
"code": 4012,
"msg": "Bad credentials"
}
}
```
:::::
:::::{tab-item} 403 Использование неподходящего токена
```
{
"error": {
"code": 4030,
"msg": "Access Denied"
}
}
```
:::::
:::::{tab-item} 404: Not Found Сообщение не найдено
```javascript
{
"error": {
"code": 404,
"msg": "Msg not found"
}
}
```
:::::
::::::
{% hint style="warning" %}
При запросе сообщения по message\_uuid непосредственно после отправки в течение 10 секунд может возвращаться ошибка 404.
{% endhint %}
## Описание объекта сообщения
| Параметр | Тип | Описание |
| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| createdTime | string | Время создания сообщения (в UTC) |
| channelType | string | [Канал трафика](../extra/references/#channel-types) |
| sendingMethod | string | [Способ отправки сообщения](../extra/references/#sending-methods) |
| trafficType | string | [Тип трафика](../extra/references/#traffic-types) |
| templateId | integer | Идентификатор шаблона (возможен для сервисных и транзакционных сообщений) |
| dispatchId | integer | Идентификатор рассылки (-1 для одиночных сообщений) |
| messageUuid | string | Идентификатор сообщения |
| externalMessageId | string | Внутренний идентификатор сообщения в вашей системе (возвращается если был передан при отправке) |
| trafficCenterId | integer | Идентификатор ЦРТ |
| senderName | string | Имя отправителя |
| destination | string | Номер абонента |
| direction | string | Направление сообщения
Параметр может отсутствовать для исходящих сообщений
|
| brand | string | Оператор абонента |
| country | string | Страна абонента |
| region | string | Регион абонента |
| content | string | Текст сообщения |
| tags | array | Массив тегов (при наличии) |
| ttl | integer | Время жизни сообщения в секундах |
| hours | array (integer) | Допустимые часы отправки |
| days | array (integer) | Допустимые дни отправки |
| localSendTime | string | Нижняя граница допустимого времени отправки сообщения |
| localCompletionTime | string | Верхняя граница допустимого времени отправки сообщения |
| useLocalTime | boolean | Учет местного времени абонента для localSendTime, localCompletionTime, hours, days |
| callbackEvents | string | [События для отправки callback](../extra/references/#callback-events) |
| callbackUrl | string | Адрес для отправки callback |
| totalParts | integer | Количество частей в сообщении |
| price.totalPrice | number | Стоимость сообщения |
| price.currency | string | Валюта сообщения |
| price.invoicedParts | integer | Количество тарифицированных частей |
| price.final | boolean | Цена является окончательной (true) / предварительной (false) |
| sentTime | string | Время отправки сообщения (в UTC) |
| status | string | [Статус сообщения](../extra/references/#message-states) |
| statusTime | string | Время получения статуса (в UTC), статус появляется после финализации сообщения |
| readStatus | string | [Статус прочтения](../extra/references/#message-read-states) |
| readStatusTime | string | Время получения статуса прочтения (в UTC) |
| specialContent | object | Содержимое сообщения |
| specialContent.contentType | string | [Тип содержимого сообщения](../extra/references/#message-content-types) |
| specialContent.text | string | Текст сообщения |
| specialContent.caption | string | Текст кнопки |
| specialContent.action | string | Действие кнопки |
| specialContent.imageUrl | string | Ссылка на изображение |
| errorCode | integer | [Код ошибки сообщения](../extra/references/error-codes.md) |
| flashcallConversion | string | [Результат отправки FlashCall](../extra/references/#flashcall-result) |
| cascadeMessageUuid | string | Идентификатор корневого сообщения каскада |
| cascadeStep | integer | Номер шага в каскаде |