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

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

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

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

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"
      ]
  }
}

Last updated