Conversations

On this page we'll dive into the Conversations endpoints you can use to programatically start conversations and post messages to interact with Dust assistants. We'll look into how to create a converstaion, post a message, retrieve a conversation and stream events about it.

Authentication

All requests to the Dust API must be authenticated using an Authentication header. The value of this header must be the string Bearer followed by a space and your API key. You can find your API key in your account's Developers Tools panel.

Conversations

A conversation is consituted of UserMessages, AgentMessages and ContentFragments.

A UserMessage is a message sent by a human to interact with one or more assistants.

An AgentMessage is an assistant response. AgentMessages can potentially include an action. Currently the only action supported are:

RetrievalAction which triggers for agents configured to perform a retrieval before streaming their response.
DustAppRunAction which triggers for agents configured to run a Dust App before streaming their response.

ContentFragments are pieces of information that can be inserted in conversations and are passed to assistants as part of the context.

The UserMessage model

The UserMessage model contains all the information and data related to a user message.

Properties

Name
sId
Type
string
Description
Unique identifier for the message.
Name
visibility
Type
string
Description
One of visible or deleted.
Name
version
Type
integer
Description
The version number of the message.
Name
user
Type
object | null
Description
Information about the user that created that message. Only set if the message was created through the Dust interface by a logged in user.
Name
mentions
Type
[]object
Description
A list of AgentMentions objects. An AgentMention is an object with a single configurationId field which points the assistant being mentioned.
Name
content
Type
string
Description
The content of the message. In this content, mentions to assistants are rendered as markdown directives :cite[assistantName]{configurationId}.
Name
context
Type
object
Description
Context about the user who sent the message. This will be based on the user profile if the message was created by a logged in user, or on the context provided when the message was created by API.

The AgentMessage model

The AgentMessage model contains all the information and data related to an agent message.

Properties

Name
sId
Type
string
Description
Unique identifier for the message.
Name
visibility
Type
string
Description
One of visible or deleted.
Name
version
Type
integer
Description
The version number of the message.
Name
parentMessageId
Type
string
Description
The unique identifier of the UserMessage this AgentMessage is a response to.
Name
configuration
Type
object
Description
The configuration of the assistant that generated this message.
Name
status
Type
string
Description
One of created, succeeded or failed. A message will remain in created status until the assistant has finished processing it.
Name
action
Type
object | null
Description
An object representing the potential action that the assistant took before generating an answer. Currently only RetrievalAction and DustAppRunAction are supported.
Name
content
Type
string
Description
The content of the message.
Name
error
Type
object | null
Description
If an error occured this object will be set with a code and a message.

The Conversation model

The Conversation model contains all the information and data related to a conversation.

Properties

Name
sId
Type
string
Description
Unique identifier for the conversation.
Name
created
Type
integer
Description
Epoch of the creation of the conversation.
Name
owner
Type
object
Description
Information about the workspace owning this conversation.
Name
title
Type
string | null
Description
The title of the conversation if set.
Name
visibility
Type
string
Description
One of deleted or unlisted.
Name
content
Type
(UserMessage[] | AgentMessage[])[]
Description
A list (the converation) of either UserMessage or AgentMessage lists (the versions for each message of the conversations).

Conversation events

A conversation will emit the following events that can be streamed by API (see below):

The user_message_new event is sent when a new UserMessage is received.

{
  type: "user_message_new";
  created: number;
  messageId: string;
  message: UserMessage;
}

The agent_message_new event is sent when a new AgentMessage is received. The agent message status will initially be created.

{
  type: "agent_message_new";
  created: number;
  configurationId: string;
  messageId: string;
  message: AgentMessage;
}

The conversation_title event is sent when the title of the conversation is updated (manually or automatically after the first user assistant interaction).

{
  type: "conversation_title";
  created: number;
  title: string;
}

AgentMessage events

AgentMessages have a complex lifecycle going from possibly running an action, to streaming tokens and finally being marked as succeeded. These events can be streamed by API (see below).

Action events

Retrieval Action events

The retrieval_params event is sent during retrieval (if applicable) with the finalized query used to retrieve documents.

{
  type: "retrieval_params";
  created: number;
  configurationId: string;
  messageId: string;
  dataSources: "all" | DataSourceConfiguration[];
  action: RetrievalActionType;
}

DustAppRun Action events

The dust_app_run_params event is sent during the preparation of the execution of the Dust app (if applicable) with the finalized inputs for the app infered by a model from the conversation context and the Dust app's input dataset schema.

