Addon - Keyword Detection

Setup

To setup Keyword Detection, you must enable it as an addon.

This addon requires the setup property webhook to provide a URI that is a POST endpoint.

An optional property includeFullMessage can also be passed if you want the sample to be included in the eventuality a Webhook is sent.

PATCH https://api.chatsight.ai/addons

HEADER x-chatsight-api-auth: <<apiKeyExample>>

curl --location --request PATCH 'https://api.chatsight.ai/addons' \
--header 'x-chatsight-api-auth: <<apiKeyExample>>' \
--header 'Content-Type: application/json' \
--data-raw '{"addon":"keywordAlert","webhook":"http://coolwebsite.com/webhook","includeFullMessage":true}'

Adding Keywords

You can register keywords to monitor by calling the addon/keywords endpoint.

Any alphanumeric or UTF-8 text can be submitted in the keyword property of your request.

PATCH https://api.chatsight.ai/addons/keywords

HEADER x-chatsight-api-auth: <<apiKeyExample>>

curl --location --request PATCH 'https://api.chatsight.ai/addons/keywords' \
--header 'x-chatsight-api-auth: <<apiKeyExample>>' \
--header 'Content-Type: application/json' \
--data-raw '{"keyword":"pizza"}'

Removing Keywords

DELETE https://api.chatsight.ai/addons/keywords

HEADER x-chatsight-api-auth: <<apiKeyExample>>

curl --location --request DELETE 'https://api.chatsight.ai/addons/keywords' \
--header 'x-chatsight-api-auth: <<apiKeyExample>>' \
--header 'Content-Type: application/json' \
--data-raw '{"keyword":"pizza"}'

Adding Metadata

To make Keyword Detection alerts more contextual and relevant, you can pass a metadata object property to your standard moderation request body. There are no formal requirements for what can be within, but a maximum of 20 metadata object property keys can be passed - if more are passed, the addon will not run but the request will continue as normal.

{
  "sample":"Is the pizza ready?",
  "metadata":{
    "someRoomID":"abcdd-edfe-eaggae",
    "myCustomMetadataKey":"Pizza Party Chatroom #5 🍕"
  }
}

Webhook Schema

Webhooks will make a POST request to your designated endpoint in this following format.

{
  "sender": "chatsight-webhooks",
  "addon": "keywordAlert",
  "payload": {
    "keywordDetected": "pizza",
    "metadata": {
      "someRoomID":"abcdd-edfe-eaggae",
      "myCustomMetadataKey": "Pizza Party Chatroom #5 🍕"
    },
    "fullText": "Is the pizza ready?"
  },
  "time": 1616965047337,
  "hmac": "..."
}

Key	Value	Description
sender	String	An identifier that can be used by you to loosely-distinguish our Webhook requests from others you may incorporate later.
addon	String	The SKU of the addon making use of this Webhook request. In this case, it is Keyword Detection.
payload.keywordDetected	String	The detected keyword match.
payload.metadata	Object	An object containing metadata passed by your original request to the endpoint. As described above.
payload.fullText	String // Boolean	If the property "includeFullMessage" is passed as true when enabling the addon, this field will contain the original text made by the request for better context. If not enabled, this will pass literal False.
time	Int	Milliseconds since the Unix Epoch.
hmac	String	If the addon's global shared secret is enabled by calling /addons/secrets at least once, this field can be used to verify this Webhook came from Chatsight by verifying the SHA-256 HMAC with the symmetric key issued. Calculate the HMAC SHA-256 of the `time` property (`time` is sent as an Integer, but must be converted to a string before hashing) and evaluate if they match to authenticate the message. Note: The HMAC sent is in Base-64 format.