# Отправка TELEGRAM

{% hint style="info" %}
Для получения возможности отправки TELEGARAM-сообщений необходимо:

1. Создать TELEGRAM-бота ([инструкция](https://faq.docs.direct.i-dgtl.ru/kanaly-otpravki/messendzhery-i-soc.-seti/telegram/bot-1.0-sozdaite-novyi-kanal-obsheniya-s-klientami-v-telegram#sozdanie-chat-bota-v-telegram))
2. Добавить TELEGRAM-бота в [Личном кабинете](https://direct.i-dgtl.ru/settings/telegram) i-Digital Direct ([инструкция](https://faq.docs.direct.i-dgtl.ru/kanaly-otpravki/messendzhery-i-soc.-seti/telegram/bot-1.0-sozdaite-novyi-kanal-obsheniya-s-klientami-v-telegram#podklyuchenie-telegram-chat-bota-v-lichnom-kabinete-i-digital-direct))
3. Попросить абонентов запустить бота и поделиться с ним номером телефона

После этого вы сможете отправлять TELEGRAM-сообщения всем абонентам, кто поделился номером телефона с вашим ботом.
{% endhint %}

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

<mark style="color:green;">`POST`</mark> `https://direct.i-dgtl.ru/api/v1/message`

Метод позволяет отправлять массив одиночных сообщений **(от 1 до 1000)**

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | `Basic {TOKEN_1}`  |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json` |

#### Request Body

| Name                                          | Type    | Description                                                                                                                                                                                                                                                                                              |
| --------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| channelType<mark style="color:red;">\*</mark> | string  | Канал отправки (`TELEGRAM`)                                                                                                                                                                                                                                                                              |
| senderName<mark style="color:red;">\*</mark>  | string  | Имя отправителя. Допускаются имена ботов, добавленных в ЛК Direct                                                                                                                                                                                                                                        |
| destination<mark style="color:red;">\*</mark> | string  | Номер абонента                                                                                                                                                                                                                                                                                           |
| content<mark style="color:red;">\*</mark>     | object  | Контент сообщения. Ниже описаны возможные варианты содержимого.                                                                                                                                                                                                                                          |
| tags                                          | array   | Теги сообщения (массив строк). Каждый тег должен соответствовать выражению `^\w+$` (допускаются буквы в любом регистре, цифры и нижнее подчеркивание "\_")                                                                                                                                               |
| useLocalTime                                  | boolean | <p>Флаг, отвечающий за таймзону, в которой будет отправлено сообщение:<br><strong><code>true</code></strong> – отправка в таймзоне абонента<br><strong><code>false</code></strong> – отправка по МСК<br><em>По умолчанию true</em></p>                                                                   |
| localSendTime                                 | string  | <p>Нижняя граница допустимого времени отправки сообщения (с учетом значения<code>useLocalTime</code>)<br>Дата в формате <code>YYYY-MM-DD hh:mm:ss</code> в диапазоне от (текущее время в UTC - 12 часов) до (текущее время в UTC + 7 дней)<br><em>По умолчанию сообщение будет отправлено сразу</em></p> |
| localCompletionTime                           | string  | Верхняя граница допустимого времени отправки сообщения (с учетом `useLocalTime`) в диапазоне от `localSendTime` до (текущее время в UTC + 70 дней)                                                                                                                                                       |
| ttl                                           | integer | <p>Время жизни сообщения в секундах. По истечении ttl сообщению устанавливается финальный статус.<br><code>60 ≤ ttl ≤ 86400</code></p>                                                                                                                                                                   |
| hours                                         | array   | Допустимые часы отправки (массив чисел). В массиве могут быть переданы целые числа от 0 до 23, каждое из которых соответствует разрешенному для отправки интервалу с учетом `useLocalTime`; значения должны быть уникальны.                                                                              |
| days                                          | array   | Допустимые дни отправки (массив чисел). В массиве могут быть переданы целые числа от 1 (пн) до 7 (вс), каждое из которых соответствует разрешенному для отправки дню недели; значения должны быть уникальны.                                                                                             |
| shortUrl                                      | boolean | <p>Флаг, отвечающий за сокращение ссылок в сообщении:<br><code>true</code> - ссылки в тексте сообщения и кнопках будут сокращены<br>По умолчанию false</p>                                                                                                                                               |
| callbackUrl                                   | string  | Адрес для отправки callback                                                                                                                                                                                                                                                                              |
| callbackEvents                                | array   | События, по которым будут отправлены callback (массив строк). При наличии `callbackUrl` и отсутствии `callbackEvents` в запросе, будет отправлен callback по событию `delivered`.                                                                                                                        |
| externalMessageId                             | string  | Внутренний id сообщения в вашей системе. До 100 символов.                                                                                                                                                                                                                                                |

::::::{tab-set}

:::::{tab-item} 200

В случае успешного запроса возвращается ответ, в котором перечислены идентификаторы сообщений и коды результата. При значении errors = false гарантируется, что все переданные сообщения успешно созданы.

```
{
  "errors": false,
  "items": [
    {
      "messageUuid": "063474ec-a34f-4558-90c5-984395000004",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}
```
:::::


:::::{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} 403

Использование неподходящего токена.

```
{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}
```
:::::


:::::{tab-item} 422

Невалидные параметры в теле запроса; ниже приведены несколько примеров ответа.

```
{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid text length in viber content (0)"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid caption length in viber content (3)"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid caption length in viber content (3)"
    }
}
```
:::::


:::::{tab-item} 402

Payment Required. Недостаточно средств на балансе.

```javascript
{
    "error": {
        "code": 402,
        "msg": "Insufficient funds"
    }
}
```
:::::

::::::


{% hint style="warning" %}
Рекомендуемое время ожидания ответа: 70 секунд.\
Как правило, ответ на запрос возвращается не более чем за несколько секунд, но таймаут величиной в 70 секунд позволяет гарантированно получить ответ на запрос, в том числе в ситуациях повышенной нагрузки.
{% endhint %}

{% hint style="info" %}
Для использования личного домена в сокращенных ссылках необходимо обратиться в поддержку
{% endhint %}

Возможные варианты перечислений:

| Параметр       | Варианты                                                              |
| -------------- | --------------------------------------------------------------------- |
| callbackEvents | [События для отправки callback](../extra/references/#callback-events) |

## Текстовое сообщение <a href="#text" id="text"></a>

Текстовое TELEGRAM-сообщение, помимо текста, может содержать кнопки с ссылками

Для отправки текстового TELEGRAM-сообщения используется следующий объект `content`:

```
{
  "contentType": "text",
  "text": "Текст TELEGRAM-сообщения",
  "inlineKeyboard": [
    [
      {
        "text": "текст кнопки 1",
        "url": "https://i-dgtl.ru/1"
      },
      {
        "text": "текст кнопки 2",
        "url": "https://i-dgtl.ru/2"
      }
    ],
    [
      {
        "text": "текст кнопки 3",
        "url": "https://i-dgtl.ru/3"
      },
      {
        "text": "текст кнопки 4",
        "url": "https://i-dgtl.ru/4"
      }
    ]
  ]
}
```

| Параметр            | Тип                                        | Описание                                                                                                                                                                                                        |
| ------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contentType         | <p>string</p><p><em>required</em></p>      | Тип контента (`text`)                                                                                                                                                                                           |
| text                | <p>string</p><p><em>required</em></p>      | <p>Текст сообщения; строка в кодировке UTF-8 без Byte Order Mark</p><p>От 1 до 4096 символов</p>                                                                                                                |
| inlineKeyboard      | <p>array (arrays)<br><em>optional</em></p> | <p>Массив с массивами объектов кнопок<br>Каждый вложенный массив является отдельной строкой из кнопок.<br>Допускается отправка не более чем 10 вложенных массивов, в каждом из которых не более 10 объектов</p> |
| inlineKeyboard.text | <p>string<br><em>optonal</em></p>          | Текст кнопки; от 1 до 50 символов                                                                                                                                                                               |
| inlineKeyboard.url  | <p>string<br><em>optional</em></p>         | Ссылка, на которую происходит переход при нажатии на кнопку; от 1 до 1000 символов                                                                                                                              |

{% hint style="info" %}
Вы можете форматировать текст сообщения:

* Для полужирного шрифта нужны две звездочки слева и справа от фрагмента. \*\*text\*\* → **text**
* Для курсива понадобятся по два знака нижнего подчеркивания слева и справа. \_\_text\_\_ → _text_
* Чтобы сделать текст моноширинным, оберните его в тройные апострофы. '''text'''→ `text`
* Для переноса текста на новую строку используйте символ `\n`.
{% endhint %}

## Сообщение с изображением <a href="#image" id="image"></a>

Для отправки TELEGRAM-сообщения с изображением используется следующий объект `content`:

```
{
  "contentType": "image",
  "imageUrl": "https://image.png",
  "caption": "Подпись к изображению",
  "inlineKeyboard": [
    [
      {
        "text": "текст кнопки 1",
        "url": "https://i-dgtl.ru/1"
      },
      {
        "text": "текст кнопки 2",
        "url": "https://i-dgtl.ru/2"
      }
    ],
    [
      {
        "text": "текст кнопки 3",
        "url": "https://i-dgtl.ru/3"
      },
      {
        "text": "текст кнопки 4",
        "url": "https://i-dgtl.ru/4"
      }
    ]
  ]
}
```



| Параметр            | Тип                                        | Описание                                                                                                                                                                                                        |
| ------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contentType         | <p>string</p><p><em>required</em></p>      | Тип контента (`image`)                                                                                                                                                                                          |
| imageUrl            | <p>string</p><p><em>required</em></p>      | Ссылка на изображение                                                                                                                                                                                           |
| caption             | <p>string<br><em>optional</em></p>         | Подпись к изображению; до 1024 символов                                                                                                                                                                         |
| inlineKeyboard      | <p>array (arrays)<br><em>optional</em></p> | <p>Массив с массивами объектов кнопок<br>Каждый вложенный массив является отдельной строкой из кнопок.<br>Допускается отправка не более чем 10 вложенных массивов, в каждом из которых не более 10 объектов</p> |
| inlineKeyboard.text | <p>string<br><em>optonal</em></p>          | Текст кнопки; от 1 до 50 символов                                                                                                                                                                               |
| inlineKeyboard.url  | <p>string<br><em>optional</em></p>         | Ссылка, на которую происходит переход при нажатии на кнопку; от 1 до 1000 символов                                                                                                                              |

## Пример запроса <a href="#example" id="example"></a>

::::::{tab-set}

:::::{tab-item} JSON

```
POST https://direct.i-dgtl.ru/api/v1/message
Authorization: Basic QWxhZGRpbjpvc...
Content-Type: application/json
[
  {
    "senderName": "i-digital_bot",
    "channelType": "TELEGRAM",
    "content": {
      "contentType": "text",
      "text": "Текст TELEGRAM-сообщения"
    },
    "destination": "79999999999"
  }
]
```
:::::


:::::{tab-item} cURL

```
curl -X POST 'https://direct.i-dgtl.ru/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvc...' \
-d '[{"senderName":"i-digital_bot","channelType":"TELEGRAM","content":{"contentType":"text","text":"Текст TELEGRAM-сообщения"},"destination":"79999999999"}]'
```
:::::

::::::


{% hint style="info" %}
В примере указан минимальный набор параметров, который позволяет моментально отправить TELEGRAM-сообщение. Вы можете кастомизировать контент, время отправки, настроить коллбэки, добавить теги и внутренний идентификатор, используя опциональные параметры, описанные выше на данной странице.&#x20;
{% endhint %}