> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellocobi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interaction Model

> The user interaction data model represents a user's interaction with an item (TAG, OFFER, KEYWORD, or SHOP) in the Cobi system.

<Note>
  **Important**: User interaction records have dependencies students. The system
  validates the `student_id` against existing records in the database. You
  should upload student data before uploading user interaction records to ensure
  proper data validation. The `item_id` field must reference the correct item
  type as specified by `item_type`.
</Note>

## Schema

```json theme={null}
{
  "type": "object",
  "required": [
    "interaction_type",
    "student_id",
    "item_type",
    "event_timestamp"
  ],
  "properties": {
    "interaction_type": {
      "type": "string",
      "description": "Type of interaction. One of: FILTER_CLICK, SHARE, PAGE_VIEW, DISCOUNT_CODE"
    },
    "user_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the student"
    },
    "student_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "UUID of the student"
    },
    "item_type": {
      "type": "string",
      "description": "One of: TAG, OFFER, SHOP, KEYWORD"
    },
    "item_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the item (TAG, OFFER, KEYWORD or SHOP) as determined by item_type"
    },
    "city": {
      "type": "string",
      "description": "City where the interaction occurred"
    },
    "country": {
      "type": "string",
      "description": "Country where the interaction occurred"
    },
    "platform": {
      "type": "string",
      "description": "One of: ANDROID, IOS, WEB, OTHER"
    },
    "event_timestamp": {
      "type": ["integer", "string"],
      "description": "Event timestamp (positive integer or ISO datetime string)"
    }
    "source": {
      "type": "string",
      "nullable": true,
      "description": "Source of interaction. Set to 'COBI' when the interaction is from a recommendation API response, null otherwise"
    },
    "recommendation_id": {
      "type": "string",
      "nullable": true,
      "description": "Recommendation ID of cobi recommended interaction, null otherwise"
    },
  }
}
```

## Field Descriptions

### Required Fields

| Field              | Type           | Description                                                                   |
| ------------------ | -------------- | ----------------------------------------------------------------------------- |
| `interaction_type` | string         | Type of interaction. One of: FILTER\_CLICK, SHARE, PAGE\_VIEW, DISCOUNT\_CODE |
| `item_type`        | string         | One of: TAG, OFFER, SHOP                                                      |
| `item_id`          | string (UUID)  | UUID of the item (TAG, OFFER, KEYWORD or SHOP) as determined by `item_type`   |
| `event_timestamp`  | int/ISO string | Event timestamp (positive integer or ISO datetime string)                     |

### Optional Fields

| Field               | Type          | Description                                                                       |
| ------------------- | ------------- | --------------------------------------------------------------------------------- |
| `user_id`           | string        | Psuedo Id of the student                                                          |
| `student_id`        | string (UUID) | UUID of the student                                                               |
| `city`              | string        | City where the interaction occurred                                               |
| `country`           | string        | Country where the interaction occurred                                            |
| `platform`          | string        | One of: ANDROID, IOS, WEB, OTHER                                                  |
| `source`            | string        | Source of interaction. Set to 'COBI' when from recommendation API, null otherwise |
| `recommendation_id` | string (UUID) | Source of interaction. Set to 'COBI' when from recommendation API, null otherwise |

## Example

```json theme={null}
{
  "interaction_type": "FILTER_CLICK",
  "user_id": "75962b04e5caa7e582e2bc2949587ed9"
  "student_id": null,
  "item_type": "TAG",
  "item_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "city": "Berlin",
  "country": "Germany",
  "platform": "WEB",
  "event_timestamp": 1718035200,
  "source": "COBI",
  "recommendation_id": "6fc7eb1d-a516-4a9b-8dcc-313976461ae4"
}
```

## Source Field for Recommendation Feedback

The `source` field is used to track whether user interactions originated from recommendation API responses:

* **`null`**: The interaction occurred through normal user browsing (not from a recommendation)
* **`"COBI"`**: The interaction occurred when a user clicked on or interacted with an item that was recommended by the Cobi recommendation API

This field is crucial for:

* **Feedback Loop**: Helps the recommendation system understand which recommendations led to user engagement
* **Analytics**: Track the effectiveness of recommendation algorithms
* **Model Training**: Improve future recommendations based on user interaction patterns

### Example Usage

When a user receives recommendations from the API and clicks on a recommended offer:

```json theme={null}
{
  "interaction_type": "PAGE_VIEW",
  "student_id": "00000000-9779-438e-ae0d-b52099f6be51",
  "item_type": "OFFER",
  "item_id": "00000000-aaca-4844-9cb0-54af8f897322",
  "event_timestamp": 1718035200,
  "source": "COBI"
}
```

## Best Practices

1. **Data Validation**: Ensure all required fields are present and properly formatted.
2. **Timestamps**: Use a valid positive integer or ISO 8601 string for `event_timestamp`.
3. **Platform**: Use one of the allowed values for `platform`.
4. **Source Tracking**: Always set `source` to "COBI" when tracking interactions from recommendation API responses.

Need help? Contact our support team at [support@hellocobi.com](mailto:support@hellocobi.com)