--- updatedAt: 2026-06-26T12:43:18.000Z --- Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further. # Chat webhook The Chat webhook notifies you in real time when chat messages and conversations are created, updated, or deleted, so you can mirror Connecteam Chat into your own systems without polling. > 🚧 Beta > > **Chat webhooks are currently in Beta and are enabled per company.** Event names, payload fields, and behavior may change before general availability. Build defensively — ignore unknown fields and tolerate new event types — so your integration keeps working as the feature graduates from Beta. See [Beta Endpoints](beta-endpoints) for our Beta policy and contact information. ## Events All Chat events use the `chat` feature type. Subscribe with the `eventType` values below. | Event Type | Entity | Description | | :-------------------- | :----------- | :---------------------------------------------------------------------------------------- | | message\_created | message | A new message was posted in a conversation | | message\_updated | message | A message's content was edited | | message\_deleted | message | A message was deleted (content & attachments omitted) | | conversation\_created | conversation | A new conversation was created (private, group, or channel) | | conversation\_updated | conversation | A conversation was edited: title/members changed, locked/unlocked, or description changed | | conversation\_deleted | conversation | A conversation was deleted (description & lock state omitted) | *** ## Subscribing Create the subscription with the Webhook API using `featureType: "chat"`. See [Setting up webhook via API](https://developer.connecteam.com/docs/setting-up-webhook-via-api) for the full management reference (list, update, delete). ```bash curl --request POST \ --url https://api.connecteam.com/settings/v1/webhooks \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: YOUR_API_KEY' \ --data '{ "name": "Chat events", "url": "https://your-endpoint.com/webhooks/chat", "featureType": "chat", "eventTypes": [ "message_created", "message_updated", "message_deleted", "conversation_created", "conversation_updated", "conversation_deleted" ], "secretKey": "a-long-random-string-you-generate" }' ``` > 👍 Scope to a single conversation > > Pass `entityId` with a conversation ID (as a string) to receive events for just that conversation. Omit it to receive events for **all** conversations in the company. *** ## Payload Structure Every delivery is an HTTP `POST` with a JSON body sharing the same envelope. The event-specific object lives under `data`. | Field | Type | Description | | :------------- | :------ | :------------------------------------------------------------------------------------------------------ | | requestId | string | Correlation ID for the delivery (useful for de-duplication & support) | | company | string | The Connecteam company (object) ID | | activityType | string | Always `Chat` | | eventTimestamp | integer | When the event fired — Unix timestamp in **seconds** | | eventType | string | One of the six event types above | | data | object | Event-specific object: contains `message` for message events, or `conversation` for conversation events | > 📘 Timestamps > > All timestamps are **Unix seconds** — both the envelope `eventTimestamp` and the `createdAt`, `modifiedAt`, and `deletedAt` fields inside `data`. A deprecated, misspelled `evnetTimestamp` field mirrors `eventTimestamp` for backward compatibility — always read `eventTimestamp`. *** ## Message Events For `message_created`, `message_updated`, and `message_deleted`, `data.message` is a message object. ### message\_created ```json { "requestId": "f1c2e3a4-5b6c-7d8e-9f01-2a3b4c5d6e7f", "company": "your_company_id", "activityType": "Chat", "eventTimestamp": 1717238400, "eventType": "message_created", "data": { "message": { "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", "conversationId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789", "conversationSource": "chat", "conversationType": "channel", "senderId": 4455667, "senderType": "user", "recipientId": null, "type": "text", "content": "Morning team \u2014 shift starts in 15 minutes", "attachments": null, "isSystem": false, "createdAt": 1717238400 } } } ``` ### message\_created (with a file attachment) ```json { "requestId": "0b1a2c3d-4e5f-6071-8293-a4b5c6d7e8f9", "company": "your_company_id", "activityType": "Chat", "eventTimestamp": 1717238460, "eventType": "message_created", "data": { "message": { "id": "aa11bb22-cc33-dd44-ee55-ff6677889900", "conversationId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789", "conversationSource": "chat", "conversationType": "channel", "senderId": 4455667, "senderType": "user", "recipientId": null, "type": "file", "content": null, "attachments": [ { "type": "file", "url": "https://files.connecteam.com/chat/aa11bb22.pdf", "fileName": "june-schedule.pdf", "fileSize": 248213 } ], "isSystem": false, "createdAt": 1717238460 } } } ``` ### message\_created (private 1:1 — includes recipientId) ```json { "requestId": "2b3c4d5e-6f70-8192-a3b4-c5d6e7f80911", "company": "your_company_id", "activityType": "Chat", "eventTimestamp": 1717238700, "eventType": "message_created", "data": { "message": { "id": "bb22cc33-dd44-ee55-ff66-778899001122", "conversationId": "5e6f7890-abcd-ef01-2345-6789abcdef01", "conversationSource": "chat", "conversationType": "private", "senderId": 4455667, "senderType": "user", "recipientId": 8899001, "type": "text", "content": "Can you cover the front desk at 2pm?", "attachments": null, "isSystem": false, "createdAt": 1717238700 } } } ``` ### message\_updated `modifiedAt` is included; `deletedAt` is omitted. ```json { "requestId": "7c6d5e4f-3a2b-1c0d-9e8f-7a6b5c4d3e2f", "company": "your_company_id", "activityType": "Chat", "eventTimestamp": 1717238500, "eventType": "message_updated", "data": { "message": { "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", "conversationId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789", "conversationSource": "chat", "conversationType": "channel", "senderId": 4455667, "senderType": "user", "recipientId": null, "type": "text", "content": "Morning team \u2014 shift starts in 10 minutes (edited)", "attachments": null, "isSystem": false, "createdAt": 1717238400, "modifiedAt": 1717238500 } } } ``` ### message\_deleted `content`, `attachments`, and `modifiedAt` are omitted; `deletedAt` is included. ```json { "requestId": "1f2e3d4c-5b6a-7980-c1d2-e3f4a5b6c7d8", "company": "your_company_id", "activityType": "Chat", "eventTimestamp": 1717238600, "eventType": "message_deleted", "data": { "message": { "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", "conversationId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789", "conversationSource": "chat", "conversationType": "channel", "senderId": 4455667, "senderType": "user", "recipientId": null, "type": "text", "isSystem": false, "createdAt": 1717238400, "deletedAt": 1717238600 } } } ``` ### Message Fields | Field | Type | Description | | :----------------- | :------------- | :----------------------------------------------------------------------------------------- | | id | string | Message ID | | conversationId | string | ID of the parent conversation | | conversationSource | string | `chat`, `helpDesk`, `publisherChat`, `connecteamTips`, `agent`, or `app` | | conversationType | string | `private`, `channel`, or `team` | | senderId | integer | Sender user ID. `-1` when there is no associated user (e.g. system message) | | senderType | string | `user`, `customPublisher`, or `agent` | | recipientId | integer / null | The other participant's user ID — only set for `private` conversations | | type | string | Message type (see below) | | content | string / null | Text content or media caption. Omitted on `message_deleted` | | attachments | array / null | Media attachments (see below). Omitted on `message_deleted` | | isSystem | boolean | `true` for system-generated messages (group created, member added, conversation locked, …) | | createdAt | integer | Creation time, Unix **seconds** | | modifiedAt | integer / null | Last edit time, Unix **seconds**. Present on `message_updated` | | deletedAt | integer / null | Deletion time, Unix **seconds**. Present on `message_deleted` | **Message **`type`** values** Content types: `text`, `image`, `image-gallery`, `video`, `file`, `audio-recording`, `gif`, `location`, `contact`, `deep-link`, `reply`, `agent-response`. System types (delivered with `isSystem: true`): `create-group`, `changed-group-name`, `add-to-group`, `left-group`, `removed-from-group`, `changed-group-description`, `lock-conversation`, `unlock-conversation`, `ticket-closed`, `ticket-reopened`, `ticket-assigned`, `ticket-unassigned`. **Attachment fields** | Field | Type | Description | | :------- | :------------- | :------------------------------------------ | | type | string | `image`, `video`, `file`, `audio`, or `gif` | | url | string | Download URL for the media | | fileName | string / null | Original file name (file attachments) | | fileSize | integer / null | File size in bytes (file attachments) | *** ## Conversation Events For `conversation_created`, `conversation_updated`, and `conversation_deleted`, `data.conversation` is a conversation object. ### conversation\_created ```json { "requestId": "3c4d5e6f-7081-92a3-b4c5-d6e7f8091122", "company": "your_company_id", "activityType": "Chat", "eventTimestamp": 1717239000, "eventType": "conversation_created", "data": { "conversation": { "id": "1a2b3c4d-5e6f-7890-abcd-ef0123456789", "title": "Store #42 \u2014 Floor Team", "type": "channel", "conversationSource": "chat", "createdBy": 4455667, "description": null, "isLocked": false, "createdAt": 1717239000 } } } ``` ### conversation\_updated Fires on title/member edits, lock/unlock, or description changes. `modifiedAt` is included; `deletedAt` is omitted. ```json { "requestId": "4d5e6f70-8192-a3b4-c5d6-e7f809112233", "company": "your_company_id", "activityType": "Chat", "eventTimestamp": 1717239100, "eventType": "conversation_updated", "data": { "conversation": { "id": "1a2b3c4d-5e6f-7890-abcd-ef0123456789", "title": "Store #42 \u2014 Floor Team (Summer)", "type": "channel", "conversationSource": "chat", "createdBy": 4455667, "description": [ { "type": "paragraph", "children": [{ "text": "Daily ops channel for the floor team." }] } ], "isLocked": false, "createdAt": 1717239000, "modifiedAt": 1717239100 } } } ``` ### conversation\_deleted `description`, `isLocked`, and `modifiedAt` are omitted; `deletedAt` is included. ```json { "requestId": "5e6f7081-92a3-b4c5-d6e7-f80911223344", "company": "your_company_id", "activityType": "Chat", "eventTimestamp": 1717239200, "eventType": "conversation_deleted", "data": { "conversation": { "id": "1a2b3c4d-5e6f-7890-abcd-ef0123456789", "title": "Store #42 \u2014 Floor Team (Summer)", "type": "channel", "conversationSource": "chat", "createdBy": 4455667, "createdAt": 1717239000, "deletedAt": 1717239200 } } } ``` ### Conversation Fields | Field | Type | Description | | :----------------- | :------------- | :-------------------------------------------------------------------------------- | | id | string | Conversation ID | | title | string / null | Conversation title. `null` for private conversations | | type | string | `private`, `channel`, or `team` | | conversationSource | string | `chat`, `helpDesk`, `publisherChat`, `connecteamTips`, `agent`, or `app` | | createdBy | integer | User ID of the creator | | description | array / null | Rich-text description blocks, or `null`. Omitted on `conversation_deleted` | | isLocked | boolean | Whether the conversation is locked (read-only). Omitted on `conversation_deleted` | | createdAt | integer | Creation time, Unix **seconds** | | modifiedAt | integer / null | Last modification time, Unix **seconds**. Present on `conversation_updated` | | deletedAt | integer / null | Deletion time, Unix **seconds**. Present on `conversation_deleted` | *** ## Field Availability per Event Some fields are intentionally omitted depending on the event. Treat a missing field the same as `null`. **Message events** | Field | message\_created | message\_updated | message\_deleted | | :---------- | :--------------: | :--------------: | :--------------: | | content | yes | yes | omitted | | attachments | yes | yes | omitted | | modifiedAt | omitted | yes | omitted | | deletedAt | omitted | omitted | yes | **Conversation events** | Field | conversation\_created | conversation\_updated | conversation\_deleted | | :---------- | :-------------------: | :-------------------: | :-------------------: | | description | yes | yes | omitted | | isLocked | yes | yes | omitted | | modifiedAt | omitted | yes | omitted | | deletedAt | omitted | omitted | yes | *** ## Delivery, Retries & Best Practices * Each event is delivered as an HTTP `POST` with a JSON body to your configured `url`. Every request carries a `User-Agent: connecteam` header. * If you set a `secretKey`, it is sent on every request in the `x-webhook-secret` header so you can verify the request came from Connecteam. * Connecteam waits up to **10 seconds** for a response. Any `2xx` is treated as success. * A `404` is treated as a permanent error and is **not** retried. Any other non-`2xx`, a timeout, or a connection error is retried up to the webhook's retry limit (3). > 👍 Integration checklist > > * **Verify the secret.** Reject requests whose `x-webhook-secret` doesn't match, and always use an HTTPS endpoint. > * **Acknowledge fast, process later.** Return `2xx` immediately and queue the payload so you never hit the 10-second timeout. > * **Be idempotent.** Retries can deliver the same event more than once — de-duplicate on `data.message.id` / `data.conversation.id` + `eventType`, or on `requestId`. > * **Don't assume ordering.** Order events yourself using `eventTimestamp` and the payload `createdAt` / `modifiedAt` timestamps (all Unix seconds). > * **Tolerate change (Beta).** Ignore unknown fields and unknown `eventType` values; treat omitted fields as `null`. > * **Filter what you don't need.** Use `conversationSource` to skip sources like `helpDesk` or `connecteamTips`, and `isSystem` to skip system messages. Scope with `entityId` to a single conversation when possible. *** ## FAQ **Why didn't I receive an event?** Chat webhooks are in Beta and gated per company. Confirm your company is enabled, the subscription is not disabled, your `eventTypes` include the event, and your endpoint returns `2xx` within 10 seconds (a `404` disables retries for that delivery). **Are private (1:1) messages included?** Yes. They have `conversationType: "private"` and message payloads include `recipientId` (the other participant). **How do I tell a bot/agent message from a person?** Check `senderType` (`agent` / `customPublisher` vs `user`) and `conversationSource` (`agent`, `app`, `publisherChat`). **Can I get the full message content on delete?** No. `message_deleted` omits `content` and `attachments`. Persist content on `message_created` / `message_updated` if you need it after deletion. *** [API Reference](https://developer.connecteam.com/reference/)