# Event catalog

> Documented watsi webhook event types with example payloads and field notes for handlers.

Source: https://docs.watsi.ai/en/webhooks/events

These examples mirror the event naming already used in watsi's existing integration docs and are meant to show the shape an integration should expect and persist.

## Index

| Event                                          | Description                                                            |
| ---------------------------------------------- | ---------------------------------------------------------------------- |
| [`message.received`](#messagereceived)         | New inbound message payload from the messaging pipeline.               |
| [`message.status`](#messagestatus)             | Delivery/read/failure status change for an outbound message.           |
| [`conversation.created`](#conversationcreated) | A new conversation record was created.                                 |
| [`conversation.updated`](#conversationupdated) | A conversation attribute such as assignee or automation state changed. |
| [`contact.created`](#contactcreated)           | A new contact record was created.                                      |
| [`contact.updated`](#contactupdated)           | A contact profile was updated.                                         |

## Messages

### message.received

Triggered when an inbound message enters watsi. Handlers typically use this event to sync inbound messages into an external CRM, warehouse, or workflow engine.

```json message.received
{
  "id": "evt_01HXYZ111111111",
  "type": "message.received",
  "created_at": "2025-03-15T10:30:00.000Z",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "from": "5215512345678",
    "body": "Hola, quiero información",
    "messageId": "wamid.HBgL...",
    "conversationId": "chat_123",
    "channel": "whatsapp"
  }
}
```

### message.status

Triggered when an outbound message changes state. Use it to reconcile sent, delivered, read, or failed transitions in downstream systems.

```json message.status
{
  "id": "evt_01HXYZ222222222",
  "type": "message.status",
  "created_at": "2025-03-15T10:32:00.000Z",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "messageId": "wamid.HBgL...",
    "status": "delivered",
    "recipientId": "5215512345678",
    "timestamp": "1710499920"
  }
}
```

## Conversations

### conversation.created

Triggered when watsi opens a new conversation record for a contact.

```json conversation.created
{
  "id": "evt_01HXYZ333333333",
  "type": "conversation.created",
  "created_at": "2025-03-15T10:30:00.000Z",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "conversationId": "chat_123",
    "contactId": "contact_123",
    "status": "active",
    "channel": "whatsapp"
  }
}
```

### conversation.updated

Triggered when a tracked conversation field changes, such as assignment, closure state, or automation status.

```json conversation.updated
{
  "id": "evt_01HXYZ444444444",
  "type": "conversation.updated",
  "created_at": "2025-03-15T11:00:00.000Z",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "conversationId": "chat_123",
    "status": "closed",
    "assignedUserId": "user_123",
    "watsiEnabled": false
  }
}
```

## Contacts

### contact.created

Triggered when watsi creates a new contact record.

```json contact.created
{
  "id": "evt_01HXYZ555555555",
  "type": "contact.created",
  "created_at": "2025-03-15T10:30:00.000Z",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "contactId": "contact_123",
    "phone": "+5215512345678",
    "name": "Ana Martínez"
  }
}
```

### contact.updated

Triggered when watsi updates a contact profile.

```json contact.updated
{
  "id": "evt_01HXYZ666666666",
  "type": "contact.updated",
  "created_at": "2025-03-16T09:00:00.000Z",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "contactId": "contact_123",
    "name": "Ana M. García",
    "email": "ana@example.com"
  }
}
```