{
  type: "dust_app_run_params";
  created: number;
  configurationId: string;
  messageId: string;
  action: DustAppRunActionType;
}

The dust_app_run_block event is sent during the execution of the Dust app as a block execution starts. The field runningBlock will be non-null on the action object.

{
  type: "dust_app_run_block";
  created: number;
  configurationId: string;
  messageId: string;
  action: DustAppRunActionType;
}

Generic Action events

The agent_action_success event is sent once the assistant action is completed (if applicable), as we're moving to generating a message if applicable. The currently supported actions are retrieval and dust_app_run. If the assistant is configured to not perform any action, these events won't be emitted.

{
  type: "agent_action_success";
  created: number;
  configurationId: string;
  messageId: string;
  action: AgentActionType;
}

Generation events

The generation_tokens event is sent when tokens are streamed as the the assistant is generating a message.

{
  type: "generation_tokens";
  created: number;
  configurationId: string;
  messageId: string;
  text: string;
}

The agent_generation_success event is sent once the generation has completed.

{
  type: "agent_generation_success";
  created: number;
  configurationId: string;
  messageId: string;
  text: string;
}

Other events

The agent_message_success event is sent once the message is fully completed and successful.

{
  type: "agent_message_success";
  created: number;
  configurationId: string;
  messageId: string;
  message: AgentMessageType;
}

The agent_error event is sent whenever an error occured durint the AgentMessage lifecycle.

{
  type: "agent_error";
  created: number;
  configurationId: string;
  messageId: string;
  error: {
    code: string;
    message: string;
  };
}

POST/v1/w/:workspace_id/assistant/conversations

Create a Conversation

This endpoint allows you to create a Conversation potentially posting an initial user message at the same time. If you specify an initial user message, the conversation objet returned will be returned including the user message and potential assistant response messages as they got added (created status). Knowing their sId will enable you to stream their events without having to retrieve the conversation object again.

URL attributes

Name
workspace_id
Type
string
Description
The ID of the workspace to use (can be found in any of the workspace's URL)

JSON body attributes

Attributes are passed as a JSON object in the request body.

Name
visibility
Type
string
Description
Only "unlisted" is supported.
Name
title
Type
string | null
Description
A title for the conversation. If none is provided, one will be generated automatically.

Optional JSON body attributes

Name
contentFragment
Type
object
Description
An initial content fragment object. See "Create a New Content Fragment" endpoint body attributes for more details. The content fragment will be inserted before the user message if both are specified.
Name
message
Type
object
Description
An initial user message object. See "Create a New User Message" endpoint body attributes for more details.
Name
blocking
Type
boolean
Description
When set to true, the conversation will be created synchronously and the response will include the full generation data. Default value is false.

Request

POST

/v1/w/:workspace_id/assistant/conversations

curl https://dust.tt/api/v1/w/b809011d38/assistant/conversations \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "unlisted",
    "title": null,
    "message": {
      "content": "Hi :cite[dust]{dust}!",
      "mentions": [{
        "configurationId": "dust"
      }],
      "context": {
        "timezone": "Europe/Paris",
        "username": "peter",
        "email": null,
        "fullName": "Peter Parker",
        "profilePictureUrl": "https://dust.tt/static/systemavatar/helper_avatar_full.png"
      }
    }
  }'

Response

{
  "conversation": {
    "owner": {
      "sId":"b809011d38",
      "name":"dust",
      "role":"builder",
      "plan":{...},
    },
    "created":1695901958406,
    "sId":"7b6396245c",
    "title":null,
    "visibility":
    "unlisted",
    "content": [
      [{
        "sId": "1651e51da4",
        "type": "user_message",
        "visibility": "visible",
        "version": 0,
        "user": null,
        "mentions": [{"configurationId":"dust"}],
        "content": "Hi :cite[dust]{dust}!",
        "context": {
          "username": "peter",
          "timezone": "Europe/Paris",
          "fullName": "Peter Parker",
          "email": null,
          "profilePictureUrl": "https://dust.tt/static/systemavatar/helper_avatar_full.png"
       }
      }] , [{
        "sId": "fa72419067",
        "type": "agent_message",
        "visibility": "visible",
        "version": 0,
        "parentMessageId": "1651e51da4",
        "status": "created",
        "action": null,
        "content": null,
        "error":null,
        "configuration":{...}
      }]
    ]
  },
  "message": {...},
  "contentFragment": {...}
}

POST/v1/w/:workspace_id/assistant/conversations/:conversation_id/messages

Create a new User Message

