Skip to main content

Websocket Events

To subscribe to various events happening in your chatwoot installation in realtime, You can connect to the Chatwoot WebSockets. Chatwoot WebSockets connection can be made at the following URL

<your installation url>/cable

Authenticating your WebSocket connection#

You will start receiving the events directed towards your customer after subscribing using the customer pubsub_token. You will start receiving the events directed towards your agents after subscribing using the user pubsub_token.

Also refer Client APIs to build real time customer facing integrations using chatwoot.

Example#

const connection = new WebSocket('ws://localhost:3000/cable');connection.send(JSON.stringify({ command:"subscribe", identifier: "{\"channel\":\"RoomChannel\",\"pubsub_token\":\""+ customer_pubsub_token+"\"}" }));

Publishing Presence to the websocket server#

Publish the appropriate payloads back to the websocket server at 30 second intervals to keep the online presence updated in chatwoot.

Agent presence#

{    "command": "message",    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "data": "{\"action\":\"update_presence\"}"}

Contact Presence#

 {    "command": "message",    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\"}",    "data": "{\"action\":\"update_presence\"}"}

Websocket Event payload samples#

Here are example payloads of various websocket events in chatwoot

conversation_created#

Available for: Agents

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "conversation.created",        "data": {            "additional_attributes": {                "browser": {                    "device_name": "Unknown",                    "browser_name": "Chrome",                    "platform_name": "macOS",                    "browser_version": "92.0.4515.107",                    "platform_version": "10.15.7"                },                "referer": "http://localhost:3000/widget_tests",                "initiated_at": {                    "timestamp": "Fri Jul 23 2021 22:43:14 GMT+0530 (India Standard Time)"                }            },            "can_reply": true,            "channel": "Channel::WebWidget",            "id": 7,            "inbox_id": 1,            "contact_inbox": {                "id": 8,                "contact_id": 10,                "inbox_id": 1,                "source_id": "4f5c785e-abba-4527-82a9-bbdb2117c167",                "created_at": "2021-07-23T17:08:53.771Z",                "updated_at": "2021-07-23T17:08:53.771Z",                "hmac_verified": false            },            "messages": [],            "meta": {                "sender": {                    "additional_attributes": {},                    "custom_attributes": {},                    "email": null,                    "id": 10,                    "identifier": null,                    "name": "white-shadow-394",                    "phone_number": null,                    "pubsub_token": "token",                    "thumbnail": "",                    "type": "contact"                },                "assignee": {                    "id": 1,                    "name": "John",                    "available_name": "John",                    "avatar_url": "https://www.gravatar.com/avatar/0d722ac7bc3b3c92c030d0da9690d981?d=404",                    "type": "user",                    "availability_status": "online"                }            },            "status": "open",            "unread_count": 0,            "agent_last_seen_at": 0,            "contact_last_seen_at": 0,            "timestamp": 1627060394,            "account_id": 1        }    }}

conversation_read#

Available for: Agents

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "conversation.read",        "data": {            "additional_attributes": {                "browser": {                    "device_name": "Unknown",                    "browser_name": "Chrome",                    "platform_name": "macOS",                    "browser_version": "92.0.4515.107",                    "platform_version": "10.15.7"                },                "referer": "http://localhost:3000/widget_tests",                "initiated_at": {                    "timestamp": "Fri Jul 23 2021 22:58:28 GMT+0530 (India Standard Time)"                }            },            "can_reply": true,            "channel": "Channel::WebWidget",            "id": 9,            "inbox_id": 1,            "contact_inbox": {                "id": 11,                "contact_id": 12,                "inbox_id": 1,                "source_id": "d45c0005-2429-4079-bbc2-6ade8bdb2866",                "created_at": "2021-07-23T17:28:24.996Z",                "updated_at": "2021-07-23T17:28:40.864Z",                "hmac_verified": false            },            "messages": [{                "id": 117,                "content": "helllo",                "account_id": 1,                "inbox_id": 1,                "conversation_id": 9,                "message_type": 1,                "created_at": 1627061456,                "updated_at": "2021-07-23T17:30:56.000Z",                "private": false,                "status": "sent",                "source_id": null,                "content_type": null,                "content_attributes": {},                "sender_type": "User",                "sender_id": 1,                "external_source_ids": {},                "sender": {                    "id": 1,                    "name": "John",                    "available_name": "John",                    "avatar_url": "https://www.gravatar.com/avatar/0d722ac7bc3b3c92c030d0da9690d981?d=404",                    "type": "user",                    "availability_status": "online"                }            }],            "meta": {                "sender": {                    "additional_attributes": {},                    "custom_attributes": {},                    "email": "jane@acme.inc",                    "id": 12,                    "identifier": null,                    "name": "jane",                    "phone_number": null,                    "pubsub_token": "token",                    "thumbnail": "https://www.gravatar.com/avatar/526692031d4bb623b36ae4e340260f13?d=404",                    "type": "contact"                },                "assignee": {                    "id": 1,                    "name": "John",                    "available_name": "John",                    "avatar_url": "https://www.gravatar.com/avatar/0d722ac7bc3b3c92c030d0da9690d981?d=404",                    "type": "user",                    "availability_status": "online"                }            },            "status": "open",            "unread_count": 0,            "agent_last_seen_at": 1627061456,            "contact_last_seen_at": 1627061467,            "timestamp": 1627061456,            "account_id": 1        }    }}

