Подключение бота помощью API

Graspil имеет разные способы подключение бота к системе. Здесь описан метод подключения с помощью API.

В личном кабинете, при подключении бота вы можете ознакомиться со всеми вариантами подключения.

В API существует два метода передачи данных в graspil:

1. Пакетная отправка данных — предпочтительный вариант

2. Отправка данных в момент получения

В данной статье под "данными" подразумевается набор обьектов

В graspil важно получить точное время получения вашим ботом (кодом), вплоть до миллисекунд. Поэтому мы рекомендуем использовать метод пакетной отправки данных

1. Вы можете передать точное время получения данных

2. Если вы сделаете отложенную передачу данных, например раз в минуту это положительно скажется на производительности всех систем.

Зачем нужна дата получения и в каких случаях важны миллисекунды

Дата получения объекта нужна просто потому что не все типы данных Update содержат дату.

Зачем миллисекунды?

Они важны в случае если вы так же передаете к в graspil. Системе важно правильно отсортировать список входящих, и исходящих сообщений и единственный способ сделать это использовать дату.

Часто получение и отправка сообщений происходит в рамках одной секунды, поэтому мы используем миллисекунды.

Авторизация

Graspil API ожидает, что ключ API будет включен во все запросы к API в заголовке, который выглядит следующим образом:

Name	Value
Api-Key	meowmeowmeow

Подробней про авторизацию и о том как получить ключ авторизации читайте в разделе про авторизацию

Проверка структуры Update

В обоих методах система ожидает получить которые полностью соответствуют структуре Telegram Bot API

Для ускорения работы, в момент получения данных система проверяет только базовые части данных. Полная проверка, в том числе на соответствие данных структуре Telegram Bot API происходит позднее. При возникновении ошибок они попадут в раздел "Ошибки бота"

Мы рекомендуем передавать данные в том виде в котором вы получили их от телегам. Если вы решили собирать update самостоятельно, то убедитесь что структура данных на 100% соответствует Telegram Bot Api, так же убедитесь что передаете все нужные данные в graspil, иначе это может исказить отчеты.

Примеры структуры updates есть в документации https://core.telegram.org/bots/webhooks#testing-your-bot-with-updates

Пакетная отправка данных

POST https://api.graspil.com/v1/send-batch-update

Метод для пакетной отправки Update. Можно передать до 1к update с указанием даты получения. Для отправки данных нужно отправить массив данных.

Headers

Name	Value
Content-Type	application/json
Api-Key	meowmeowmeow

Body

Параметр	Тип	Обязательный	Описание
date	RFC 3339 (ISO 8601)	Нет	Время получения ботом конкретного update. Если не передавать будет установленно текущее время. Формат времени должен содержать миллисекунды и часовой пояс. Пример: 2024-08-03T20:00:00.123+02:00
update	Объект Update	да	Один объект Update, данные которые вы получили от телеграм

Метод принимает до 1000 Update за один запрос

Пример тело запроса

[
    {
        "date": "2024-08-03T20:00:00.123+02:00", // дата и время получения данных
        "update": {
            "message": {
                "chat": {
                    "id": 123,
                    "type": "private",
                    "username": "Graspil",
                    "last_name": "Graspil",
                    "first_name": "Bot"
                },
                "date": 1718691840,
                "from": {
                    "id": 123,
                    "is_bot": false,
                    "username": "Graspil",
                    "last_name": "Graspil",
                    "first_name": "Bot"
                },
                "text": "Hi, how are you?",
                "message_id": 1000
            },
            "update_id": 22111111
        }
    },
    {
        "update": {
            "message": {
                "chat": {
                    "id": 123,
                    "type": "private",
                    "username": "Graspil",
                    "last_name": "Graspil",
                    "first_name": "Bot"
                },
                "date": 1718691840,
                "from": {
                    "id": 123,
                    "is_bot": false,
                    "username": "Graspil",
                    "last_name": "Graspil",
                    "first_name": "Bot"
                },
                "text": "Hi, how are you?",
                "message_id": 1000
            },
            "update_id": 22111112
        }
    }
]

Примеры кода

Python

import requests
import json

url = "https://api.graspil.com/v1/send-batch-update"
api_key = "< API KEY >"

payload = json.dumps([
  {
    "date": "2024-08-03T20:00:00.123+02:00",
    "update": {
        "message": {
            "chat": {
                "id": 123,
                "type": "private",
                "username": "Graspil",
                "last_name": "Graspil",
                "first_name": "Bot"
            },
            "date": 1718691840,
            "from": {
                "id": 123,
                "is_bot": false,
                "username": "Graspil",
                "last_name": "Graspil",
                "first_name": "Bot"
            },
            "text": "Hi, how are you?",
            "message_id": 1000
        },
        "update_id": 22111112
    }
  }
])
headers = {
  'Content-Type': 'application/json',
  'Api-Key': api_key,
}

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

