# Получение массива сообщений
## Получение массива сообщений
`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 (см. [Остановка сообщений](/messages/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}` |
{% tabs %}
{% tab title="200 " %}
```
{
"page": 1,
"perPage": 1,
"total": 100,
"items": [
{
... // объект сообщения
}
]
}
```
{% endtab %}
{% tab title="400" %}
Отсутствие обязательных параметров.
```
{
"error": {
"code": 4000,
"msg": "Required Instant parameter 'time_from' is not present: null"
}
}
```
{% endtab %}
{% tab title="401" %}
Использование невалидного токена / отсутствие заголовка авторизации.
{% tabs %}
{% tab title="4012" %}
```
{
"error": {
"code": 4012,
"msg": "Bad credentials"
}
}
```
{% endtab %}
{% tab title="4010" %}
```
{
"error": {
"code": 4010,
"msg": "Not Authenticated"
}
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="404" %}
Not Found. Сообщение по данному message\_uuid не найдено.
```javascript
{
"error": {
"code": 404,
"msg": "Msg not found"
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
Данный метод позволяет получить не более 10 000 сообщений из одной выборки. Т.е. независимо от значения `total` в ответе, постраничный переход возможен до тех пор, пока не превышено количество 10 000 сообщений.
При необходимости выгрузки большего количества сообщений вы можете воспользоваться:
* экспортом одиночных сообщений в ЛК:
* экспортом сообщений рассылок в ЛК: [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.md#message-states) |
| sending\_method | [Способы отправки сообщений](/extra/references.md#sending-methods) |
| channel\_type | [Каналы отправки сообщений](/extra/references.md#channel-types) |
| traffic\_type | [Типы трафика](/extra/references.md#traffic-types) |
| direction | [Направления сообщений](/extra/references.md#directions) |
| flashcall\_conversion | [Результат отправки FlashCall](/extra/references.md#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
{% tabs %}
{% tab title="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==
```
{% endtab %}
{% tab title="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=='
```
{% endtab %}
{% endtabs %}
## Получение сообщения по 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}` |
{% tabs %}
{% tab title="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
}
```
{% endtab %}
{% tab title="401 Использование невалидного токена" %}
```
{
"error": {
"code": 4012,
"msg": "Bad credentials"
}
}
```
{% endtab %}
{% tab title="403 Использование неподходящего токена" %}
```
{
"error": {
"code": 4030,
"msg": "Access Denied"
}
}
```
{% endtab %}
{% tab title="404: Not Found Сообщение не найдено" %}
```javascript
{
"error": {
"code": 404,
"msg": "Msg not found"
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
При запросе сообщения по message\_uuid непосредственно после отправки в течение 10 секунд может возвращаться ошибка 404.
{% endhint %}
## Описание объекта сообщения
| Параметр | Тип | Описание |
| -------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| createdTime | string | Время создания сообщения (в UTC) |
| channelType | string | [Канал трафика](/extra/references.md#channel-types) |
| sendingMethod | string | [Способ отправки сообщения](/extra/references.md#sending-methods) |
| trafficType | string | [Тип трафика](/extra/references.md#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.md#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.md#message-states) |
| statusTime | string | Время получения статуса (в UTC), статус появляется после финализации сообщения |
| readStatus | string | [Статус прочтения](/extra/references.md#message-read-states) |
| readStatusTime | string | Время получения статуса прочтения (в UTC) |
| specialContent | object | Содержимое сообщения |
| specialContent.contentType | string | [Тип содержимого сообщения](/extra/references.md#message-content-types) |
| specialContent.text | string | Текст сообщения |
| specialContent.caption | string | Текст кнопки |
| specialContent.action | string | Действие кнопки |
| specialContent.imageUrl | string | Ссылка на изображение |
| errorCode | integer | [Код ошибки сообщения](/extra/error-codes.md) |
| flashcallConversion | string | [Результат отправки FlashCall](/extra/references.md#flashcall-result) |
| cascadeMessageUuid | string | Идентификатор корневого сообщения каскада |
| cascadeStep | integer | Номер шага в каскаде |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://api.docs.direct.i-dgtl.ru/messages/get-1.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.