Webhook Events and Schema

This page provides sample JSON payloads for all webhook events supported by the K-LINK Customer Support Platform. Use these schemas to understand the structure of incoming webhook requests and properly handle the data in your application.

Common Webhook Structure

All webhook requests follow this basic structure:

{
  "event": "event.type",
  "timestamp": "2026-01-09T03:42:38.000000Z",
  "data": {
    // Event-specific data
  }
}

Common Fields

Field	Type	Description
`event`	String	Type of event (e.g., `contact.create`, `message.inbound`)
`timestamp`	ISO 8601	When the event occurred in UTC
`data`	Object	Event-specific payload data

Contact Events

Contact Created

Triggered when a new contact is added to your system.

Event Type: contact.create

{
  "event": "contact.create",
  "timestamp": "2026-01-09T03:42:38.000000Z",
  "data": {
    "id": "a0cad4e8-c23b-426d-95fe-75d02325d943",
    "name": "John",
    "address": "No.123, Sik Rd, Singapore",
    "channel": "whatsapp",
    "company": null,
    "companyId": null,
    "contactEmails": [
      {
        "id": "a0cad4e8-d357-42ae-aea2-0f628b826bd6",
        "email": "john@klink.cloud",
        "isPrimary": true,
        "createdAt": "2026-01-09T03:42:38.000000Z",
        "updatedAt": "2026-01-09T03:42:38.000000Z",
        "deletedAt": null
      }
    ],
    "contactPhones": [
      {
        "id": "a0cad4e8-da82-4d6b-b11c-bd3338c5e5b4",
        "phone": "06838387278",
        "isPrimary": true,
        "createdAt": "2026-01-09T03:42:38.000000Z",
        "updatedAt": "2026-01-09T03:42:38.000000Z",
        "deletedAt": null
      }
    ],
    "contactNumber": null,
    "contactProfile": null,
    "socialProfileUrl": null,
    "notes": null,
    "customFields": [],
    "tags": [
      {
        "id": "4f9cdf9d-ad8f-46d9-8e37-116b8741a7fb",
        "name": "VVIP",
        "position": 0,
        "createdAt": "2024-04-01T03:07:53.577170Z",
        "updatedAt": "2025-05-29T06:46:18.717607Z",
        "deletedAt": null
      }
    ],
    "platformContacts": [],
    "createdAt": "2026-01-09T03:42:38.000000Z",
    "updatedAt": "2026-01-09T03:42:38.000000Z",
    "deletedAt": null
  }
}

Contact Create - Field Reference

Field	Type	Description
`id`	String	Unique contact identifier
`name`	String	Contact name
`address`	String	Physical address
`channel`	String	Primary communication channel
`company`	String/null	Company name
`companyId`	String/null	Associated company ID
`contactEmails`	Array	List of email addresses with `id`, `email`, `isPrimary`, timestamps
`contactPhones`	Array	List of phone numbers with `id`, `phone`, `isPrimary`, timestamps
`contactNumber`	Integer/null	Contact reference number
`contactProfile`	String/null	Profile image URL
`socialProfileUrl`	String/null	Social media profile URL
`notes`	String/null	Internal notes
`customFields`	Array	Custom field values
`tags`	Array	Assigned tags with `id`, `name`, `position`, timestamps
`platformContacts`	Array	Platform-specific contact data
`createdAt`	ISO 8601	Contact creation timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`deletedAt`	ISO 8601/null	Soft delete timestamp

Contact Updated

Triggered when a contact's information is modified.

Event Type: contact.update