message_created#

Available for: Agents & Contacts

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "message.created",        "data": {            "id": 106,            "content": "hi",            "account_id": 1,            "inbox_id": 1,            "conversation_id": 7,            "message_type": 0,            "created_at": 1627060394,            "updated_at": "2021-07-23T17:13:14.000Z",            "private": false,            "status": "sent",            "source_id": null,            "content_type": "text",            "content_attributes": {},            "sender_type": "Contact",            "sender_id": 10,            "external_source_ids": {},            "sender": {                "additional_attributes": {},                "custom_attributes": {},                "email": null,                "id": 10,                "identifier": null,                "name": "white-shadow-394",                "phone_number": null,                "pubsub_token": "token",                "thumbnail": "",                "type": "contact"            }        }    }}

message_updated#

Available for: Agents & Contacts

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "message.updated",        "data": {            "id": 111,            "content_type": "input_email",            "content_attributes": {                "submitted_email": "jane@acme.inc"            },            "account_id": 1,            "inbox_id": 1,            "conversation_id": 8,            "content": "Get notified by email",            "message_type": 3,            "created_at": 1627060984,            "updated_at": "2021-07-23T17:23:14.000Z",            "private": false,            "status": "sent",            "source_id": null,            "sender_type": null,            "sender_id": null,            "external_source_ids": {}        }    }}

conversation_status_changed#

Available for: Agents & Contacts

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "conversation.status_changed",        "data": {            "additional_attributes": {                "browser": {                    "device_name": "Unknown",                    "browser_name": "Chrome",                    "platform_name": "macOS",                    "browser_version": "92.0.4515.107",                    "platform_version": "10.15.7"                },                "referer": "http://localhost:3000/widget_tests",                "initiated_at": {                    "timestamp": "Fri Jul 23 2021 22:43:14 GMT+0530 (India Standard Time)"                }            },            "can_reply": true,            "channel": "Channel::WebWidget",            "id": 7,            "inbox_id": 1,            "contact_inbox": {                "id": 8,                "contact_id": 10,                "inbox_id": 1,                "source_id": "4f5c785e-abba-4527-82a9-bbdb2117c167",                "created_at": "2021-07-23T17:08:53.771Z",                "updated_at": "2021-07-23T17:08:53.771Z",                "hmac_verified": false            },            "messages": [{                "id": 107,                "content": "sfdfd",                "account_id": 1,                "inbox_id": 1,                "conversation_id": 7,                "message_type": 0,                "created_at": 1627060756,                "updated_at": "2021-07-23T17:19:16.000Z",                "private": false,                "status": "sent",                "source_id": null,                "content_type": "text",                "content_attributes": {},                "sender_type": "Contact",                "sender_id": 10,                "external_source_ids": {},                "sender": {                    "additional_attributes": {},                    "custom_attributes": {},                    "email": null,                    "id": 10,                    "identifier": null,                    "name": "white-shadow-394",                    "phone_number": null,                    "pubsub_token": "token",                    "thumbnail": "",                    "type": "contact"                }            }],            "meta": {                "sender": {                    "additional_attributes": {},                    "custom_attributes": {},                    "email": null,                    "id": 10,                    "identifier": null,                    "name": "white-shadow-394",                    "phone_number": null,                    "pubsub_token": "token",                    "thumbnail": "",                    "type": "contact"                },                "assignee": {                    "id": 1,                    "name": "John",                    "available_name": "John",                    "avatar_url": "https://www.gravatar.com/avatar/0d722ac7bc3b3c92c030d0da9690d981?d=404",                    "type": "user",                    "availability_status": "offline"                }            },            "status": "pending",            "unread_count": 0,            "agent_last_seen_at": 1627060756,            "contact_last_seen_at": 0,            "timestamp": 1627060756,            "account_id": 1        }    }}