This endpoint allows you to post a new user message in a conversation, potentially triggering an assistant response.

URL attributes

Name
workspace_id
Type
string
Description
The ID of the workspace to use (can be found in any of the workspace's URL)
Name
conversation_id
Type
string
Description
The sId of the conversation object to retrieve.

JSON body attributes

Name
content
Type
string
Description
The textual content of the message. Mentions to assistants in the message content should be sent as markdown directives :cite[assistantName]{configurationId} so that they can be properly rendered in the Dust interface.
Name
mentions
Type
[]{configurationId}
Description
Mentions are a way to trigger the response of an assistant in a message. They are an array of objects with a single configurationId field which points the assistant being mentioned. Available global assistant configurationId are: helper, dust, gpt-3.5-turbo, gpt-4, claude-3-opus, claude-3-sonnet, slack, google_drive, notion, github. To mention custom assistants, you can find the assistant configurationId in the URL of the assistant page.
Name
context
Type
object
Description
An object with attributes about the user posting the message. Required attributes are timezone (in the format of Javascript Intl.DateTimeFormat().resolvedOptions().timeZone, eg: Europe/Paris), and username. Optional attributes are email, fullName and profilePictureUrl.

Optional JSON body attributes

Name
blocking
Type
boolean
Description
When set to true, the message will be posted synchronously and the response will include agentMessages. Default value is false.

Request

POST

/v1/w/:workspace_id/assistant/conversations/:conversation_id/messages

curl https://dust.tt/api/v1/w/b809011d38/assistant/conversations/7b6396245c/messages \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hi :cite[dust]{dust}!",
    "mentions": [{
      "configurationId": "dust"
    }],
    "context": {
      "timezone": "Europe/Paris",
      "username": "peter",
      "email": null,
      "fullName": "Peter Parker",
      "profilePictureUrl": "https://dust.tt/static/systemavatar/helper_avatar_full.png"
    }
  }'

Response

{
  "message": {
    "sId": "e20e7b5aac",
    "type": "user_message",
    "visibility": "visible",
    "version": 0,"user": null,
    "mentions": [{ "configurationId":"dust" }],
    "content": "Hi :cite[dust]{dust}!",
    "context": {
      "timezone": "Europe/Paris",
      "username": "peter",
      "fullName": "Peter Parker",
      "email":null,
      "profilePictureUrl": "https://dust.tt/static/systemavatar/helper_avatar_full.png"
    }
  }
}

POST/v1/w/:workspace_id/assistant/conversations/:conversation_id/content_fragments

Create a new Content Fragment

This endpoint enables you to create a new content fragment in a conversation. Content fragments are pieces of information that can be inserted in conversations and are passed as context to assistants to when they generate an answer.

URL attributes

Name
workspace_id
Type
string
Description
The ID of the workspace (can be found in the workspace's URL)
Name
conversation_id
Type
string
Description
The ID of the conversation where you want to create a content fragment.

JSON body attributes

Name
content
Type
string
Description
A string representing the content of the fragment. It must be a non-empty string of less than 64kb.
Name
title
Type
string
Description
A string representing the title of the fragment. It must be a non-empty string.

Request

POST

/v1/w/:workspace_id/assistant/conversations/:conversation_id/content_fragments

curl https://dust.tt/api/v1/w/workspace1/assistant/conversations/conversation1/content_fragments \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This is a content fragment.",
    "title": "Content Fragment Title"
  }'

Response

{
  "contentFragment": {
    "title": "Content Fragment Title",
    "content": "This is a content fragment."
  }
}

GET/v1/w/:workspace_id/assistant/conversations/:conversation_id

Retrieve a Conversation

This endpoint allows you to retrieve a Conversation. It will render the conversation in its current state (potential agent messages will still be in created state).

URL attributes

