Sending a target event/goal completion

A goal is a user action in the bot, for example a sale. Graspil comes with several pre-built "goals," which you can see in your dashboard in the conversions section. You can also create your own goals there.

Each goal has its own trigger - some logic that, when met, creates a target event (goal completion), which you'll then see in your statistics.

"Goals" can be activated via the API. Below is the method describing how to send a target event.

Sending data

You can send from 1 to 100 events per request. Data is sent in json format. It's preferable to send events at the moment they occur.

Don't forget to add the authorization header to your request. More details in the authorization section

HTTPS Request

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

Parameters

Parameter	Type	Required	Description
target_id	integer	yes	Goal ID, you can find the ID in the settings
user_id	integer	yes	Telegram ID of the user the event belongs to. Before saving the data, the system checks whether this ID belongs to a user of your bot.
date	RFC 3339 (ISO 860)	no	The date and time the event occurred. If left empty, the current time will be used. The time format must include milliseconds and a timezone. Example: 2024-08-03T20:00:00.123+02:00
value	float	no	Total price (a floating-point number).
unit	string(3)	yes, if value is present	Currency code, maximum string length 3. Similar to currencies in the TG API.

You can pass either a single object:

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

Or an 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

Response

Example of a successful response:

{
  "ok": true
}

Errors

When receiving data, the API only checks basic parameters; the remaining checks happen later during data processing. You can find all errors that occur in the "bot errors" section

If a data validation error occurs, 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"
      ]
  }
}