Sending interactions — guide for the app team

Audience: Android, iOS and web developers. Status: built on the backend (branch fet/feed_baking, 2026-09-17).

The recommendation model learns from what people do. It can only learn from what the app sends, and anything not sent today is lost for good: a watch time nobody recorded cannot be recovered later. Please send everything below from the first release that has the endpoint.

The same action must mean the same thing on every platform. A VIEW on Android and a VIEW on iOS are counted together; if their definitions differ, the model learns the difference between the apps instead of what people like.

1. The endpoint

POST /api/v1/feed/interactions/batch
Authorization: Bearer <access token>
Content-Type: application/json

{
  "sessionId": "s-8812e0c4",
  "client": { "platform": "ANDROID", "appVersion": "2.4.1", "networkType": "CELLULAR" },
  "events": [
    { "clientEventId": "c-000184", "action": "IMPRESSION", "targetType": "POST", "targetId": "4f2a77e1-0c8b-4d2f-9a11-7b6c3e5d8f90",
      "occurredAt": "2026-09-17T10:22:31.900Z",
      "context": { "surface": "REELS", "position": 3, "feedSessionId": "fs-77aa", "source": "RECO" } },
    { "clientEventId": "c-000185", "action": "VIEW", "targetType": "POST", "targetId": "4f2a77e1-0c8b-4d2f-9a11-7b6c3e5d8f90",
      "occurredAt": "2026-09-17T10:22:41.100Z",
      "watchMs": 9000, "mediaDurationMs": 6000, "loopCount": 1, "soundOn": true, "mediaIndex": 0,
      "context": { "surface": "REELS", "position": 3, "feedSessionId": "fs-77aa", "source": "RECO" } }
  ]
}

Answer: 202

{ "data": { "accepted": 2, "dropped": 0, "rejected": [] } }

• rejected lists events that were invalid, each with a reason. Fix the app; do not resend them.
• dropped counts valid events the server did not keep (rate limit or a temporary broker problem). Do not resend them either.
• Only resend a batch when the request itself failed (no connection, timeout, 5xx). Resending is safe: the server recognises repeats by clientEventId.
• Never put an account id in the body. The account always comes from the token; any id in the body is ignored.
• Unknown fields are ignored, so an older server never rejects a newer app.

2. When to send

Never send one request per event.

3. Fields

Batch

Event

Send numbers as whole milliseconds. Leave a field out rather than sending 0 when it was not measured.

4. Actions — exact definitions

Do not send LIKE, UNLIKE, COMMENT, BOOKMARK, SHARE, ADD_TO_CART, REMOVE_FROM_CART, PURCHASE, BLOCK, REPORT or MUTE_AUTHOR. Just call the feature's own API (like a post, add to cart, pay). The backend sends the interaction itself once the change is saved, so it is counted exactly once, even if the app crashes before its next batch, and never for a like that failed. The batch API rejects these actions with SENT_BY_SERVER.

What the backend cannot know is where the tap happened. Keep sending CLICK with context (surface, position, source, viaPostId) when a product, event or profile is opened; that is how the model learns a post led to a purchase.

Clips (reels)

• A clip is a POST. Use the clip's postId as targetId, not its id (that is the media id); mediaIndex says which video of the post.
• mediaDurationMs = media.durationMs from the clip response.
• POST /api/v1/e-social/clip/{id}/view only counts the view (once per person). It ignores watchDurationMs and source: watch time reaches the model only through this batch.
• A clip with visibility: INTERSTITIAL gets a "sensitive content" cover; play only after the viewer taps through.

Worked examples

A reel watched to the end and replayed partly, sound on, on cellular VIEW, watchMs: 9000, mediaDurationMs: 6000, loopCount: 1, soundOn: true, surface REELS.

A reel flicked past IMPRESSION (if it met 50 % / 300 ms), then SKIP with watchMs: 400, mediaDurationMs: 15000.

Third image of a carousel post looked at for 2.5 s VIEW, targetType: POST, mediaIndex: 2, dwellMs: 2500.

A product tagged in a post, opened then added to cart CLICK, targetType: PRODUCT, context.viaPostId = the post. The add to cart itself is sent by the backend.

Search SEARCH, context: { surface: "SEARCH", query: "running shoes" }; then an IMPRESSION per result with surface: SEARCH and its position.

5. Rejection reasons

A rejection is a bug in the app. Log it in development builds.