Sending a target event/achieving a goal

The goal is the user's action in the bot, for example, a sale. Graspil has several “goals” already created, you can see them in your personal account in the conversions section. You can also create your own goals there.

Each goal has its own trigger — some kind of logic, upon the occurrence of which a target event (goal achievement) will be created, which you will see in the statistics.

“Goals” can be activated via the API. Below is a method that describes how to send a target event.

Sending data

You can send from 1 to 100 events per request. The data is sent in json format. It is preferable to send events at the moment they appear. HTTPS Request POST https://api.graspil.com/api/send-target

Don't forget to add a header to authorize the request. For more information, see this section

HTTPS Request

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

Transmitted parameters

Параметр	Type	Обязательный	Описание
target_id	integer	yes	The goal ID, you can find the ID in the settings
user_id	integer	yes	Telegram ID of the user to whom the event belongs. Before saving the data, it will be checked whether the id matches the user of your bot.
date	string ISO8601	no	The date and time when the event occurred, if left empty, 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
value	float	no	Total price (floating point number)
unit	string(3)	yes, if value is set	Currency code, maximum line length 3. Similar to currencies in the TG Api.

Examples of data being sent

You can transfer it as one object:

{
    "target_id": 1,
    "user_id": 5842703839,
    "date": "2023-12-31T20:00:00+01:00",
    "value": 10,
    "unit": "usd"
}

So is the array of objects:

[
    {
        "target_id": 1,
        "user_id": 5842703839,
        "date": "2023-12-31T20:00:00+01:00",
        "value": 10,
        "unit": "usd"
    },
    {
        "target_id": 1,
        "user_id": 5842703839,
        "date": "2023-12-31T20:00:00+01:00",
        "value": 10,
        "unit": "usd"
    }
]

Code examples

PHP

$url = "https://api.graspil.com/v1/send-target";
$api_key = ""; // your API key
$data = json_encode([
    "target_id": 1,
    "user_id": 5842703839,
    "date": "2023-12-31T20:00:00+01:00",
    "value": 10,
    "unit": "usd"
]);

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

Python

import requests
import json

url = "https://api.graspil.com/v1/send-update"
api_key = ""  # your API key

payload = json.dumps({
  "target_id": 1,
  "user_id": 5842703839,
  "date": "2023-12-31T20:00:00+01:00",
  "value": 10,
  "unit": "usd"
})

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

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

print(response.text)

Answer

Example of a successful response:

{
  "ok": true
}

Errors

When receiving data, the API checks only the basic parameters, the rest of the checks occur later during data processing. You can find all the errors that have occurred in the “bot errors” section

In case of errors during data validation, the response will contain information about the error

{
  "ok": false,
  "error": {
      "target_id": [
          "Unknown target_id"
      ],
      "user_id": [
          "The user with this id was not found"
      ]
  }
}