Event Tracker

The track call#

Every event — reserved or general — is a POST /v1/track with the same envelope. The event name decides how it is handled; the data object carries the properties for that event.

A minimal call and its response:

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "product_viewed",
    "sessionId": "sess-9f2c",
    "userId": "+966501234567",
    "data": { "productId": "SKU-1", "productName": "Blue Shirt" }
  }'

A successful call returns 200 with the ID we assigned the event:

{ "eventId": "px-1f3a9c20-6b7e-4a51-9d2c-8e0b4f7a1c33" }

Identity & sessions#

Two fields identify who an event is about and how its events group together.

userId — the contact

userId is the contact's phone number in E.164 form, e.g. +966501234567. Formatting is tolerated — spaces, dashes, brackets, and Arabic-Indic digits are cleaned up — and the endpoint turns away only what is obviously not a number.

sessionId — the visit

sessionId is a stable string you choose that scopes one visit. Events in your workspace sharing a sessionId are treated as one journey. Use any stable identifier — a cookie value, a server session ID — and keep sending the same one for the life of the visit.

Reserved events#

These are the events BusinessChat acts on. Each needs its sessionId, and some need specific keys inside data — those are listed as required below and are checked when the event is received. Everything else is enrichment: it improves what an automation can say, but its absence never rejects the event.

session_started#

The visitor has begun a session. Send it once at the start of a visit.

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "session_started", "sessionId": "sess-9f2c",
        "data": { "url": "https://shop.example/home" } }'

website_visited#

A page was viewed within a session.

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "website_visited", "sessionId": "sess-9f2c",
        "data": { "url": "https://shop.example/products/blue-shirt" } }'

contact_identified#

You have learned the visitor's phone number. Send it to attach the contact to the session; from here on the session can be messaged.

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "contact_identified", "sessionId": "sess-9f2c",
        "userId": "+966501234567" }'

product_viewed#

The visitor looked at a product.

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "product_viewed", "sessionId": "sess-9f2c",
        "userId": "+966501234567",
        "data": { "productId": "SKU-1", "productName": "Blue Shirt",
                  "productPrice": 49.0, "productCurrency": "SAR" } }'

added_to_cart#

The visitor added a product to their cart.

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "added_to_cart", "sessionId": "sess-9f2c",
        "userId": "+966501234567",
        "data": { "productId": "SKU-1", "qty": 2, "addedAt": "2026-09-07T10:15:00Z",
                  "cartProducts": [ { "productId": "SKU-1", "quantity": 2 },
                                    { "productId": "SKU-9", "quantity": 1 } ],
                  "cartId": "cart-77", "cartUrl": "https://shop.example/cart",
                  "cartTotal": "98.00", "currency": "SAR" } }'

checkout_started#

The visitor began checkout.

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "checkout_started", "sessionId": "sess-9f2c",
        "userId": "+966501234567",
        "data": { "checkoutUrl": "https://shop.example/checkout/9f2c",
                  "productsIdAndQtyList": ["SKU-1:2", "SKU-9:1"],
                  "cartTotal": "147.00", "currency": "SAR" } }'

removed_from_cart#

The visitor removed a product from their cart.

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "removed_from_cart", "sessionId": "sess-9f2c",
        "userId": "+966501234567",
        "data": { "productId": "SKU-1", "qty": 1,
                  "removedAt": "2026-09-07T10:20:00Z",
                  "cartProducts": [ { "productId": "SKU-9", "quantity": 1 } ] } }'

How cart recovery works#

Cart events do more than record activity: they are what makes abandoned-cart recovery possible. It is worth knowing how the timing works, because nothing you send triggers a message directly.

1. You send cart events. Each one updates what BusinessChat believes is in this shopper's cart, and refreshes their activity clock.
2. The shopper goes quiet. After roughly four hours with no further events, their session is closed.
3. If the cart was still open at that moment, recovery runs — the abandoned-cart automation sends its WhatsApp message.

So recovery is inferred from silence, on our side. There is no event you can send that means "send the recovery message now", and none that skips the wait.

An order cancels it. If an order arrives for the shopper before the message goes out, recovery is called off rather than sent — you do not need to tell us to stop.