{
  "event": "contact.update",
  "timestamp": "2026-01-09T03:42:38.000000Z",
  "data": {
    "id": "a0cad4e8-c23b-426d-95fe-75d02325d943",
    "name": "John",
    "address": "No.123, Sik Rd, Singapore",
    "channel": "whatsapp",
    "company": null,
    "companyId": null,
    "contactEmails": [
      {
        "id": "a0cad4e8-d357-42ae-aea2-0f628b826bd6",
        "email": "john@klink.cloud",
        "isPrimary": true,
        "createdAt": "2026-01-09T03:42:38.000000Z",
        "updatedAt": "2026-01-09T03:42:38.000000Z",
        "deletedAt": null
      }
    ],
    "contactPhones": [
      {
        "id": "a0cad4e8-da82-4d6b-b11c-bd3338c5e5b4",
        "phone": "06838387278",
        "isPrimary": true,
        "createdAt": "2026-01-09T03:42:38.000000Z",
        "updatedAt": "2026-01-09T03:42:38.000000Z",
        "deletedAt": null
      }
    ],
    "contactNumber": 54432,
    "contactProfile": null,
    "socialProfileUrl": null,
    "notes": null,
    "customFields": [],
    "tags": [
      {
        "id": "4f9cdf9d-ad8f-46d9-8e37-116b8741a7fb",
        "name": "VVIP",
        "position": 0,
        "createdAt": "2024-04-01T03:07:53.577170Z",
        "updatedAt": "2025-05-29T06:46:18.717607Z",
        "deletedAt": null
      }
    ],
    "platformContacts": [],
    "createdAt": "2026-01-09T03:42:38.000000Z",
    "updatedAt": "2026-01-09T03:42:38.000000Z",
    "deletedAt": null
  }
}

Room Events

Room Solved/Closed

Triggered when a room is solved or closed by an agent.

Event Type: room.closed

{
  "event": "room.closed",
  "timestamp": "2026-04-21T14:49:55Z",
  "data": {
    "id": "ea5ed3fe-4de8-4d44-867f-c104636a313a",
    "status": 1,
    "direction": "incoming",
    "actor": {
      "id": "9984c805-fed0-4011-a163-c3374974c3ea",
      "name": "Nang Hmu",
      "email": "nanghmu@demo.klink.cloud",
      "createdAt": "2024-06-25T08:18:59.442Z",
      "updatedAt": "2026-03-11T12:00:23.728Z"
    },
    "assignee": {
      "id": "9984c805-fed0-4011-a163-c3374974c3ea",
      "name": "Nang Hmu",
      "email": "nanghmu@demo.klink.cloud",
      "createdAt": "2024-06-25T08:18:59.442Z",
      "updatedAt": "2026-03-11T12:00:23.728Z"
    },
    "channel": {
      "id": "4da39031-79b0-4fec-9800-4d9199ec82d5",
      "name": "Meow Diary",
      "brandName": "Meow Diary",
      "type": "messenger",
      "platformId": "555104637677266",
      "status": true,
      "createdAt": "2025-12-15T05:55:14.275Z",
      "updatedAt": "2026-03-05T15:48:55.859Z"
    },
    "platformContact": [
      {
        "id": "94262e75-84a5-49b7-aa5a-c1c664a4b4af",
        "contactId": "2a26a0e7-fde9-4a4d-9955-d76c5fe769f8",
        "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
        "type": "messenger",
        "socialPlatformId": "8793154924097941",
        "metadata": {
          "id": "8793154924097941",
          "name": "Jim Jim",
          "profileUrl": "https://platform-lookaside.fbsbx.com/...",
          "socialPlatformId": "8793154924097941",
          "contactFolderName": "demo/profile"
        },
        "contact": {
          "id": "2a26a0e7-fde9-4a4d-9955-d76c5fe769f8",
          "name": "Jim Jim",
          "channel": "messenger",
          "contactNumber": 8284,
          "createdAt": "2025-12-15T05:56:06.104Z"
        }
      }
    ],
    "closedAt": "2026-04-21T14:49:51Z",
    "createdAt": "2026-04-21T14:47:35.073Z",
    "updatedAt": "2026-04-21T14:49:51.000Z",
    "lastMessage": "Hello Jim Jim...",
    "lastMessageAt": "2026-04-21T14:47:42.168Z"
  }
}

