Connecting a Bot via API

Graspil offers different methods to connect a bot to the system. This article describes the method of connecting using the API. In your personal account, when connecting a bot, you can review all the connection options.

There are two methods for sending data to Graspil via the API:

1. Batch Data Sending — the preferred method

2. Real-Time Data Sending

In this article, "data" refers to a set of Update objects.

Graspil needs to receive the exact time when your bot (code) received the Update, accurate to milliseconds. Therefore, we recommend using the batch data sending method:

• You can provide the exact time of data receipt.

• If you delay data transmission, for example, sending it once a minute, it will positively affect the performance of all systems.

Why is the Receipt Date Important, and When are Milliseconds Crucial?

The receipt date of an Update object is necessary because not all Update data types contain a date.

Why milliseconds?

Milliseconds are crucial if you also send outgoing traffic to Graspil. The system needs to properly sort the list of incoming and outgoing messages, and the only way to do this is by using the date. Often, receiving and sending messages occur within the same second, so we use milliseconds.

Authorization

Graspil API expects the API key to be included in all API requests in the header, formatted as follows:

Name	Value
Api-Key	meowmeowmeow

For more details on authorization and how to obtain the authorization key, see the authorization section.

Verifying the Update Structure

In both methods, the system expects to receive Updates that fully comply with the Telegram Bot API structure. To speed up the process, the system checks only the basic parts of the data upon receipt. Full verification, including compliance with the Telegram Bot API structure, occurs later. If errors occur, they will be listed in the "Bot Errors" section.

If you decide to collect updates manually, make sure that the data structure 100% matches the Telegram Bot API. Also, ensure that you send all the required data to Graspil; otherwise, it may distort the reports.

Examples of update structures can be found in the documentation: https://core.telegram.org/bots/webhooks#testing-your-bot-with-updates

Batch Data Sending

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

This method is for batch sending Updates. You can send up to 1,000 updates with the receipt date specified. To send data, you need to send an array of data.

Headers

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

Body

Parameter	Type	Required	Описание
date	RFC 3339 (ISO 8601)	No	The time the bot received a specific update. If not provided, the current time will be set. The time format must include milliseconds and the time zone. Example: 2024-08-03T20:00:00.123+02:00
update	Object Update	Yes	A single Update object, the data you received from Telegram

The method accepts up to 1,000 Updates per request.

Example request body

[
    {
        "date": "2024-08-03T20:00:00.123+02:00", // date and time of data receipt
        "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
        }
    }
]

Code examples

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

401

Real-Time Data Sending

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

When you receive data from the Telegram Bot API, you need to send this data to our platform. The data should be sent in its original form, matching the Telegram Bot API data structure.

For the system to work correctly, it is important to transmit data at the time of receipt, or use the send-batch-update method with the receipt date if you are sending data later.

The data received from Telegram can contain two different structures, depending on the update delivery method: webhook or getUpdates. This method supports both structures.

Headers

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

Body

Example of the request body (webhook bot type)

{
  "update_id": 123,
  "message":{
    "date": 1691489960,
    "chat":{...}, // abbreviation, contains the Chat object from the TG API
    "message_id": 123,
    "from":{...}, // abbreviation, contains the User object from the TG API
    "text":"/start"
  }
}

Example of the request body (bot type getUpdates)

{
  "ok":true,
  "result":[
    {
      "update_id": 123,
      "message":{...} // abbreviation, contains the Message object from TG AP
    },
    {
      "update_id": 124,
      "message":{...} // abbreviation, contains the Message object from TG AP
    }
  ]
}

Code examples

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

Untitled

For Developers

Develop an SDK in your programming language to integrate with Graspil. Publish the repository on GitHub and let us know at [email protected].

We’ll add a link to your repository in our documentation, bringing additional visitors to your page. Additionally, we can provide free access to a premium plan for several months and early access to our referral program.