How do I add custom interactions to Davis?

Custom interactions allow users with the correct permissions to define custom behavior following certain events in the Davis interaction lifecycle (an "interaction" is a single user question followed by the corresponding Davis response). 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.

Note: Custom interactions is an advanced topic for technical users. Development experience is strongly recommended.

General web hook requirements

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

Authorization

All requests will include the Authorization header using the token authentication scheme Token ${client secret}, with the client secret defined by the user in the configuration. The web hook should check that the client secret matches on every request and reject unauthentic requests with a 401 Unauthorized status code.

Web hook payload format

All requests are HTTP POST requests.

Content-Type: application/json

Authorization: Token ${client secret}

{
      "type": "event type (override, validate, confirmed)",
      "event": "event name",
      "endpoint": "hook endpoint",
      "clientSecret": "hook client secret",

      // See glossary
      "intent": "intent run (post hook only)",

      "user": "email of Davis user",
      "context": {
        // complex object representing the current state of the system from previous interactions
      },
      "payload": {
        // complex object representing the subject of the current interaction
      },

}

Web hook response format

{
  // boolean, optional - true delegates to the default functionality
  // only valid on override event types
  "delegate": false,

  // boolean, optional - true indicates that the prompt includes a yes/no question
  // if true and the user responds yes, Davis will send a "confirmed" event
  "confirmation": false,

  // required if delegate is not true on override event types
  // `card` is a subset of the slack card format supported by Davis
  "response": {
    "confirmationButtonName": "", // string, optional
    "text": "", // string, required if delegate is not true
    "ssml": "", // string, optional
    "card": { // optional, all properties optional
      "fallback": "",
      "color": "",
      "pretext": "",
      "author_name": "",
      "author_link": "",
      "author_icon": "",
      "title": "",
      "title_link": "",
      "text": "",
      "fields": [{
        "title": "",
        "value": "",
        "short": ""
      }],
      "footer": "",
      "footer_icon": ""
    }
  }
}

Fully custom phrases

Custom phrases are configured using the Full Text Interception event type. When this event type is enabled, Davis 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 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 Dynatrace) 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 Dynatrace API Documentation
      // https://www.dynatrace.com/support/help/dynatrace-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",
  ...
}