Room Solved - Field Reference

Field	Type	Description
`id`	String	Unique room/conversation identifier
`status`	Integer	Room status (1 = closed/solved)
`direction`	String	Initial direction of the room (`incoming` or `outgoing`)
`actor`	Object	The agent who performed the solve action
`assignee`	Object	The agent assigned to the room when closed
`channel`	Object	Sanitized channel data
`platformContact`	Array	Associated platform contacts and metadata
`closedAt`	ISO 8601	When the room was officially closed
`createdAt`	ISO 8601	When the room was first created
`updatedAt`	ISO 8601	Last modification timestamp

Room Assigned

Triggered when a room is assigned or when assignee is updated.

Event Type: room.assigned

{
  "event": "room.assigned",
  "timestamp": "2026-05-11T09:32:00.000000Z",
  "data": {
    "id": "ea5ed3fe-4de8-4d44-867f-c104636a313a",
    "createdAt": "2026-05-11T09:30:00.000Z",
    "updatedAt": "2026-05-11T09:32:00.000Z",
    "deletedAt": null,
    "lastMessage": "I need help with my order",
    "actorId": "9984c805-fed0-4011-a163-c3374974c3ea",
    "assigneeId": "9984c805-fed0-4011-a163-c3374974c3ea",
    "platformContactId": "94262e75-84a5-49b7-aa5a-c1c664a4b4af",
    "automationQueueId": "713214a1-b845-42f1-9b1b-789a71239c4d",
    "actorType": "user",
    "handledTime": 120000,
    "closedAt": null,
    "unreadCount": 1,
    "firstResponseAt": "2026-05-11T09:31:00.000Z",
    "firstResponseTime": 60000,
    "firstRepliedAt": null,
    "firstRepliedTime": null,
    "isLatest": true,
    "direction": "incoming",
    "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
    "status": 1,
    "lastMessageAt": "2026-05-11T09:30:05.000Z",
    "isBotRoom": false,
    "metadata": {},
    "telegramBusinessConnectionId": null,
    "isGroup": false,
    "csatStatus": null,
    "cxlog": {
      "id": "313111f6-3c40-4a01-b9ca-be56f4cd265f",
      "caseId": 13316,
      "channel": "messenger",
      "direction": "inbound",
      "contactId": "2a26a0e7-fde9-4a4d-9955-d76c5fe769f8",
      "agentId": "9984c805-fed0-4011-a163-c3374974c3ea",
      "firstAssigneeId": "9984c805-fed0-4011-a163-c3374974c3ea",
      "entityName": "room",
      "entityId": "ea5ed3fe-4de8-4d44-867f-c104636a313a",
      "startedDate": "2026-05-11T09:30:00.000Z",
      "firstResponseTime": 60000,
      "firstRepliedTime": null,
      "createdAt": "2026-05-11T09:30:00.000Z",
      "updatedAt": "2026-05-11T09:32:00.000Z",
      "wrapUpFormId": null,
      "deletedAt": null
    },
    "channel": {
      "id": "4da39031-79b0-4fec-9800-4d9199ec82d5",
      "name": "Meow Diary",
      "brandName": "Meow Diary",
      "type": "messenger",
      "platformId": "555104637677266",
      "status": true,
      "createdAt": "2025-12-15T05:55:14.275Z",
      "updatedAt": "2026-03-05T15:48:55.859Z",
      "metadata": {},
      "csatPreferences": {}
    },
    "resumeLabel": null,
    "platformContact": [
      {
        "id": "94262e75-84a5-49b7-aa5a-c1c664a4b4af",
        "createdAt": "2025-12-15T05:56:06.104Z",
        "updatedAt": "2025-12-15T05:56:06.104Z",
        "deletedAt": null,
        "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
        "contactId": "2a26a0e7-fde9-4a4d-9955-d76c5fe769f8",
        "socialPlatformId": "8793154924097941",
        "type": "messenger",
        "metadata": {
          "id": "8793154924097941",
          "name": "Jim Jim",
          "profileUrl": "https://platform-lookaside.fbsbx.com/...",
          "socialPlatformId": "8793154924097941",
          "contactFolderName": "demo/profile"
        },
        "contact": {}
      }
    ],
    "assignee": {
      "id": "9984c805-fed0-4011-a163-c3374974c3ea",
      "createdAt": "2024-06-25T08:18:59.442Z",
      "updatedAt": "2026-03-11T12:00:23.728Z",
      "deletedAt": null,
      "name": "Nang Hmu",
      "email": "nanghmu@demo.klink.cloud",
      "phone": null,
      "provider": null,
      "providerId": null
    },
    "actor": {
      "id": "9984c805-fed0-4011-a163-c3374974c3ea",
      "createdAt": "2024-06-25T08:18:59.442Z",
      "updatedAt": "2026-03-11T12:00:23.728Z",
      "deletedAt": null,
      "name": "Nang Hmu",
      "email": "nanghmu@demo.klink.cloud",
      "phone": null,
      "provider": null,
      "providerId": null
    },
    "isAiAgentRoom": false,
    "subject": null,
    "thread_id": null,
    "participants": []
  }
}

