# Notify Fin of Conversation Events

This endpoint handles two distinct use cases depending on whether an `event_type` is provided:
## 1. Conversation Synchronization (default behavior)
When you **omit the `event_type` field**, Fin will synchronize the conversation by pulling the latest data from your endpoints. Use this when:
- An agent sends a message
- The conversation state changes (status, assignee, etc.)
- Any other conversation data changes that Fin should know about

**Example payload:**

```json
{
  "conversation_id": "conv_456"
}
```
## 2. Agent Typing Indicator
When you set `event_type` to `agent_typing`, Fin will display a typing indicator to the end-user in the Fin Messenger. **No synchronization occurs** - this is purely a real-time UI update.
Use this when an agent starts typing a response in your helpdesk. The typing indicator automatically dismisses after a few seconds.
**Important:** When using `event_type: "agent_typing"`, the `data.agent` field is **required** and must include the agent's `id`, `user_type`, `name`, and `email`.
**Example payload:**

```json
{
  "conversation_id": "conv_456",
  "event_type": "agent_typing",
  "data": {
    "agent": {
      "id": "agent_001",
      "user_type": "agent",
      "name": "Sarah Johnson",
      "email": "sarah.johnson@company.com"
    }
  }
}
```

Endpoint: POST /custom_helpdesk_conversation_event/{integration_id}
Version: 0.0.1
Security: WebhookSignature

## Path parameters:

  - `integration_id` (string, required)
    The ID of your integration. You can find this in the Fin Deployment UI.

## Request fields (application/json):

  - `conversation_id` (string, required)
    ID of the conversation in your system
    Example: conv_456

  - `event_type` (string)
    Optional. The type of event that occurred.
- **Omitted or null**: Fin will synchronize the conversation by pulling the latest data from your endpoints.
- `agent_typing`: Displays a typing indicator to the end-user. No synchronization occurs. Requires `data.agent` to be provided.
    Enum: "agent_typing"

  - `data` (object)
    Additional event data. Required when `event_type` is `agent_typing`.

  - `data.agent` (object)
    Agent having a conversation with an end-user.

  - `data.agent.id` (string)
    Unique identifier for the user in your system
    Example: agent_123456

  - `data.agent.user_type` (string)
    Type of user
    Enum: "agent"

  - `data.agent.name` (string)
    User's display name
    Example: Jane Doe

  - `data.agent.email` (string)
    User's email address
    Example: jane.doe@example.com

  - `data.agent.photo_url` (string)
    URL to user's avatar/profile picture (displayed in Fin Messenger)
    Example: https://example.com/avatars/jane.jpg

  - `data.agent.alias` (string)
    Agent's display alias (shown to end-users instead of real name)
    Example: Support Jane