# WEBHOOK visit.message.created
URL: https://developers.vsee.io/api/visit-messages-api/webhook/visit.message.created
API: Visit Messages API — https://developers.vsee.io/api/visit-messages-api
Direction: inbound — delivered to your configured webhook URL, not called by you.

New message on the visit thread

Fires for **every** new message on the visit, in either direction — patient messages sent through this API and provider replies sent from the VSee Clinic dashboard. Filter on `data.actor_type` if you only want one side.

The payload is a thin pointer: it deliberately carries **no message content and no PHI**. Treat it as a signal to fetch, then read the thread with `GET /api/visits/{visit_id}/messages`.

## Delivery

Configure the destination URL per clinic account in Admin settings. There is no signature header — restrict your endpoint by network or use an unguessable path.

| Behaviour | Contract |
|-----------|----------|
| Acknowledgement | Return any `2xx` within 30 seconds |
| Retries | Up to 5 attempts, roughly 60 seconds apart |
| De-duplication | Retries repeat a delivery — de-duplicate on `data.message_id` |
| Ordering | Not guaranteed; use `data.ts` to order |
| Latency | Seconds for messages sent through this API, up to ~2 minutes for provider replies |

## Handling

1. Acknowledge immediately — do the work after responding, not before.
2. Skip the event if you have already seen its `data.message_id`.
3. Call `GET /api/visits/{visit_id}/messages?skip=<count you hold>` to pull only what is new.

Payload (application/json):
- id (string, required) — Unique id for this delivery. Changes on each retry — do not de-duplicate on it.
- type (string, required) — Event name [one of: visit.message.created]
- created (integer, required) — UNIX timestamp when the event was emitted
- account_code (string, required) — Clinic account the visit belongs to
- version (string, required) — Payload version
- data (object, required) — Pointer to the new message. Carries no message content or PHI.
- data.visit_id (string, required) — Visit whose message thread changed
- data.message_id (string, required) — The new message. De-duplicate on this — retries repeat a delivery.
- data.actor_type (string, required) — Who sent the message [one of: patient, provider]
- data.ts (integer, required) — UNIX timestamp when the message was created

Example delivery:
```json
{
  "id": "6a47ea02-4809-4af6-b8f6-c56bc2bd2adb",
  "type": "visit.message.created",
  "created": 1786755119,
  "account_code": "aubrey",
  "version": "1.0",
  "data": {
    "visit_id": "1000021648",
    "message_id": "83c3b3d7-346c-4ac9-8276-f96ac8356e25",
    "actor_type": "provider",
    "ts": 1786755119
  }
}
```