Message Events

Inbound Message Received

Triggered when a new message is received from a customer.

Event Type: message.inbound

{
  "event": "message.inbound",
  "timestamp": "2026-01-09T07:05:42.378992489Z",
  "data": {
    "id": "706feaae-8e59-48c7-8784-33541e954c6b",
    "type": "text",
    "direction": "incoming",
    "message": "Hi there",
    "createdAt": "2026-01-09T07:05:33.027Z",
    "updatedAt": "2026-01-09T07:05:33.027Z",
    "editedAt": null,
    "isEdited": false,
    "platformMessageId": "m_doklox4t_bvRT60GJhQbji0VXumaYr7fHlifZ2Y4c5c-lSGsIQwFDjsNd5Uu8DaAyx2praGmIIa_zFwqswpEYQ",
    "platformId": "555104637677266",
    "roomId": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
    "senderId": null,
    "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
    "attachments": null,
    "readAt": null,
    "previewUrl": "",
    "locale": "",
    "template": null,
    "replyPlatformMessageId": null,
    "repliedMessage": null,
    "replyReaction": null,
    "metadata": {},
    "room": {
      "id": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
      "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
      "platformContactId": "7ea470eb-6e44-4f9d-aedd-e0330cb48235",
      "actorId": "8cde99fe-6054-4859-a104-d6a862afd811",
      "actor": {
        "id": "8cde99fe-6054-4859-a104-d6a862afd811",
        "name": "Hay Marn Sue",
        "email": "asue00630@gmail.com",
        "phone": "09980711651",
        "createdAt": "2023-11-17T09:12:08.801665Z",
        "updatedAt": "2025-12-24T09:16:25.826122Z",
        "deletedAt": null
      },
      "assigneeId": "8cde99fe-6054-4859-a104-d6a862afd811",
      "channel": {
        "id": "4da39031-79b0-4fec-9800-4d9199ec82d5",
        "name": "Testing Channel",
        "brandName": "Testing Channel",
        "type": "messenger",
        "platformId": "555104637677266",
        "status": true,
        "connectedUserId": "122131365806382390",
        "connectedUserName": "Jim Jim",
        "createdAt": "2025-12-15T05:55:14.275542Z",
        "updatedAt": "2025-12-15T05:55:14.275542Z",
        "deletedAt": null
      },
      "platformContact": [
        {
          "id": "7ea470eb-6e44-4f9d-aedd-e0330cb48235",
          "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
          "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
          "type": "messenger",
          "socialPlatformId": "25084025951204536",
          "metadata": {
            "id": "25084025951204536",
            "name": "John Hopper",
            "email": "",
            "profileUrl": "https://platform-lookaside.fbsbx.com/platform/profilepic/?psid=25084025951204536",
            "socialPlatformId": "25084025951204536",
            "contactFolderName": "demo/profile"
          },
          "createdAt": "2025-12-18T03:59:07.599301Z",
          "updatedAt": "2025-12-18T03:59:07.599301Z",
          "deletedAt": null
        }
      ],
      "direction": "incoming",
      "status": 1,
      "isLatest": true,
      "isBotRoom": false,
      "isGroup": false,
      "createdAt": "2025-12-18T03:59:03.39Z",
      "updatedAt": "2026-01-09T07:05:33.027Z",
      "firstResponseAt": "2025-12-18T04:38:13Z",
      "firstResponseTime": 0,
      "firstRepliedAt": null,
      "firstRepliedTime": null,
      "lastMessage": "Hi there",
      "lastMessageAt": "2026-01-09T07:05:33.027Z",
      "unreadCount": 1,
      "closedAt": null,
      "metadata": {}
    },
    "deletedAt": null
  }
}

