Automation Framework best practices

Learn about our best practices when working with the Automation Framework

We call these best practices, but consider them more as requirements in order to future-proof your bot as we add new features and events.

Bot work queues

We recommend a minimum of two work queues in Khoros Care: one for bot-only conversations and another for conversations handed off from a bot to an agent. You can use the Bot API v3 to tag a conversation, and set up the work queues so that conversations with the appropriate tags are routed to the appropriate work queues.

JWT Token refresh

We recommend programmatically refreshing the JWT once a week. (See /bots/v3/tokens/appId/{appId}). This timeframe leaves plenty of time to troubleshoot manually if an error occurs. Your automated solution should attempt to retry in the event of a 500 response. A 4xx response indicates that you should not retry, but rather you should fix the query. Your old token will remain valid for a 10-minute grace period.


Expect that Khoros will add new fields to common object payloads (Author, Coordinate, Media, Actions, etc.). Fields added in the future will be backward compatible. If you use logic to validate a payload, do not invalidate if additional fields are present.

Webhook events

  • Return a 202 Accepted response when your bot receives any request at its webhook endpoint. We will ignore all response bodies returned from messages we deliver to your bot.
  • Be explicit in the events that your bot handles. Most bots generally only care about a subset of events they receive. In your code, be explicit about the events to process. For all other events, return a 202 statusCode. As we continue to develop the Automation Framework, we will deliver additional types of events. When we add new event types, update your code to handle those events, as needed (take no action or take a specific action). See an example of this in our Hello World bot example.
  • We provide request IDs in a callback request header and a response header named x-amzn-RequestId. Note the ID and, if needed, ask for information about the status of requests using the /request endpoint. This is helpful to check the status of a request that might take a while to complete or to view details about unsuccessful requests.
  • Because of our retry rules, it is possible that the bot could receive the same message multiple times. Always note and check against the x-amzn-RequestId found in the response header to ensure that you don’t process the same ID twice.