Name
workspace_id
Type
string
Description
The ID of the workspace to use (can be found in any of the workspace's URL)
Name
conversation_id
Type
string
Description
The sId of the conversation object to retrieve.

Request

GET

/v1/w/:workspace_id/assistant/conversations/:conversation_id

curl https://dust.tt/api/v1/w/3e26b0e764/assistant/conversations/7b6396245c \
  -H "Authorization: Bearer sk-..." \

Response

{
  "conversation": {
    "created": 1695901958406,
    "sId": "7b6396245c",
    "owner": {...},
    "title": "Dust Assistance",
    "visibility": "unlisted",
    "content": [
      [{
        "sId":"f635e9996a",
        "type":"user_message",
        "visibility":"visible",
        "version":0,
        "user":null,
        "mentions": [{"configurationId":"dust"}],
        "content":"Hi :cite[dust]{dust}!",
        "context": {
          "username": "peter",
          "timezone": "Europe/Paris",
          "fullName": "Peter Parker",
          "email": null,
          "profilePictureUrl": "https://dust.tt/static/systemavatar/helper_avatar_full.png"
        }
      }], [{
        "sId": "b960910cdb",
        "type": "agent_message",
        "visibility": "visible",
        "version": 0,
        "parentMessageId": "f635e9996a",
        "status": "succeeded",
        "action": {
          "type": "retrieval_action",
          "params": {
            "query": "Hi",
            "relativeTimeFrame": null,
            "topK": 32
          },
          "documents": [{
            "dataSourceId": "managed-slack",
            "sourceUrl": "https://dust4ai.slack.com/...",
            "documentId": "slack-C050S7TE50T-thread-1690811107.286489",
            "reference": "e3",
            "timestamp": 1690811107000,
            "tags": [
              "channelId:C050S7TE50T",
              "channelName:admin",
              "threadId:1690811107.286489",
              "title:admin-thread-2023-07-31_13h45"
            ],
            "score": 0.8278559,
            "chunks":[...]
          },
          ...
          ]
        },
        "content": "Hello Peter! How can I assist you today?",
        "error": null,
        "configuration":{
          "sId": "dust",
          "version": 0,
          "name": "dust",
          "description": "An assistant with context on your company data.",
          "pictureUrl": "https://dust.tt/static/systemavatar/dust_avatar_full.png",
          "status": "active",
          "scope": "global",
          "generation": {...}
          "action": {...}
        }
      }]
    ]
  }
}

GET/v1/w/:workspace_id/assistant/conversations/:conversation_id/events

Stream Conversation Events

This endpoint allows you to stream a Conversation's event (see event definitions above). Events are streamed using Server Side Rendering and wrapped in the structure:

{
  "eventId": ${INTERNAL_ID},
  "data": ${EVENT_DATA}
}

Note that events can be repeated across API calls.

URL attributes

Name
workspace_id
Type
string
Description
The ID of the workspace to use (can be found in any of the workspace's URL)
Name
conversation_id
Type
string
Description
The sId of the conversation to stream events from.

Request

GET

/v1/w/:workspace_id/assistant/conversations/:conversation_id/events

curl https://dust.tt/api/v1/w/3e26b0e764/assistant/conversations/7b6396245c/events \
  -H "Authorization: Bearer sk-..." \

Response

{
  "eventId":"1695991686152-0",
  "data": {
    "type": "user_message_new",
    "created": 1695991686151,
    "messageId": "343756bed1",
    "message": {...}
  }
}
{
  "eventId": "1695991727206-0",
  "data": {
    "type": "agent_message_new",
    "created": 1695991727204,
    "configurationId": "helper",
    "messageId": "d349842779",
    "message": {...}
  }
}

GET/v1/w/:workspace_id/assistant/conversations/:conversation_id/messages/:message_id/events

Stream Message Events

This endpoint allows you to stream a Message's event (see event definitions above). Events are streamed using Server Side Rendering and wrapped in the structure:

{
  "eventId": ${INTERNAL_ID},
  "data": ${EVENT_DATA}
}

Note that events can be repeated across API calls.

URL attributes

Name
workspace_id
Type
string
Description
The ID of the workspace to use (can be found in any of the workspace's URL)
Name
conversation_id
Type
string
Description
The sId of the conversation of the message to stream events from.
Name
message_id
Type
string
Description
The sId of the message to stream events from.

Query parameters

Query attributes are passed as GET parameters.

Name
lastEventId
Type
string
Description
If provided, the stream will start at the event with the provided ID.

Request

GET

/v1/w/:workspace_id/assistant/conversations/:conversation_id/messages/:message_id/events

curl https://dust.tt/api/v1/w/3e26b0e764/assistant/conversations/7b6396245c/messages/d349842779/events \
  -H "Authorization: Bearer sk-..." \

Response

{
  "eventId":"1695991686152-0",
  "data": {
    "type": "generation_token",
    "created": 1695991686151,
    "configurationId": "helper",
    "messageId": "d349842779",
    "text": "World"
  }
}
{
  "eventId": "1695991727206-0",
  "data": {
    "type": "generation_tokens",
    "created": 1695991727204,
    "configurationId": "helper",
    "messageId": "d349842779",
    "text": "World"
  }
}