Inbound Message - Field Reference

Field	Type	Description
`id`	String	Unique message identifier
`type`	String	Message type (e.g., `text`, `image`, `file`)
`direction`	String	`incoming` for inbound messages
`message`	String	Message body content
`createdAt`	ISO 8601	Message timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`isEdited`	Boolean	Whether message was edited
`platformMessageId`	String	Platform-specific message ID
`platformId`	String	Platform account/page ID
`roomId`	String	Conversation room ID
`senderId`	String/null	ID of the sender (null for incoming)
`contactId`	String/null	Associated contact ID
`attachments`	Array/null	File attachments
`readAt`	ISO 8601/null	When message was read
`metadata`	Object	Platform-specific metadata and payload
`room`	Object	Associated room/conversation data
`deletedAt`	ISO 8601/null	Soft delete timestamp

Outbound Message Sent

Triggered when a message is sent to a customer.

Event Type: message.outbound

{
  "event": "message.outbound",
  "timestamp": "2026-01-09T07:07:38.128247406Z",
  "data": {
    "id": "c0ab2468-f630-4c75-9b8c-ba63df930b19",
    "type": "text",
    "direction": "outgoing",
    "message": "It is outbound message",
    "createdAt": "2026-01-09T07:07:34.699380286Z",
    "updatedAt": "2026-01-09T07:07:34.699380286Z",
    "editedAt": null,
    "isEdited": false,
    "platformMessageId": "m_ZDrWvRbfp_RwWyfAwc936S0VXumaYr7fHlifZ2Y4c5fYVVwxGqQYTwsZFdiZ6q4P2YIZxuB5Gr5395-X7jsZuA",
    "platformId": "555104637677266",
    "roomId": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
    "senderId": "d762a2be-ea27-49ff-b42c-03992953ab67",
    "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
    "attachments": null,
    "readAt": null,
    "previewUrl": "",
    "locale": "",
    "template": null,
    "replyPlatformMessageId": null,
    "repliedMessage": null,
    "replyReaction": null,
    "metadata": {},
    "room": {
      "id": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
      "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
      "platformContactId": "7ea470eb-6e44-4f9d-aedd-e0330cb48235",
      "actorId": "d762a2be-ea27-49ff-b42c-03992953ab67",
      "actor": {
        "id": "d762a2be-ea27-49ff-b42c-03992953ab67",
        "name": "John Hopper",
        "email": "johnhopper@gmail.co",
        "phone": "",
        "createdAt": "2023-11-22T18:40:10.632745Z",
        "updatedAt": "2025-05-01T04:04:12.691716Z",
        "deletedAt": null
      },
      "assigneeId": "d762a2be-ea27-49ff-b42c-03992953ab67",
      "assignee": {
        "id": "d762a2be-ea27-49ff-b42c-03992953ab67",
        "name": "John Hopper",
        "email": "johnhopper@gmail.co",
        "phone": "",
        "createdAt": "2023-11-22T18:40:10.632745Z",
        "updatedAt": "2025-05-01T04:04:12.691716Z",
        "deletedAt": null
      },
      "channel": {
        "id": "4da39031-79b0-4fec-9800-4d9199ec82d5",
        "name": "Testing Channel",
        "brandName": "Testing Channel",
        "type": "messenger",
        "platformId": "555104637677266",
        "status": true,
        "connectedUserId": "122131365806382390",
        "connectedUserName": "Jim Jim",
        "createdAt": "2025-12-15T05:55:14.275542Z",
        "updatedAt": "2025-12-15T05:55:14.275542Z",
        "deletedAt": null
      },
      "platformContact": [
        {
          "id": "7ea470eb-6e44-4f9d-aedd-e0330cb48235",
          "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
          "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
          "type": "messenger",
          "socialPlatformId": "25084025951204536",
          "metadata": {
            "id": "25084025951204536",
            "name": "John Hopper",
            "email": "",
            "profileUrl": "https://platform-lookaside.fbsbx.com/platform/profilepic/?psid=25084025951204536",
            "socialPlatformId": "25084025951204536",
            "contactFolderName": "demo/profile"
          },
          "createdAt": "2025-12-18T03:59:07.599301Z",
          "updatedAt": "2025-12-18T03:59:07.599301Z",
          "deletedAt": null
        }
      ],
      "cxLog": {
        "id": "313111f6-3c40-4a01-b9ca-be56f4cd265f",
        "caseId": 13315,
        "channel": "messenger",
        "direction": "inbound",
        "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
        "agentId": "d762a2be-ea27-49ff-b42c-03992953ab67",
        "firstAssigneeId": "8cde99fe-6054-4859-a104-d6a862afd811",
        "entityName": "room",
        "entityId": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
        "startedDate": "2025-12-18T03:59:03.39Z",
        "firstResponseTime": 0,
        "firstRepliedTime": null,
        "createdAt": "2025-12-18T03:59:08.628432Z",
        "updatedAt": "2026-01-09T07:07:18Z",
        "wrapUpFormId": "f71c0570-f92e-426e-9017-6c64cb75bc0b",
        "deletedAt": null
      },
      "direction": "incoming",
      "status": 1,
      "isLatest": true,
      "isBotRoom": false,
      "isGroup": false,
      "createdAt": "2025-12-18T03:59:03.39Z",
      "updatedAt": "2026-01-09T07:07:34.69938Z",
      "firstResponseAt": "2025-12-18T04:38:13Z",
      "firstResponseTime": 0,
      "firstRepliedAt": "2026-01-09T07:07:37.085254Z",
      "firstRepliedTime": 1912113,
      "lastMessage": "It is outbound message",
      "lastMessageAt": "2026-01-09T07:05:33.027Z",
      "unreadCount": 0,
      "closedAt": null,
      "metadata": {}
    },
    "deletedAt": null
  }
}

