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