Отправить событие

Production

Send server-to-server (S2S) events from your Telegram bot or backend to GramPixel. Events are automatically mapped to native platform formats (Meta CAPI, TikTok Events) and forwarded to configured ad network integrations. Event Mapping: FTD/DEP/Purchase → Purchase (Meta) / CompletePayment (TikTok) with value. REG → CompleteRegistration / Registration. Subscribe/JoinRequest → Lead / SubmitForm. INSTALL → AppInstall / Download. TRIAL → StartTrial / Subscribe. Session Resolution: If session_id is not provided, the system resolves it automatically: 1) prelanding_invite_sessions by telegram_id, 2) ClickHouse events, 3) last known session. The session_id links the event to the original ad click for attribution.

POST/api/v1/events/custom

Параметры тела

event_namestringОбязательно

Event key: FTD, DEP, REG, Subscribe, JoinRequest, Purchase, INSTALL, TRIAL, or any custom name.

telegram_idintegerОбязательно

Telegram User ID. Used for session resolution and S2S attribution.

workspace_iduuidОбязательно

Your workspace ID.

session_idstringНеобязательно

The GramPixel session ID (from ?start= deep link parameter, e.g. gp_a1b2c3). Auto-resolved if omitted.

valuefloatНеобязательно

Monetary value. Required for FTD, DEP, Purchase events for ROAS tracking.

currencystringНеобязательно

3-letter ISO 4217 currency code. Defaults to USD.

user_dataobjectНеобязательно

Additional user metadata (e.g. { "plan": "premium" }).

How to get session_id in your bot

When a user clicks t.me/your_bot?start=gp_a1b2c3, your bot receives /start gp_a1b2c3. Parse and store this value per user, then pass it back as session_id on conversion events for precise attribution.

curl -X POST https://api.grampixel.com/v1/events/custom \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "FTD",
    "telegram_id": 123456789,
    "session_id": "gp_a1b2c3",
    "workspace_id": "uuid-of-workspace",
    "value": 150.00,
    "currency": "USD",
    "user_data": { "plan": "premium" }
  }'

Ответ

{
  "ok": true,
  "data": {
    "event_id": "evt_89237498237",
    "session_id": "gp_a1b2c3",
    "status": "processed"
  }
}