# Engagements

## Concepts

**Engagements** in Conversion are events that happen for a contact. These can include website page visits, form submissions, actions in the product, or even sales meetings.

**Custom engagements** are a subset of engagements, representing engagements that aren't natively tracked in Conversion and synced in from external sources. Examples include:

* Meetings
* Calls
* Product usage

## Batch Track Custom engagements

Record custom engagements for contacts.

**Rate limits:** 10 / second, 200 custom engagements per batch

**Method:** `POST` 

**Route:** `/v1/activities/batch`

**Request Body:**

```json
{
  "batch": [
    {
      "id": "your_custom_engagement_id_123",
      "contactEmail": "john@example.com",
      "type": "PRODUCT_ACTIVITY",
      "name": "Product Demo Completed",
      "description": "Customer completed full product demonstration session",
      "data": { // Include any relevant engagement metadata
        "duration_minutes": 45,
        "demo_type": "interactive",
        "interest_level": "high",
        ...
      }
    },
    ...
  ]
}
```

**Field Descriptions:**

* `batch` (required): List of contacts to create/update
  * `id` (optional): Your system's custom engagement id
  * `contactEmail` (required): The contact's email address to track the custom engagement for
  * `type` (required): The type of this custom engagement
  * `name` (optional): The name of this custom engagement
  * `description` (optional): The description of this custom engagement
  * `createdAt` (optional): Defaults to now. When the custom engagement was created in your system.
  * `data` (optional): Key-value pairs for the custom engagement's data fields

**Response:**

Empty object response.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.conversion.ai/engagements.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.