Отправка TELEGRAM

Содержание

Отправка TELEGRAM#

Совет

Для получения возможности отправки TELEGARAM-сообщений необходимо:

Создать TELEGRAM-бота (инструкция)
Добавить TELEGRAM-бота в Личном кабинете i-Digital Direct (инструкция)
Попросить абонентов запустить бота и поделиться с ним номером телефона

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

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

POST https://direct.i-dgtl.ru/api/v1/message

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

Headers#

Name	Type	Description
Authorization*	string	`Basic {TOKEN_1}`
Content-Type*	string	`application/json`

Request Body#

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

200

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

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

401

Использование невалидного токена / отсутствие заголовка авторизации.

4012

{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}

4010

{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}

403

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

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

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)"
    }
}

402

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

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

Совет

Рекомендуемое время ожидания ответа: 70 секунд.
Как правило, ответ на запрос возвращается не более чем за несколько секунд, но таймаут величиной в 70 секунд позволяет гарантированно получить ответ на запрос, в том числе в ситуациях повышенной нагрузки.

Совет

Для использования личного домена в сокращенных ссылках необходимо обратиться в поддержку

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

Параметр	Варианты
callbackEvents	События для отправки callback

Текстовое сообщение #

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

Совет

Вы можете форматировать текст сообщения:

Для полужирного шрифта нужны две звездочки слева и справа от фрагмента. **text** → text
Для курсива понадобятся по два знака нижнего подчеркивания слева и справа. __text__ → text
Чтобы сделать текст моноширинным, оберните его в тройные апострофы. „““text“““→ text
Для переноса текста на новую строку используйте символ \n.

Сообщение с изображением #

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

Пример запроса #

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"
  }
]

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"}]'

Python

import requests
import json

url = "https://direct.i-dgtl.ru/api/v1/message"

payload = json.dumps([
  {
    "senderName": "i-digital_bot",
    "channelType": "TELEGRAM",
    "destination": "79999999999",
    "content": {
      "contentType": "text",
      "text": "Текст TELEGRAM-сообщения"
    }
  }
])
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify([
  {
    "senderName": "i-digital_bot",
    "channelType": "TELEGRAM",
    "destination": "79999999999",
    "content": {
      "contentType": "text",
      "text": "Текст TELEGRAM-сообщения"
    }
  }
]);

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://direct.i-dgtl.ru/api/v1/message", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "[\n  {\n    \"senderName\": \"i-digital_bot\",\n    \"channelType\": \"TELEGRAM\",\n    \"destination\": \"79999999999\",\n    \"content\": {\n      \"contentType\": \"text\",\n      \"text\": \"Текст TELEGRAM-сообщения\"\n    }\n  }\n]");
Request request = new Request.Builder()
  .url("https://direct.i-dgtl.ru/api/v1/message")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

PHP

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json'
];
$body = '[
  {
    "senderName": "i-digital_bot",
    "channelType": "TELEGRAM",
    "destination": "79999999999",
    "content": {
      "contentType": "text",
      "text": "Текст TELEGRAM-сообщения"
    }
  }
]';
$request = new Request('POST', 'https://direct.i-dgtl.ru/api/v1/message', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

Go

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://direct.i-dgtl.ru/api/v1/message"
  method := "POST"

  payload := strings.NewReader(`[
  {
    "senderName": "i-digital_bot",
    "channelType": "TELEGRAM",
    "destination": "79999999999",
    "content": {
      "contentType": "text",
      "text": "Текст TELEGRAM-сообщения"
    }
  }
]`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Совет

В примере указан минимальный набор параметров, который позволяет моментально отправить TELEGRAM-сообщение. Вы можете кастомизировать контент, время отправки, настроить коллбэки, добавить теги и внутренний идентификатор, используя опциональные параметры, описанные выше на данной странице.