conversation_typing_on#

Available for: Agents & Contacts

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "conversation.typing_on",        "data": {            "conversation": {                "additional_attributes": {                    "browser": {                        "device_name": "Unknown",                        "browser_name": "Chrome",                        "platform_name": "macOS",                        "browser_version": "92.0.4515.107",                        "platform_version": "10.15.7"                    },                    "referer": "http://localhost:3000/widget_tests",                    "initiated_at": {                        "timestamp": "Fri Jul 23 2021 22:43:14 GMT+0530 (India Standard Time)"                    }                },                "can_reply": true,                "channel": "Channel::WebWidget",                "id": 7,                "inbox_id": 1,                "contact_inbox": {                    "id": 8,                    "contact_id": 10,                    "inbox_id": 1,                    "source_id": "4f5c785e-abba-4527-82a9-bbdb2117c167",                    "created_at": "2021-07-23T17:08:53.771Z",                    "updated_at": "2021-07-23T17:08:53.771Z",                    "hmac_verified": false                },                "messages": [{                    "id": 106,                    "content": "hi",                    "account_id": 1,                    "inbox_id": 1,                    "conversation_id": 7,                    "message_type": 0,                    "created_at": 1627060394,                    "updated_at": "2021-07-23T17:13:14.000Z",                    "private": false,                    "status": "sent",                    "source_id": null,                    "content_type": "text",                    "content_attributes": {},                    "sender_type": "Contact",                    "sender_id": 10,                    "external_source_ids": {},                    "sender": {                        "additional_attributes": {},                        "custom_attributes": {},                        "email": null,                        "id": 10,                        "identifier": null,                        "name": "white-shadow-394",                        "phone_number": null,                        "pubsub_token": "token",                        "thumbnail": "",                        "type": "contact"                    }                }],                "meta": {                    "sender": {                        "additional_attributes": {},                        "custom_attributes": {},                        "email": null,                        "id": 10,                        "identifier": null,                        "name": "white-shadow-394",                        "phone_number": null,                        "pubsub_token": "token",                        "thumbnail": "",                        "type": "contact"                    },                    "assignee": {                        "id": 1,                        "name": "John",                        "available_name": "John",                        "avatar_url": "https://www.gravatar.com/avatar/0d722ac7bc3b3c92c030d0da9690d981?d=404",                        "type": "user",                        "availability_status": "online"                    }                },                "status": "open",                "unread_count": 0,                "agent_last_seen_at": 1627060549,                "contact_last_seen_at": 0,                "timestamp": 1627060394            },            "user": {                "additional_attributes": {},                "custom_attributes": {},                "email": null,                "id": 10,                "identifier": null,                "name": "white-shadow-394",                "phone_number": null,                "pubsub_token": "token",                "thumbnail": "",                "type": "contact"            },            "account_id": 1        }    }}

conversation_typing_off#