print(response.text)

JS

var request = require('request');
var api_key = '< API KEY >'
var options = {
  'method': 'POST',
  'url': 'https://api.graspil.com/v1/send-batch-update',
  'headers': {
    'Content-Type': 'application/json',
    'Api-Key': api_key,
  },
  body: JSON.stringify([
    {
      "date": "2024-08-03T20:00:00.123+02:00",
      "update": {
        "message": {
          "chat": {
            "id": 123,
            "type": "private",
            "username": "Graspil",
            "last_name": "Graspil",
            "first_name": "Bot"
          },
          "date": 1718691840,
          "from": {
            "id": 123,
            "is_bot": false,
            "username": "Graspil",
            "last_name": "Graspil",
            "first_name": "Bot"
          },
          "text": "Hi, how are you?",
          "message_id": 1000
        },
        "update_id": 22111111
      }
    }
  ])

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

PHP

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.graspil.com/v1/send-batch-update',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'[
    {
        "date": "2024-08-03T20:00:00.123+02:00",
        "update": {
            "message": {
                "chat": {
                    "id": 123,
                    "type": "private",
                    "username": "Graspil",
                    "last_name": "Graspil",
                    "first_name": "Bot"
                },
                "date": 1718691840,
                "from": {
                    "id": 123,
                    "is_bot": false,
                    "username": "Graspil",
                    "last_name": "Graspil",
                    "first_name": "Bot"
                },
                "text": "Hi, how are you?",
                "message_id": 1000
            },
            "update_id": 22111112
        }
    }
]',
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Api-Key: ' . $api_key
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response

200

{
  "ok": true
}

400

{
  "ok": false,
  "error_code": 400,
  "description": "Too many updates. Max 1000"
}

401

{
  "ok": false,
  "error_code": 401,
  "description": "Unauthorized"
}

Отправка данных в момент получения

POST https://api.graspil.com/api/send-update

В момент когда вы получаете данные от Telegram Bot API вам необходимо отправить эти данные нашей платформе. Данные должны отправляться в неизменном виде, соответствующие структуре данных Telegram Bot API.

Для корректности работы системы, важно передавать данные в момент их получения. Либо использовать метод send-batch-update с добавлением даты получения, если вы отправляете данные позже

Данные получаемые от Telegram могут содержать две разных структуры, в зависимости от метода доставки обновлений webhook или getUpdate. Данный метод поддерживает обе этих структуры.

Headers

Name	Value
Content-Type	application/json
Api-Key	meowmeowmeow

Body

Пример тела запроса (тип бота webhook)

{
  "update_id": 123,
  "message":{
    "date": 1691489960,
    "chat":{...}, // <----- сокращение, содержит обьект Chat из TG API
    "message_id": 123,
    "from":{...}, // <----- сокращение, содержит обьект User из TG API
    "text":"/start"
  }
}

Пример тела запросы (тип бота getUpdates)

{
  "ok":true,
  "result":[
    {
      "update_id": 123,
      "message":{...} // <- сокращение, содержит обьект Message из TG AP
    },
    {
      "update_id": 124,
      "message":{...} // <- сокращение, содержит обьект Message из TG AP
    }
  ]
}

Примеры кода

Python

import requests

url = "https://api.graspil.com/v1/send-update"
api_key = ""  # your API key
data = {}  # received data from telegram

headers = {
    "Api-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(url, json=data, headers=headers)

# Response processing
print(response.text)

PHP

$url = "https://api.graspil.com/v1/send-update";
$api_key = ""; // your API key
//$data - received data from telegram for sending

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Api-Key: ' . $api_key,
    'Content-Type: application/json;'
)];
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

Response

200

{
  "ok": true
}

400

{
  "ok": false,
  "error_code": 400,
  "description": "Wrong json"
}

401

{
  "ok": false,
  "error_code": 401,
  "description": "Unauthorized"
}

Разработчикам

Разработайте SDK на вашем языке программирования для подключения graspil. Опубликуйте этот репозиторий на GitHub и напишите нам на [e-mail].

Мы добавим ссылку на ваш репозиторий в документацию что привлечет дополнительных посетителей на вашу страницу. Так же мы можем предоставить бесплатный доступ на несколько месяцев к премиум тарифу и ранний доступ к реферальной программе.