Add custom interactions to Davis Assistant

An "interaction" is a single user question followed by the corresponding Davis Assistant response. Custom interactions allow users with the correct permissions to define custom behavior following certain events in the Davis Assistant interaction life cycle. These can be used for logging/auditing, ticket creation, problem triage, team notification, and anything else you can think of.

Custom interactions are configured per environment in Account settings > Customizations > Custom interactions.

General web hook requirements

• Must utilize HTTPS.
• Must return a 200 status code within 5 seconds.
• Full response time from initial question to Davis Assistant response, including any override and extension hooks, must take less than 10 seconds.

Authorization

All requests from Davis Assistant will include the Authorization header with the Client Secret defined by you in Custom Interactions configuration. Your web hook should ensure that the client secret matches on every request, rejecting any unauthentic requests with a 401 Unauthorized status code.

Incoming web hook

{
  "type": "event type (override, validate, confirmed)",
  "event": "event name",
  "endpoint": "hook endpoint",
  "clientSecret": "hook client secret",
  "intent": "intent run (post hook only)",
  "user": "email of Davis user",
  "context": {
    ...
  },
  "payload": {
    ...
  },
}

{
  "delegate": false,
  "confirmation": true,
  "response": {
    "confirmationButtonName": "yes-button",
    "text": "There were 83 problems yesterday. Would you like to see a list?",
    "ssml": "There were 83 problems yesterday. <break time=\"2s\"> Would you like to see a list?",
    "card": {
      "fallback": "There were 83 problems yesterday. Would you like to see a list?",
      "color": "#ff0000",
      "pretext": "Hi there!",
      "author_name": "Page 1 of 32",
      "author_link": "https://www.example.com/foobar",
      "author_icon": "https://www.example.com/foobar.png",
      "title": "Today's problems",
      "title_link": "https://www.example.com/problems",
      "text": "There were 83 problems yesterday. Would you like to see a list?",
      "fields": [{
        "title": "Problem ID",
        "value": "0123456789",
        "short": "true"
      }],
      "footer": "My company",
      "footer_icon": "https://www.example.com/companylogo.png"
    }
  }
}

Fully custom phrases

Custom phrases are configured using the Full Text Interception event type. When this event type is enabled, Davis Assistant sends the full text of each request matching the configured regular expression to your web hook service. Your service can then choose to respond to the request, or delegate to the default functionality.

{
  "type": "override",
  "event": "fullTextInterception",
  ...
}

Override default responses

Overriding default responses works similarly to the Full Text Interception event type, however it only triggers when a specific intent would otherwise be triggered, rather than when a regular expression matches (an "intent" is the logic that is run for a single Davis Assistant interaction. For example, the phrase "Hey, Davis", triggers the launch intent).

Just as with Full Text Interception, you can choose to handle a request or delegate to the default behavior.

Daily/Morning report

{
  "type": "override",
  "event": "preReport",
  ...
}

Extend default responses

Extending default responses works slightly differently than override hooks. The intent logic is first run (either the default or your custom logic from an override event hook), then the web hook is sent a validate event. On receiving a validate event, your web hook can choose to add text and/or a visual card that will be appended to the message. In some cases, this is enough and you can continue with the regular flow. In other cases, you may want to prompt your user with a yes/no question. If this is the case, you can respond with confirmation: true. A "yes" button (or a button with the text of your choice) will be added to the response. If the user responds with "yes" or clicks the button, your web hook will be sent a confirmed event. An example of a flow like this is support-ticket creation. On receiving a validate event, you may prompt the user to create a ticket in your ticketing system. If the user responds with "yes", your web hook will be sent a confirmed event, and you can handle the ticket creation and respond to the user appropriately.

Problem detail

This extension event allows you to augment the problem detail response with your own information and optionally prompt the user with a yes/no question. The problem detail intent is triggered when a user selects a problem from a list of problems or when a user asks about a problem specifically by ID.

{
  "type": "validate | confirmed",
  "event": "postProblemDetail",
  ...
  "payload": {
    "problem": {
      "id": "string",
      "displayName": "string",
      "title": "string",
      "url": "string",
      "tagsOfAffectedEntities": [
        {
          "context": "string",
          "key": "string",
          "value": "string"
        }
      ]
    }
  }
}

Entity detail

This extension event enables you to augment the entity detail response (an "entity" is any host, service, or process monitored by DESK) with your own information and optionally prompt the user with a yes/no question. The entity detail intent is triggered when a user selects an entity from a list of entities or when a user specifically asks about an entity.

{
  "type": "validate | confirmed",
  "event": "postEntityDetail",
  ...
  "payload": {
    "entity": {
      // entity format as described in the DESK API Documentation
      // https://www.desk.com/support/help/desk-api/topology-and-smartscape/how-do-i-fetch-the-list-of-monitored-applications/
    }
  }
}

Daily/Morning report

This extension event will allow you to augment the daily report response with your own information and optionally prompt the user with a yes/no question.

{
  "type": "validate | confirmed",
  "event": "postReport",
  ...
}