What the message can say. The recovery template can use the cart link, the cart total, the currency and the cart id. Product names are not available — only product ids reach this stage — so a template cannot list the items by name. Send cartUrl and cartTotal with currency if you want the message to name a value and link back.

heartbeat#

Keeps a session alive while the visitor is active. Sessions also close on their own after inactivity, so heartbeats are optional for a backend integration.

Valid state values (uppercase, exact): SESSION_STARTED, SESSION_ENDED, PRODUCT_VIEWED, CART_ADDED, CHECKOUT_STARTED, ORDER_COMPLETED, CART_ABANDONED.

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "heartbeat", "sessionId": "sess-9f2c",
        "data": { "state": "SESSION_STARTED" } }'

Orders#

An order sent here becomes the same order BusinessChat builds from a connected store, so everything that already reacts to an order reacts to this one: the contact and conversation are created, post-purchase and order-status automations run, the customer's journey advances, and the revenue is attributed.

There are two event names:

Orders carry no sessionId — an order is not a browsing session. They do require userId: the order creates the contact, and every automation it drives needs someone to message.

Fields#

Required

Optional — order

Optional — the customer object

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "order_created",
    "userId": "+966501234567",
    "data": {
      "order_id": 1001,
      "reference_id": "ORD-1001",
      "status": "processing",
      "total": { "amount": 149.00, "currency": "SAR" },
      "created_at": "2026-09-06T10:00:00Z",
      "order_link": "https://shop.example/orders/1001",
      "products": [ { "id": "SKU-1", "name": "Blue Shirt", "quantity": 2 } ],
      "customer": { "name": "Sara" }
    }
  }'

Reporting a status change later is the same call with order_updated and the new status:

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "order_updated",
    "userId": "+966501234567",
    "data": {
      "order_id": 1001,
      "status": "paid",
      "total": { "amount": 149.00, "currency": "SAR" },
      "created_at": "2026-09-06T10:00:00Z",
      "updated_at": "2026-09-06T11:15:00Z"
    }
  }'

Status values#

Send one of these words, lower-case. They are listed in lifecycle order:

new, created, pending, payment_pending, authorized, partially_paid, processing, under_review, preparing, ready, shipped, delivering, paid, delivered, completed, closed, abandoned, restored, restoring, partially_refunded, cancelled, refunded, failed, denied, voided, expired.

General events#

Any event name that is not a reserved name is a general event. Use these to record facts BusinessChat has no built-in behavior for — a loyalty tier change, a newsletter signup — so you can report on them alongside everything else.

curl -X POST 'https://pixel-gateway.businesschat.io/v1/track' \
  -H 'Authorization: Bearer YOUR_TRACK_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "event": "loyalty_tier_changed", "userId": "+966501234567",
        "data": { "tier": "gold", "previous": "silver" } }'

Like every accepted event, a general event returns its eventId. There is no sessionId requirement.

Responses#

Every accepted event, reserved or general, returns 200 with the ID we assigned it:

{ "eventId": "px-1f3a9c20-6b7e-4a51-9d2c-8e0b4f7a1c33" }

A request without a valid track token returns 401, whatever is wrong with the token, and nothing is recorded:

{ "error": "Missing or invalid track token. Send it as `Authorization: Bearer <token>`." }

A request that fails validation returns 422 with a message naming the problem:

{ "error": "Missing field: data.url, required for session_started" }

Errors#

A missing, malformed or invalid track token returns 401 before the body is read; see Responses. All validation failures return 422 with an error string. The full set:

Good to know#

• No idempotency. Every accepted call mints a new eventId. If you retry a request, you create a duplicate event — retry only when you did not receive a 200.
• Timestamps are for you, timing is on receipt. occurredAt is recorded as you send it (useful for backfills), but journeys and automations run against the moment we receive the event.
• Accepted-then-dropped. Beyond the checks listed above, a value we cannot interpret downstream — an unknown enum name, a wrongly typed field — costs the whole event: you still get 200, but nothing is acted on. Send valid values, and use the exact state names and the "productId:qty" format shown above.
• The envelope wins over data. An envelope field repeated inside data is ignored; you cannot override sessionId or the contact through data, and the workspace always comes from your token.
• Popup events are widget-only. popup_viewed, cta_clicked, and popup_dismissed are emitted by the BusinessChat on-site widget and carry IDs only it knows. Sending them from a backend records them as general events.