Outbound Message - Field Reference

Field	Type	Description
`id`	String	Unique message identifier
`type`	String	Message type (e.g., `text`, `image`, `file`)
`direction`	String	`outgoing` for outbound messages
`message`	String	Message body content
`createdAt`	ISO 8601	Message timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`isEdited`	Boolean	Whether message was edited
`platformMessageId`	String	Platform-specific message ID
`platformId`	String	Platform account/page ID
`roomId`	String	Conversation room ID
`senderId`	String	ID of the agent/user who sent the message
`contactId`	String	Associated contact ID
`attachments`	Array/null	File attachments
`readAt`	ISO 8601/null	When message was read by recipient
`metadata`	Object	Custom metadata (can be empty)
`replyPlatformMessageId`	String/null	ID of replied message on platform
`repliedMessage`	Object/null	Replied message content
`replyReaction`	String/null	Reaction to message
`room`	Object	Associated room/conversation data with metrics and cxLog
`deletedAt`	ISO 8601/null	Soft delete timestamp

New Message Comment

Triggered when an agent adds an internal comment or note mentioning a user.

Event Type: message.comment

{
  "event": "message.comment",
  "timestamp": "2026-04-21T13:29:35Z",
  "data": {
    "id": "706feaae-8e59-48c7-8784-33541e954c6b",
    "type": "text",
    "direction": "outgoing",
    "message": "Agent mentioned you in a comment: Please check this issue.",
    "createdAt": "2026-04-21T13:29:30Z",
    "updatedAt": "2026-04-21T13:29:30Z",
    "roomId": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
    "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
    "room": {
      "id": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
      "channel": {
        "id": "4da39031-79b0-4fec-9800-4d9199ec82d5",
        "name": "Testing Channel",
        "type": "messenger"
      }
    }
  }
}

