Integrate Davis Assistant with third-party platforms

Learn how to build a custom integration using the Davis Assistant API for platforms that aren't supported out of the box.

General requirements

A valid, enabled Davis Assistant API token
A system with network access to Davis on port 443

Authorization

All requests must include the Authorization header that includes a Davis Assistant API token.
Create a new Davis Assistant API token in the Davis API configuration (located at Account settings > Integrations > Davis API within Davis Assistant).

Note

You must be an administrator of the active (selected) environment to access the Davis Assistant API configuration section. If the token is invalid, the API will return a 401 Unauthorized status code. If you're attempting to perform an action that requires administrative privileges for the selected environment, and lack these privileges, the API will return a 403 Forbidden status code.

POST user interaction input

URL	https://assistant.desk.com/api/v2/interact
Method	POST
Header	Content-Type: application/json
Header	Authorization: api-token ${DAVIS API TOKEN}

Request format

Body Example

Property	Description	Type	Required
timezone	User's time zone in tzdata format.	string	required
sessionId	Uniquely identifies a session to avoid conversation collisions (unique for each user).	string	required
input	Question or phrase to be sent to Davis Assistant.	string	required
responseFormat	The output format desired. Valid formats: "all" "audible" "visual"	string	optional
tags	An array of tags for filtering interactions. All tags must match an underlining entity in order to be included in the response. Valid formats: "test" { "key": "environment", "value": "prod" } { "context": "AWS", "key": "environment", "value": "dev" }	array	optional

Request body:

{
  "timezone": "America/Detroit",
  "sessionId": "custom:test@desk.com:1",
  "input": "What happened this week?",
  "responseFormat": "audible",
  "tags": ["test", { "key": "environment", "value": "prod" }]
}

Response format

Body Example

Property	Type	Description
responseFormat	string	Included response formats
response.text	string	Plain text version of response
response.visual	object	Slack- and Davis Assistant web UI-compatible format
response.audible	object	SSML-compatible format used for Alexa and Davis Assistant web UI speech responses
tenant	string	Name of environment associated with response
url	string	A URL is included in the response when there's a related DESK dashboard. This property may not be on every response.

Response body (Status code 200):

{
  "responseFormat": "all",
  "response": {
    "text": "Today, 11 problems occurred. The largest concentration of problems was around today at 9:00 AM. Would you like to see a listing of these issues?",
    "visual": {
      "text": "Today, 11 problems occurred. The largest concentration of problems was around <!date^1525093200^{date_long_pretty} at {time}|today at 9:00 AM>. Would you like to see a listing of these issues?"
    },
    "audible": {
      "ssml": "Today, 11 problems occurred. The largest concentration of problems was around today at 9:00 AM. Would you like to hear a listing of these issues?"
    }
  },
  "tenant": "Demo Environment",
  "url": "https://demo.desk.com/e/131245bf-c8f0-4f70-b37d-0ac6e0b32a1e/#problems;gtf=c_1525060800000_1525147199999"
}