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

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

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

1. [Пакетная отправка данных](#paketnaya-otpravka-dannykh) — предпочтительный вариант
2. [Отправка данных в момент получения](#otpravka-dannykh-v-moment-polucheniya)

{% hint style="info" %}
В данной статье под "данными" подразумевается набор обьектов Update[^1]
{% endhint %}

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

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

<details>

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

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

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

Они важны в случае если вы так же передаете [исходящий трафи](#user-content-fn-2)[^2]к в graspil. Системе важно правильно отсортировать список входящих, и исходящих сообщений и единственный способ сделать это использовать дату.&#x20;

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

</details>

### Авторизация

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

<table><thead><tr><th width="376">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>Api-Key</code></td><td><code>meowmeowmeow</code></td></tr></tbody></table>

Подробней про авторизацию и о том как получить ключ авторизации читайте в [разделе про авторизацию](https://docs.graspil.com/ru/api/auth)

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

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

Для ускорения работы, в момент получения данных система проверяет только базовые части данных. Полная проверка, в том числе на соответствие данных структуре Telegram Bot API происходит позднее. При возникновении ошибок они попадут в раздел "[Ошибки бота](https://app.graspil.com/bot_errors)"&#x20;

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

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

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

<mark style="color:green;">`POST`</mark> `https://api.graspil.com/v1/send-batch-update`

Метод для пакетной отправки [Update](https://core.telegram.org/bots/api#update). Можно передать до 1к update с указанием даты получения. Для отправки данных нужно отправить массив данных.

**Headers**

<table><thead><tr><th width="376">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr><tr><td>Api-Key</td><td><code>meowmeowmeow</code></td></tr></tbody></table>

**Body**

<table><thead><tr><th width="128">Параметр</th><th width="123">Тип</th><th width="147">Обязательный</th><th>Описание</th></tr></thead><tbody><tr><td>date</td><td>RFC 3339 (<a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a>)</td><td>Нет</td><td><p>Время получения ботом конкретного update. Если не передавать будет установленно текущее время. </p><p>Формат времени должен содержать миллисекунды и часовой пояс.<br>Пример: <code>2024-08-03T20:00:00.123+02:00</code></p></td></tr><tr><td>update</td><td>Объект <a href="https://core.telegram.org/bots/api#update">Update</a></td><td>да</td><td>Один объект <a href="https://core.telegram.org/bots/api#update">Update</a>, данные которые вы получили от телеграм</td></tr></tbody></table>

{% hint style="danger" %}
Метод принимает до 1000 [Update](https://core.telegram.org/bots/api#update) за один запрос
{% endhint %}

<details>

<summary>Пример тело запроса</summary>

{% code overflow="wrap" lineNumbers="true" %}

```json
[
    {
        "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
        }
    }
]
```

{% endcode %}

</details>

#### Примеры кода

<details>

<summary>Python</summary>

{% code overflow="wrap" lineNumbers="true" %}

```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)

```

{% endcode %}

</details>

<details>

<summary>JS</summary>

{% code overflow="wrap" lineNumbers="true" %}

```javascript
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);
});

```

{% endcode %}

</details>

<details>

<summary>PHP</summary>

{% code overflow="wrap" lineNumbers="true" %}

```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;
```

{% endcode %}

</details>

**Response**

{% tabs %}
{% tab title="200" %}
{% code overflow="wrap" lineNumbers="true" %}

```json
{
  "ok": true
}
```

{% endcode %}
{% endtab %}

{% tab title="400" %}
{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="401" %}
{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`POST`</mark> `https://api.graspil.com/api/send-update`

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

{% hint style="warning" %}
Для корректности работы системы, важно передавать данные в момент их получения. Либо использовать метод [send-batch-update](#send-batch-update) с добавлением даты получения, если вы отправляете данные позже
{% endhint %}

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

**Headers**

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

**Body**

<details>

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

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

</details>

<details>

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

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

</details>

#### Примеры кода

<details>

<summary>Python</summary>

{% code overflow="wrap" lineNumbers="true" %}

```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)
```

{% endcode %}

</details>

<details>

<summary>PHP</summary>

{% code overflow="wrap" lineNumbers="true" %}

```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);
```

{% endcode %}

</details>

**Response**

{% tabs %}
{% tab title="200" %}
{% code overflow="wrap" lineNumbers="true" %}

```json
{
  "ok": true
}
```

{% endcode %}
{% endtab %}

{% tab title="400" %}
{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="401" %}
{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

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

Разработайте SDK на вашем языке программирования для подключения graspil. Опубликуйте этот репозиторий на GitHub и напишите нам на <mail@graspil.com>. &#x20;

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

[^1]: Стандартный [объект](https://core.telegram.org/bots/api#update) с данными от ТГ.&#x20;

[^2]: Данные которые отправляет ваш бот пользователю