Available for: Agents & Contacts

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "conversation.typing_off",        "data": {            "conversation": {                "additional_attributes": {                    "browser": {                        "device_name": "Unknown",                        "browser_name": "Chrome",                        "platform_name": "macOS",                        "browser_version": "92.0.4515.107",                        "platform_version": "10.15.7"                    },                    "referer": "http://localhost:3000/widget_tests",                    "initiated_at": {                        "timestamp": "Fri Jul 23 2021 22:43:14 GMT+0530 (India Standard Time)"                    }                },                "can_reply": true,                "channel": "Channel::WebWidget",                "id": 7,                "inbox_id": 1,                "contact_inbox": {                    "id": 8,                    "contact_id": 10,                    "inbox_id": 1,                    "source_id": "4f5c785e-abba-4527-82a9-bbdb2117c167",                    "created_at": "2021-07-23T17:08:53.771Z",                    "updated_at": "2021-07-23T17:08:53.771Z",                    "hmac_verified": false                },                "messages": [{                    "id": 106,                    "content": "hi",                    "account_id": 1,                    "inbox_id": 1,                    "conversation_id": 7,                    "message_type": 0,                    "created_at": 1627060394,                    "updated_at": "2021-07-23T17:13:14.000Z",                    "private": false,                    "status": "sent",                    "source_id": null,                    "content_type": "text",                    "content_attributes": {},                    "sender_type": "Contact",                    "sender_id": 10,                    "external_source_ids": {},                    "sender": {                        "additional_attributes": {},                        "custom_attributes": {},                        "email": null,                        "id": 10,                        "identifier": null,                        "name": "white-shadow-394",                        "phone_number": null,                        "pubsub_token": "token",                        "thumbnail": "",                        "type": "contact"                    }                }],                "meta": {                    "sender": {                        "additional_attributes": {},                        "custom_attributes": {},                        "email": null,                        "id": 10,                        "identifier": null,                        "name": "white-shadow-394",                        "phone_number": null,                        "pubsub_token": "token",                        "thumbnail": "",                        "type": "contact"                    },                    "assignee": {                        "id": 1,                        "name": "John",                        "available_name": "John",                        "avatar_url": "https://www.gravatar.com/avatar/0d722ac7bc3b3c92c030d0da9690d981?d=404",                        "type": "user",                        "availability_status": "online"                    }                },                "status": "open",                "unread_count": 0,                "agent_last_seen_at": 1627060549,                "contact_last_seen_at": 0,                "timestamp": 1627060394            },            "user": {                "additional_attributes": {},                "custom_attributes": {},                "email": null,                "id": 10,                "identifier": null,                "name": "white-shadow-394",                "phone_number": null,                "pubsub_token": "token",                "thumbnail": "",                "type": "contact"            },            "account_id": 1        }    }}

assignee_changed#

Available for: Agents

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "assignee.changed",        "data": {            "additional_attributes": {                "browser": {                    "browser_name": "Chrome",                    "browser_version": "92.0.4515.107",                    "device_name": "Unknown",                    "platform_name": "macOS",                    "platform_version": "10.15.7"                },                "referer": "http://localhost:3000/widget_tests",                "initiated_at": {                    "timestamp": "Fri Jul 23 2021 22:43:14 GMT+0530 (India Standard Time)"                }            },            "can_reply": true,            "channel": "Channel::WebWidget",            "id": null,            "inbox_id": 1,            "contact_inbox": {                "id": 8,                "contact_id": 10,                "inbox_id": 1,                "source_id": "4f5c785e-abba-4527-82a9-bbdb2117c167",                "created_at": "2021-07-23T17:08:53.771Z",                "updated_at": "2021-07-23T17:08:53.771Z",                "hmac_verified": false            },            "messages": [],            "meta": {                "sender": {                    "additional_attributes": {},                    "custom_attributes": {},                    "email": null,                    "id": 10,                    "identifier": null,                    "name": "white-shadow-394",                    "phone_number": null,                    "pubsub_token": "token",                    "thumbnail": "",                    "type": "contact"                },                "assignee": {                    "id": 1,                    "name": "John",                    "available_name": "John",                    "avatar_url": "https://www.gravatar.com/avatar/0d722ac7bc3b3c92c030d0da9690d981?d=404",                    "type": "user",                    "availability_status": "online"                }            },            "status": "open",            "unread_count": 0,            "agent_last_seen_at": 0,            "contact_last_seen_at": 0,            "timestamp": 0,            "account_id": 1        }    }}

team_changed#

Available for: Agents

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "team.changed",        "data": {            "additional_attributes": {                "browser": {                    "device_name": "Unknown",                    "browser_name": "Chrome",                    "platform_name": "macOS",                    "browser_version": "92.0.4515.107",                    "platform_version": "10.15.7"                },                "referer": "http://localhost:3000/widget_tests",                "initiated_at": {                    "timestamp": "Fri Jul 23 2021 22:53:04 GMT+0530 (India Standard Time)"                }            },            "can_reply": true,            "channel": "Channel::WebWidget",            "id": 8,            "inbox_id": 1,            "contact_inbox": {                "id": 10,                "contact_id": 12,                "inbox_id": 1,                "source_id": "0538243e-1223-49e8-a381-a5a8ce250f60",                "created_at": "2021-07-23T17:22:48.744Z",                "updated_at": "2021-07-23T17:22:48.744Z",                "hmac_verified": false            },            "messages": [{                "id": 111,                "content": "Get notified by email",                "account_id": 1,                "inbox_id": 1,                "conversation_id": 8,                "message_type": 3,                "created_at": 1627060984,                "updated_at": "2021-07-23T17:23:14.000Z",                "private": false,                "status": "sent",                "source_id": null,                "content_type": "input_email",                "content_attributes": {                    "submitted_email": "jane@acme.inc"                },                "sender_type": null,                "sender_id": null,                "external_source_ids": {}            }],            "meta": {                "sender": {                    "additional_attributes": {},                    "custom_attributes": {},                    "email": "jane@acme.inc",                    "id": 12,                    "identifier": null,                    "name": "jane",                    "phone_number": null,                    "pubsub_token": "token",                    "thumbnail": "https://www.gravatar.com/avatar/526692031d4bb623b36ae4e340260f13?d=404",                    "type": "contact"                },                "assignee": {                    "id": 1,                    "name": "John",                    "available_name": "John",                    "avatar_url": "https://www.gravatar.com/avatar/0d722ac7bc3b3c92c030d0da9690d981?d=404",                    "type": "user",                    "availability_status": "online"                }            },            "status": "open",            "unread_count": 0,            "agent_last_seen_at": 1627061159,            "contact_last_seen_at": 0,            "timestamp": 1627060984,            "account_id": 1        }    }}

