The Khoros Care Automation Framework and Bot API v3 enable automation services, aka "bots," that you'd like to integrate into the Khoros engagement platform (the underlying technology of Khoros Care and Messaging). The Khoros Automation Framework is agnostic and so provides the flexibility you need to easily and quickly add automation services of your choosing to your workflow, allowing you to use the technology and providers that best match your business needs.

📘

Note

While you can use the same bot across multiple source channels or use separate bots for different channels, the Framework currently allows only a single chatbot integration per individual social business page or handle on any given source channel.

The Khoros Automation Framework and Bot API work together: the framework guides the development of your automation services while the Bot API provides the tools to register your services, implemented as a webhook, with the Khoros platform.

Using the Bot API you can:

• Register a webhook with Khoros
• Retrieve, update, and delete webhook registrations
• Receive messages and other events on your webhook

🚧

Important

The Automation Framework and Bot API described in this guide are different from our legacy Bot platform and Bot API v2, which supports Twitter and Facebook networks only, the latter via the Facebook Handover Protocol. See Supported channels for the full list of channels supported by the Automation Framework.

The Automation Framework acts as an intermediary between your service, or "bot," and Khoros Care. Your brand's bot registers a webhook with Khoros to receive messages/events. Bot registration is a one-time action per bot for each network. If you are using the same bot for multiple networks, you'll use the same App ID (appId) for each registration with a unique Network ID (network) for each network. Once the webhook is registered, your automation service is able to use the Bot v3 API.

The following sections give more detail about the Automation Framework architecture and workflows.

Acknowledge Event

You must immediately acknowledge every event that you receive from the Framework. Khoros uses acknowledgment of the event to monitor the health of your endpoint. The Framework's built-in automatic handoff workflow ensures that conversations do not get “stuck” if your bot enters an unhealthy state. Notifications alert you to degraded and unavailable endpoints.

Process Event

You will perform different actions depending on the purpose of your automation - in the case of a chatbot, the automation will figure out and send a response. In another use case, you might query and update CRM and Case systems, detect intent and tag the message, assign a priority or route the conversation, or calculate suggested agent responses. Here are a few common implementations you can use with the Automation Framework:

• Author storage - You can implement an author store that allows you to store information associated with the authors connected to events you receive

• Access token retrieval - Ideally, you will load the Khoros JWT token from a performant store and have a separate process to refresh it (well ahead of its expiration)

• Other APIs - You can use other Khoros APIs to access additional information. The conversation API, for example, can retrieve the full conversation details on a Conversation Close event.

• External APIs - You can call other Khoros Community or Marketing APIs to take action in those platform components. Be aware though, that you will need to establish an additional user-context in that external component in order that the called APIs may execute properly. For example, using Automation Framework your bot can call a community API to change the state of community content; To do this, you'll need to authenticate your community API calls with appropriate community credentials in addition to those used for basic bot integration with Care.

Monitor Requests

You can optionally monitor for the status of requests you’ve made either by querying for the status of a specific request, or more commonly by asking for all recent requests that are in an error state. For requests in an error state, you can retry the payload or determine another best action.

Common Bot Workflows

While planning your bot implementation, there are several common bot workflows to consider:

• Bot interacts directly with the customer and handles the entire conversation
• Bot interacts directly with the customer, but the customer wants to talk with an agent
• Bot interacts directly with the customer, but the bot determines that an agent should be involved
• Bot wants to listen to everything and observe what is happening
• Bot wants to update author profile information in Care
• Bot wants to prioritize a conversation
• Bot wants to route a conversation
• Bot wants to tag a post in Khoros Care

Events Delivered to your Bot

See Working with webhooks for details on each.

Bot Health

We define and monitor the health of a registered bot based on the response to events delivered by the Automation Framework. (A 200 or 202 response returned from a bot signals a successful delivery.)

Your bot will be in one of three possible health states: HEALTHY, DEGRADED, or DOWN.

• DOWN: 100% failures, at least 10 attempts
• DEGRADED: mixed successes and failures, or less than 10 attempts
• HEALTHY: 100% success, or 0 attempts

