Send Custom Event

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

Body Parameters

event_namestringRequired

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

telegram_idintegerRequired

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

workspace_iduuidRequired

Your workspace ID.

session_idstringOptional

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

valuefloatOptional

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

currencystringOptional

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

user_dataobjectOptional

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

Response

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