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.

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 for the full management reference (list, update, delete).

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

{
  "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)

{
  "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)

{
  "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.

{
  "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.

{
  "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

{
  "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.

{
  "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.

{
  "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