conversation_contact_changed#

Available for: Agents

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "conversation.contact_changed",        "data": {            "additional_attributes": {                "browser": {                    "device_name": "Unknown",                    "browser_name": "Chrome",                    "platform_name": "macOS",                    "browser_version": "92.0.4515.107",                    "platform_version": "10.15.7"                },                "referer": "http://localhost:3000/widget_tests",                "initiated_at": {                    "timestamp": "Fri Jul 23 2021 22:58:28 GMT+0530 (India Standard Time)"                }            },            "can_reply": true,            "channel": "Channel::WebWidget",            "id": 9,            "inbox_id": 1,            "contact_inbox": {                "id": 11,                "contact_id": 13,                "inbox_id": 1,                "source_id": "d45c0005-2429-4079-bbc2-6ade8bdb2866",                "created_at": "2021-07-23T17:28:24.996Z",                "updated_at": "2021-07-23T17:28:24.996Z",                "hmac_verified": false            },            "messages": [{                "id": 115,                "content": "Get notified by email",                "account_id": 1,                "inbox_id": 1,                "conversation_id": 9,                "message_type": 3,                "created_at": 1627061309,                "updated_at": "2021-07-23T17:28:40.000Z",                "private": false,                "status": "sent",                "source_id": null,                "content_type": "input_email",                "content_attributes": {                    "submitted_email": "jane@acme.inc"                },                "sender_type": null,                "sender_id": null,                "external_source_ids": {}            }],            "meta": {                "sender": {                    "additional_attributes": {},                    "custom_attributes": {},                    "email": "jane@acme.inc",                    "id": 12,                    "identifier": null,                    "name": "jane",                    "phone_number": null,                    "pubsub_token": "token",                    "thumbnail": "https://www.gravatar.com/avatar/526692031d4bb623b36ae4e340260f13?d=404",                    "type": "contact"                },                "assignee": {                    "id": 1,                    "name": "John",                    "available_name": "John",                    "avatar_url": "https://www.gravatar.com/avatar/0d722ac7bc3b3c92c030d0da9690d981?d=404",                    "type": "user",                    "availability_status": "online"                }            },            "status": "open",            "unread_count": 0,            "agent_last_seen_at": 1627061313,            "contact_last_seen_at": 0,            "timestamp": 1627061309,            "account_id": 1        }    }}

contact_created#

Available for: Agents

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "contact.created",        "data": {            "additional_attributes": {},            "custom_attributes": {},            "email": null,            "id": 1,            "identifier": null,            "name": "white-shadow-394",            "phone_number": null,            "pubsub_token": "token",            "thumbnail": "",            "type": "contact",            "account_id": 1        }    }}

contact_updated#

Available for: Agents

{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "contact.updated",        "data": {            "additional_attributes": {},            "custom_attributes": {},            "email": "jane@acme.inc",            "id": 12,            "identifier": null,            "name": "jane",            "phone_number": null,            "pubsub_token": "token",            "thumbnail": "https://www.gravatar.com/avatar/526692031d4bb623b36ae4e340260f13?d=404",            "type": "contact",            "account_id": 1        }    }}

presence_update#

Available for: Agents & Contact

# presence event delivered to contacts won't have information about other contacts{    "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":1,\"user_id\":1}",    "message": {        "event": "presence.update",        "data": {            "account_id": 1,            "users": {                "1": "online"            },            "contacts": {                "1": "online"            }        }    }}