# Введение в API Callback

С помощью TGStat API Callback вы можете получать в режиме реального времени уведомления о различных событиях в Telegram-каналах и чатах на заданный вами URL посредством программного интерфейса API.

# Как начать?

1. Активируйте нужный тарифный план в Личном кабинете или на этой странице.

2. Получите персональный токен в своем Личном кабинете.

3. Установите Callback URL, на который хотите получать уведомления с помощью метода callback/set-callback-url.

Проверить, что Callback URL установлен корректно можно с помощью метода callback/get-callback-info.

4. Подпишитесь на необходимые события с помощью методов "Подписка на канал" и "Подписка на ключевое слово".

5. Начинайте получать вебхуки на свой Callback URL.

# Пример кода на языке PHP для получения уведомлений от TGStat API Callback

<?php

$json = file_get_contents('php://input');
$dataArray = json_decode($json, true);

file_put_contents("callback.log", print_r($dataArray, true) . "\n\n", FILE_APPEND);

Структуры объектов, которые будут отправляться на Callback URL в результате наступления событий подробно описаны на странице "Объекты уведомлений API Callback".

# Доступные для подписки типы событий:

• новая публикация в Telegram-канале;
• редактирование/удаление публикации;
• новое сообщение в Telegram-чате;
• новая публикация с заданным ключевым словом/фразой во всех Telegram-каналах;
• новое сообщение с заданным ключевым словом/фразой во всех Telegram-чатах.

# Доставка событий на Callback URL

Сразу при наступлении события, на которое вы подписаны, робот сервиса TGStat отправит на указанный вами Callback URL объект с полными данными о наступившем событии.

Данные отправляются методом POST.

Нашего робота зовут TGStat Webhook Bot. Данное имя вы можете увидеть в access-логах вашего веб-сервера в поле User-Agent.

Фактом подтверждения успешной доставки сообщения является любой из кодов ответа с префиксом 20x от вашего веб-сервера. В случае получения кода ответа, отличного от успешного – робот будет предпринимать попытки повторной отправки (с паузами в 3 секунды) до тех пор, пока не получит успешный код ответа.

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

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

За состоянием очереди сообщений и возникающих ошибках можно следить с помощью метода callback/get-callback-info.

# Задержки при доставке

TGStat узнаёт о наступлении событий в Telegram-каналах и чатах моментально. С учетом внутреннего процессинга и индексации полученных данных, средняя задержка между наступлением события в Telegram и доставкой нашим роботом на ваш Callback URL составляет примерно 2-3 секунды.

Каждую минуту TGStat обрабатывает около 100,000 событий от Telegram, а в сутки индексирует более 20,000,000 новых публикаций от более чем 800,000 Telegram-каналов и чатов.

# Тарификация

Услуга доступа к API Callback тарифицируется по количеству объектов (каналов или ключевых слов/фраз), на которые вы подписаны. Актуальные сведения о тарифах и ограничениях можно получить на странице Тарифы. Отслеживать расходование квоты по вашему пакету услуг можно с помощью метода usage/stat.

# Вопросы и предложения

Если у вас возникли технические вопросы при работе с API, вопросы по стоимости услуг, или у вас имеются предложения по улучшению сервиса – пишите в Support.