Message Comment - Field Reference

Field	Type	Description
`id`	String	Unique comment identifier
`type`	String	Always `text` for comments
`direction`	String	Always `outgoing` for agent comments
`message`	String	The content of the comment
`roomId`	String	Associated room ID
`contactId`	String	Associated contact ID
`room`	Object	Minimal room context (sanitized)

Room Object Reference

The room object contains conversation context and appears in message events:

Field	Type	Description
`id`	String	Unique room/conversation ID
`channelId`	String	Associated channel ID
`platformContactId`	String	Platform contact identifier
`assigneeId`	String/null	Assigned agent/user ID
`direction`	String	`incoming` or `outgoing`
`status`	Integer	Room status (1 = active)
`isLatest`	Boolean	Whether this is the latest conversation
`createdAt`	ISO 8601	Conversation creation timestamp
`updatedAt`	ISO 8601	Last activity timestamp
`firstRepliedAt`	ISO 8601/null	When first response was sent
`firstRepliedTime`	Integer	Milliseconds to first reply
`firstResponseAt`	ISO 8601/null	When first message was received
`firstResponseTime`	Integer	Milliseconds to first response
`lastMessage`	String	Last message text
`lastMessageAt`	ISO 8601	Timestamp of last message
`unreadCount`	Integer	Number of unread messages

Email Object Reference

Appears in the contactEmails array:

Field	Type	Description
`id`	String	Unique email ID
`email`	String	Email address
`isPrimary`	Boolean	Primary email flag
`createdAt`	ISO 8601	Creation timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`deletedAt`	ISO 8601/null	Soft delete timestamp

Phone Object Reference

Appears in the contactPhones array:

Field	Type	Description
`id`	String	Unique phone ID
`phone`	String	Phone number
`isPrimary`	Boolean	Primary phone flag
`createdAt`	ISO 8601	Creation timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`deletedAt`	ISO 8601/null	Soft delete timestamp

Tag Object Reference

Appears in the tags array:

Field	Type	Description
`id`	String	Unique tag ID
`name`	String	Tag name
`position`	Integer	Display position/order
`createdAt`	ISO 8601	Creation timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`deletedAt`	ISO 8601/null	Soft delete timestamp

Best Practices for Handling Payloads

Validate Signature: Always verify webhook signatures before processing payload data
Handle Null Values: Optional fields may be null; use defensive programming
Parse Timestamps: All timestamps are in ISO 8601 format with UTC timezone
Store Event IDs: Track processed message IDs to avoid duplicate processing
Idempotency: Use clientRequestId for outbound messages to detect retries
Room Context: Use room object data for conversation metrics and status
Custom Fields: The customFields array structure depends on your workspace configuration
Metadata: Platform-specific data is nested in the metadata object; parse based on channel type

Testing with Sample Data

To test your webhook handler without live events, you can:

Copy the sample payloads above
Test your signature verification with these payloads
Ensure your endpoint correctly parses and processes the data
Verify error handling for edge cases
Validate timestamp parsing and timezone handling

For more information about webhook setup, refer to the Webhook Setup documentation.