Khoros calculates your health state based on the number of delivery successes and failures during the last 2 minutes. The Automation Framework defines a delivery attempt a failure after a timeout or a non-2xx response from the bot.

Our health calculations take into account only final delivery attempts made in last 2 minutes. If we are retrying a failed delivery, for example, and the second retry succeeds within the 2-minute period, the first failure is not counted in the bot health calculation.

Rules for Deliveries

• Khoros attempts to deliver every message at least once.
• If delivery fails, the Framework re-attempts delivery once. (See Rules for Retries below.)
• If all delivery attempts fail for a callback of type message, the Framework automatically hands that conversation to the agent and includes a message about the error. This is so that if an agent engages, and future messages are delivered to the bot, the bot will not attempt to jump into the middle of a conversation.
• Failures for agent replies, conversation control, or other non-message types do not trigger a conversation handoff.
• When the bot is in DEGRADED state, the Framework includes a health object in the delivered messages, so that the bot can take action automatically if needed.

Rules for Retries

If the Framework detects any kind of error or failure while trying to connect to or deliver a message, the Framework retries the delivery once, after a short delay of less than 1 second.

Delivery errors that trigger retries include:

• The Framework delivers the message, but your bot responds with an error HTTP status in the range of 400 to 600. (Note that this means that your bot might receive some messages twice, so you should ensure that you always return a 200-series HTTP response for every request.)
• Connection issues such as Unable to Find Server or SSL errors
• Timeouts. if your bot does not return a response quickly, the request will timeout and the Framework reattempts delivery. (Again, note this means you might receive duplicate messages.)

If the delivery fails again after the retry attempt, the delivery is marked as a failure. See our Webhook section under Best Practices for using the x-amzn-RequestId found in the response header to check for duplicate messages.

How you’ll learn about bot health changes

• Email notification - if you have added an email address in the contact field of your bot’s registration payload, the Framework sends an email when:
  • the bot health becomes DEGRADED
  • the bot health becomes DOWN
• Hand-off tags - the Framework automatically applies a Bot Handoff child-tag named Automatic Bot Handoff when we automatically hand-off a conversation if:
  • the Framework can't deliver an event of type message for a bot-owned author
  • the bot health is DOWN

Note: You can see these tags in Khoros Care and monitor for the tag in Care Analytics using a Smart View applied to an appropriate widget.

• API request - you can call to the /health/appId/appId endpoint to check the current health of a bot

The Framework will not send any bot health notification email for a single bot appId more than once every 2 minutes.

If more than 2 minutes have elapsed since the last notification, and the current bot health has changed since the last notification, the Framework will send a new notification alerting you to the current bot health status.

If the bot health status is DOWN or DEGRADED and remains in one of these states over an extended time period, we will send an additional notification every 30 minutes.

Actions your Bot can take

Actions the Framework may take on behalf of your bot

Some changes, such as the state of a bot or a conversation, result in actions undertaken by the Framework itself. Examples include:

• Logging request records
• Automatically handing-off all conversations to agents
• Marking a bot unhealthy
• Switching a bot to maintenance mode

Bot Handoffs and Handoff Tags

Khoros Care supports a Bot Handoff tag that is applied automatically by the legacy Bot API v2 /bots/networks/networkType/authors/authorId/handoff endpoint. The Bot Automation Framework uses the following Bot Handoff child tags to capture the reason for the handoff:

• Standard Bot Handoff
• Automatic Bot Handoff
• Maintenance Bot Handoff

In each handoff instance, both the legacy Bot Handoff and the appropriate child handoff tag is applied to the conversation.

Khoros Flow and the Automation Framework

Khoros Flow is an excellent chatbot tool that works great with the Automation Framework. Khoros Flow is the solution of choice that we use in our own automated chatbot used throughout our websites, Maia.

You can find out more about how we used Flow.ai to build Maia in these blog posts:

• How we Built It: Maia
• How Maia is Powered by Flow.ai and Modern Chat