Developers

Webhook Events

Events

Not all events can have webhooks registered, to avoid having useless triggers configured. The following table contains all events for which you can register webhooks:

Events

Description

chats:create

Any time a new chat is created.

chats:join

Any time a user joins a chat.

chats:leave

Any time a user leaves from a chat. 

chats:close

Any time a chat is closed.

chats:assign

Any time a chat is looking for an agent to attend it. It’s triggered each time an invitation “jumps” from one agent to another. If a valid agent ID is returned in this webhook, the chat is assigned to this agent. The timeout to return a successful response is 5 seconds and it cannot be modified.

forever:alone

Any time that there are no more agents available to be invited to the current chat. In this situation, you can start the assignation loop again or close the chat.

invitations:accept

Any time a user accepts an invitation for a chat.

messages:new

Any time a message is sent to an ongoing chat conversation.

messages:read

Any time a message is received in an ongoing chat conversation. 

queues:update

Any time a chat moves to a new position within its queue.

system:info

Any time a new system event occurs (for example, when a ticket is created upon the closing of a chat).

users:activity

Any time a user performs an action, such as:

  • Start writing

  • Stop writing

  • Leave the chat (meaning the period in which the user is not connected and the system waits a reasonable amount of time for the possibility to reconnect)

Payloads

The Live Chat server will send POST messages to the target URL(s) when a configured event happens. These messages have the following payload structure (with application/json encoding):

  • trigger: The event that triggers the webhook request
  • appId: This is the API key, the public identifier of the API instance. You can find this value in your instance, in Messenger > Settings > HyperChat.
  • data: The information on the kind of event that has been received. Each event type has a specific format with the relevant event information. All event data payloads mirror the responses of the API routes.
  • created_at: The date and time when the request was sent, in the format of unix timestamp.
{
  trigger: {{event_name}},
  appId: {{app_id}},
  data: {{object}}, // each event has different data
  created_at: {{unix_timestamp}}, // the time on which the webhook was fired
}

Note that this events’ data is “skinny”. You should make additional calls to the API to retrieve the latest state if your integration needs more information.

We make the best effort to preserve the order of messages, but some messages might be delivered out of order. We recommend as a best practice to use the 'created_at' parameter to handle the order properly.

Examples

chats:create

{
  "trigger": "chats:create",
  "appId": "3rlaOkkhY",
  "data": {
    "userId": "kHb0zVMQ1",
    "chatId": "ZvJUfblHL"
  },
  "created_at": 1677169557
}

chats:close

{
  "trigger": "chats:close",
  "appId": "3rlaOkkhY",
  "data": {
    "chatId": "ZvJUfblHL",
    "project": "messenger_pre",
    "userId": "kHb0zVMQ1"
  },
  "created_at": 1677169735
}

chats:join

{
  "trigger": "chats:join",
  "appId": "3rlaOkkhY",
  "data": {
    "chatId": "ZvJUfblHL",
    "userId": "kHb0zVMQ1"
  },
  "created_at": 1677169557
}

chats:leave

{
  "trigger": "chats:leave",
  "appId": "3rlaOkkhY",
  "data": {
    "chatId": "ZvJUfblHL",
    "userId": "kHb0zVMQ1"
  },
  "created_at": 1677169735
}

messages:new

{
  "trigger": "messages:new",
  "appId": "3rlaOkkhY",
  "data": {
    "message": {
      "created": 1677169325,
      "id": "s7pg2bg2TF",
      "chat": "FAit516fg",
      "sender": "5mABUjYYK",
      "message": "text message",
      "type": "text",
      "receivedBy": [],
      "readBy": [],
      "imported": false
    },
    "chatId": "FAit516fg"
  },
  "created_at": 1677169325
}

messages:read

{
  "trigger": "messages:read",
  "appId": "3rlaOkkhY",
  "data": {
    "messageId": "p53r5y_PsU",
    "chatId": "FAit516fg"
  },
  "created_at": 1677169329
}
 

invitations:accept

{
  "trigger": "invitations:accept",
  "appId": "3rlaOkkhY",
  "data": {
    "chatId": "FAit516fg",
    "userId": "L5VmdmYhU"
  },
  "created_at": 1677169298
}

invitations:new

{
  "trigger": "invitations:new",
  "appId": "3rlaOkkhY",
  "data": {
    "chatId": "ZvJUfblHL",
    "userId": "L5VmdmYhU",
    "options": {
      "senderId": "system",
      "attempt": 15,
      "forced": false
    }
  },
  "created_at": 1677169725
}

invitations:reject

{
  "trigger": "invitations:reject",
  "appId": "3rlaOkkhY",
  "data": {
    "chatId": "ZvJUfblHL",
    "userId": "L5VmdmYhU",
    "success": true
  },
  "created_at": 1677169725
}

users:activity

{
  "trigger": "users:activity",
  "appId": "3rlaOkkhY",
  "data": {
    "userId": "L5VmdmYhU",
    "chatId": "FAit516fg",
    "type": "not-writing"
  },
  "created_at": 1677169329
}

queues:update

{
  "trigger": "queues:update",
  "appId": "3rlaOkkhY",
  "data": {
    "userId": "kHb0zVMQ1",
    "chatId": "ZvJUfblHL",
    "data": {
      "queuePosition": 0,
      "waitingTime": 0
    }
  },
  "created_at": 1677169557
}

chats:leave

{
  "trigger": "chats:leave",
  "appId": "3rlaOkkhY",
  "data": {
    "chatId": "ZvJUfblHL",
    "userId": "kHb0zVMQ1"
  },
  "created_at": 1677169735
}