widget.keyword.matched

Fires for every message a visitor sends in a widget chat.

Despite the name, nothing is matched. Keywords are a setting on the workflow trigger of the same name, and they are applied only there. A webhook subscription receives every visitor message, and the payload does not say which keyword, if any, the message contained. Filter on text in your handler.

Payload

{
  "id": "whd_1Ns7cX4gT",
  "event": "widget.keyword.matched",
  "createdAt": "2026-09-11T13:06:40.519Z",
  "data": {
    "conversationId": "conv_7Yn2kP",
    "visitorId": "wv_5Hc2pR",
    "text": "Can I cancel my plan before it renews?"
  }
}

string

required

The chat the message was sent in. Always present.

string

The visitor who sent it.

string

The message, with leading and trailing whitespace removed.

Worth knowing

Visitor messages only. Replies from your team and from the answer bot do not fire this.
One event per message. A busy widget delivers a lot of these, so filter early and keep the handler fast.
No message id. To read the message in its thread, fetch the conversation from the Conversations API.

Example

const RETENTION_RISK = /\b(cancel|refund|downgrade)\b/i;

custral.on("widget.keyword.matched", async (event) => {
  const {conversationId, text} = event.data;
  if (!RETENTION_RISK.test(String(text ?? ""))) return;

  await alerts.notify({team: "retention", conversationId});
});

Getting started

Building a receiver

Event reference

Operations

Payload

Worth knowing

Example

​Payload

​Worth knowing

​Example

Payload

Worth knowing

Example