Connecting a bot via API

Graspil offers different ways to connect a bot to the system. Here we describe the connection method using the API.

In the Dashboard, when connecting a bot, you can review all available connection options.

There are two methods of sending data to graspil via the API:

1. Batch data sending — the preferred option

2. Sending data at the moment it is received

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

In graspil, it's important to get the exact time your bot (code) received the Update, down to the millisecond. That's why we recommend using the batch data sending method.

1. You can pass the exact time the data was received.

2. If you send data with a delay, for example once a minute, this will have a positive effect on the performance of all systems.

Why is the received date needed, and when do milliseconds matter

The received date of the Update object is needed simply because not all Update data types contain a date.

Why milliseconds?

They matter if you are also sending outgoing traffic to graspil. It's important for the system to correctly sort the list of incoming and outgoing messages, and the only way to do this is by using the date.

Receiving and sending messages often happens within the same second, which is why we use milliseconds.

Authorization

The Graspil API expects the API key to be included in all API requests, in a header that looks like this:

Name	Value
Api-Key	meowmeowmeow

For more details on authorization and how to get an authorization key, see the authorization section

Validating the Update structure

In both methods, the system expects to receive Updates that fully match the Telegram Bot API structure.

To speed things up, when the data is received the system only checks the basic parts of the data. A full check, including compliance with the Telegram Bot API structure, happens later. If errors occur, they will appear in the "Bot errors" section

We recommend sending data exactly as you received it from Telegram. If you decide to collect the update yourself, make sure the data structure is 100% compliant with the Telegram Bot API, and also make sure you're sending all the necessary data to graspil, otherwise this may distort the reports.

Examples of the update structure are available in the documentation at https://core.telegram.org/bots/webhooks#testing-your-bot-with-updates

Batch data sending

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

A method for sending Update objects in batches. You can send up to 1k updates, each with its own received date. To send data, you need to submit an array of data.

Headers

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

Body

Parameter	Type	Required	Description
date	RFC 3339 (ISO 8601)	No	The time the bot received this specific update. If not provided, the current time will be used. The time format must include milliseconds and a time zone. Example: 2024-08-03T20:00:00.123+02:00
update	An Update object	yes	A single Update object, the data you received from Telegram

The method accepts up to 1000 Update objects per request

Example request body

[
    {
        "date": "2024-08-03T20:00:00.123+02:00", // date and time the data was received
        "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

Sending data at the moment it is received

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

The moment you receive data from the Telegram Bot API, you need to send that data to our platform. The data must be sent unchanged, matching the Telegram Bot API data structure.

For the system to work correctly, it's important to send data at the moment it is received. Alternatively, use the send-batch-update method, adding the received date, if you're sending the data later.

Data received from Telegram can have two different structures, depending on the update delivery method — webhook or getUpdate. This method supports both structures.

Headers

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

Body

Example request body (webhook bot type)

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

Example request body (getUpdates bot type)

{
  "ok":true,
  "result":[
    {
      "update_id": 123,
      "message":{...} // <- shortened, contains the Message object from the TG API
    },
    {
      "update_id": 124,
      "message":{...} // <- shortened, contains the Message object from the TG API
    }
  ]
}

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

401

For developers

Develop an SDK in your programming language to connect to graspil. Publish this repository on GitHub and write to us at [e-mail].

We'll add a link to your repository in the documentation, which will bring extra visitors to your page. We can also provide free access to the premium plan for several months and early access to the referral program.