Bookmark

DELTA-V Chat API

Most of the endpoints depends on various instances and are considered parameters for the actual endpoint, but these are not meant to be passed directly by the user.

Instead, these instance-dependent elements are integrated and managed directly by the backend system. We refer to them as *name_parameter, where the asterisk (*) is used to denote a specific instance-dependent parameter that the route relies on.

Mind that: to access these APIs, user must be authenticated and have the correct permissions.

Overview

The DeltaV Chat API allows you to interact with the DeltaV backend, allowing you to interact with your agents and more.

Endpoints

GET /v1beta1/engine/chat/sessions
POST /v1beta1/engine/chat/sessions
 
DELETE /v1beta1/engine/chat/sessions/:session_id
 
POST /v1beta1/engine/chat/sessions/:session_id/submit
 
GET /v1beta1/engine/chat/sessions/:session_id/responses
 
GET /v1beta1/engine/chat/sessions/:session_id/messages
 
GET /v1beta1/engine/chat/sessions/:session_id/messages/all
 
GET /v1beta1/engine/chat/sessions/:session_id/new-messages
 
POST /v1beta1/engine/chat/sessions/:session_id/feedback
 
GET /v1beta1/engine/chat/remaining_tokens

Starting your session

Endpoint: POST /v1beta1/engine/chat/sessions

Request

Start a new session for a user authenticated through JWT.

Name
payload
Type
JSON
Description
Contains the data for the type of payload being sent.
Name
email
Type
email
Description
The email of the user
Name
request_model
Type
string
Description
The request model wherein the user wants to interact.

bash

curl \
-X POST \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions \
 -d '{"email":"your_email_address","requestedModel":"talkative-01"}'

Responses

Returns the newly created Session object

json

[
  {
    "session_id": "c320b5c4-518c-428b-889d-3cb8403901c0",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "bucket_id": null,
    "model": "talkative-01",
    "remaining_tokens": 10000000
  }
]

Get all sessions for a user

Endpoint: GET /v1beta1/engine/chat/sessions

Request

Retrieves all sessions for a user authenticated through JWT.

bash

curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions

Responses

Returns a list of Session objects associated with the user

json

[
  {
    "session_id": "7be16891-39a6-44a6-88cb-377250dd8eb7",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "bucket_id": null,
    "model": "talkative-01",
    "remaining_tokens": 9999099
  },
  {
    "session_id": "aed47bb4-9d73-4135-89f7-925036aa83bd",
    "user": "YOUR_CLIENT_UID",
    "num_messages": 0,
    "last_message_timestamp": null,
    "messages": [],
    "bucket_id": "ef6937d9-c086-4785-8bb1-748680821714",
    "model": "talkative-01",
    "remaining_tokens": 9999099
  }
]

Sending a new message

There are 4 types of messages that can be sent to the backend:

start: This is the first message that should be sent to the backend. It contains the objective and context of the conversation. The objective and context are used to determine which agent to use for the conversation.
user_message: This is a message sent by the user.
user_json: This is a JSON message sent by the user.
stop: This is the last message that should be sent to the backend. It indicates that the conversation has ended.

Sending start message

Endpoint: POST /v1beta1/engine/chat/sessions/{session_id}/submit

Request

Sending start message

Name
payload
Type
JSON
Description
Contains the data for the type of message being sent.
Name
type
Type
string
Description
The type of message being sent.
Name
objective
Type
string
Description
The objective of the conversation. This is used to determine which agent to use for the conversation.
Name
context
Type
string
Description
The context of the conversation. This is used to give information about the user to the agent.
Name
session_id
Type
string
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

bash

curl \
-X POST \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit \
 -d '{"payload":{"type":"start","objective":"I'd like to go to London","context":"User full Name: Test User\nUser email: [email protected]\nUser location: latitude=51.5072, longitude=0.1276\n"}}'

Sending user message

Endpoint: POST /v1beta1/engine/chat/sessions/{session_id}/submit

Request

Send an answer to a question asked by the agent

Name
payload
Type
JSON
Description
Contains the data for the type of message being sent.
Name
type
Type
string
Description
The type of message being sent.
Name
user_message
Type
string
Description
The user response to a question asked by the agent or to confirm the context
Name
session_id
Type
string
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

bash

curl \
-X POST \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit \
 -d '{"payload":{"type":"user_message","user_message":"The booking is for 2 people"}}'

Sending user json message

Endpoint: POST /v1beta1/engine/chat/sessions/{session_id}/submit

Request

Request for creating a new agent

Name
payload
Type
JSON
Description
Contains the data for the type of message being sent. The payload is different for each type of message.
Name
type
Type
string
Description
The type of message being sent.
Name
user_json
Type
JSON
Description
The objective of the conversation. This is used to determine which agent to use for the conversation.
Name
user_json-type
Type
string
Description
The context of the conversation. type: `task_list`, `options`. `task_list` is used to select a task pertaining to a specific agent. `options` is used to select a subtask pertaining to a specific agent or select an option from a list of suggestions given by the agent.
Name
user_json-selection
Type
array
Description
The selection of the user from the list of options. The selection is an array of integers or UUID4
Name
session_id
Type
string
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

bash

curl \
-X POST \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit \
 -d '{"payload":{"type":"user_json","user_json":{"type":"task_list | options","selection":["0 | 9f157712-472d-4f0d-814d-d5aae9fd7b28"]}}}'

Sending stop message

Endpoint: POST /v1beta1/engine/chat/sessions/{session_id}/submit

Request

Request for creating a new agent

Name
payload
Type
JSON
Description
Contains the data for the type of message being sent. The payload is different for each type of message.
Name
type
Type
string
Description
The type of message being sent.
Name
session_id
Type
string
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

bash

curl \
-X POST \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/submit \
 -d '{"payload":{"type":"stop"}}'

Delete a session for a user

Endpoint: DELETE /v1beta1/engine/chat/sessions/{session_id}

Request

Delete a specific session given a session id for a user authenticated through JWT.

bash

curl \
-X DELETE \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}

Fetch new messages sent by agent

Endpoint: GET /v1beta1/engine/chat/sessions/{session_id}/responses

Request

Fetches new messages for a specific session identified by the session_id

bash

curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/responses

Responses

Return an agent_response object containing the agent response in JSON format, which can be parsed to retrieve the agent message. It can be an AgentMessage or an AgentJsonMessage. They are almost similar to user_message and user_json_message, but they are sent by the agent.

json

[
  {
    "agent_response": "{\"message_id\": \"c5c27376-0edc-41db-ae7b-980b4a6bfe8b\", \"timestamp\": \"2023-08-31T13:10:48.941865\", \"score\": 0.0, \"type\": \"agent_json\", \"agent_json\": {\"type\": \"task_list\", \"text\": \"Found tasks for your objective. Please select.\", \"options\": [{\"key\": 0, \"value\": \"TopActivities/TopActivities\"}, {\"key\": 1, \"value\": \"Flights/Flights\"}, {\"key\": 2, \"value\": \"Hotels/Hotels\"}], \"context_json\": null}}"
  }
]

Fetch recent messages given a timestamp

Endpoint: GET /v1beta1/engine/chat/sessions/{session_id}/messages?from_timestamp=2023-08-31T13:26:30.941865

Request

Fetches agent messages filtered by timestamps for a specific session identified by the session_id

Name
from_timestamp
Type
datetime
Description
The timestamp from which to fetch the agent messages. The timestamp is in ISO 8601 format.
Name
session_id
Type
string
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

bash

curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/messages?from_timestamp=2023-08-31T13:26:30.941865

Responses

Return the most recent list of agent messages given a timestamp. The timestamp is in ISO 8601 format.

json

[
  {
    "session_id": "063fcfef-a3ec-46c4-aa8e-c9a51b6f24b7",
    "messages": [
      {
        "message_id": "922c9be4-28dd-4fdb-9b91-fc26f360d86c",
        "timestamp": "2023-08-31T13:26:42.093485",
        "score": 0,
        "type": "agent_info",
        "agent_info": "I start building the context to execute 'TopActivities/TopActivities' task.."
      },
      {
        "message_id": "2969efc7-4a8b-46e1-8c9e-fb86dbe3f5fb",
        "timestamp": "2023-08-31T13:26:51.744958",
        "score": 0,
        "type": "agent_json",
        "agent_json": {
          "type": "context_json",
          "text": "Can you confirm the following context?",
          "options": null,
          "context_json": {
            "digest": "model:77dcd01525f6f2f58bc5035942725bd57be171a9af44d2f19b796a01bd52cd91",
            "args": {
              "city": "London",
              "date": "[date]",
              "preferred_activities": ""
            }
          }
        }
      }
    ]
  }
]

Fetch all messages sent by agent in a session

Endpoint: GET /v1beta1/engine/chat/sessions/{session_id}/messages/all

Request

Fetches agent messages filtered by timestamps for a specific session identified by the session_id

bash

curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/messages/all

Responses

Return all the messages sent by the agent for a specific session.

json

[
  {
    "session_id": "063fcfef-a3ec-46c4-aa8e-c9a51b6f24b7",
    "messages": [
      {
        "message_id": "24df920c-a8eb-41cb-aa10-4283d0602d5e",
        "timestamp": "2023-08-31T13:26:23.238697",
        "score": 0,
        "type": "agent_json",
        "agent_json": {
          "type": "task_list",
          "text": "Found tasks for your objective. Please select.",
          "options": [
            {
              "key": 0,
              "value": "TopActivities/TopActivities"
            },
            {
              "key": 1,
              "value": "Flights/Flights"
            },
            {
              "key": 2,
              "value": "Hotels/Hotels"
            }
          ],
          "context_json": null
        }
      },
      {
        "message_id": "922c9be4-28dd-4fdb-9b91-fc26f360d86c",
        "timestamp": "2023-08-31T13:26:42.093485",
        "score": 0,
        "type": "agent_info",
        "agent_info": "I start building the context to execute 'TopActivities/TopActivities' task.."
      },
      {
        "message_id": "2969efc7-4a8b-46e1-8c9e-fb86dbe3f5fb",
        "timestamp": "2023-08-31T13:26:51.744958",
        "score": 0,
        "type": "agent_json",
        "agent_json": {
          "type": "context_json",
          "text": "Can you confirm the following context?",
          "options": null,
          "context_json": {
            "digest": "model:77dcd01525f6f2f58bc5035942725bd57be171a9af44d2f19b796a01bd52cd91",
            "args": {
              "city": "London",
              "date": "[date]",
              "preferred_activities": ""
            }
          }
        }
      }
    ]
  }
]

Retrieve new messages sent by agent (with possible duplicate or missed messages)

Endpoint: GET /v1beta1/engine/chat/sessions/{session_id}/new-messages

Request

Retrieves a batch of new messages since the last retrieved message for a specific chat session.

Name
session_id
Type
UUID4
Description
The unique identifier of the chat session. It must be a valid UUID4 string.
Name
last_message_id
Type
string
Required
optional
Description
The message ID of the last message that was retrieved. This is optional and, if provided, the service will return messages that were sent after this message.

bash

curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/new-messages

Responses

Returns a list of new messages for the session, if specified then returns the messages since the last checked message. If there are no new messages, an empty list is returned. If the session is not found, a 404 error with a descriptive message is returned.

json

[
  {
    "status": 200,
    "agent_response": [
      {
        "session_id": "063fcfef-a3ec-46c4-aa8e-c9a51b6f24b7",
        "messages": [
          {
            "message_id": "24df920c-a8eb-41cb-aa10-4283d0602d5e",
            "timestamp": "2023-08-31T13:26:23.238697",
            "score": 0,
            "type": "agent_json",
            "agent_json": {
              "type": "task_list",
              "text": "Found tasks for your objective. Please select.",
              "options": [
                {
                  "key": 0,
                  "value": "TopActivities/TopActivities"
                },
                {
                  "key": 1,
                  "value": "Flights/Flights"
                },
                {
                  "key": 2,
                  "value": "Hotels/Hotels"
                }
              ],
              "context_json": null
            }
          },
          {
            "message_id": "922c9be4-28dd-4fdb-9b91-fc26f360d86c",
            "timestamp": "2023-08-31T13:26:42.093485",
            "score": 0,
            "type": "agent_info",
            "agent_info": "I start building the context to execute 'TopActivities/TopActivities' task.."
          },
          {
            "message_id": "2969efc7-4a8b-46e1-8c9e-fb86dbe3f5fb",
            "timestamp": "2023-08-31T13:26:51.744958",
            "score": 0,
            "type": "agent_json",
            "agent_json": {
              "type": "context_json",
              "text": "Can you confirm the following context?",
              "options": null,
              "context_json": {
                "digest": "model:77dcd01525f6f2f58bc5035942725bd57be171a9af44d2f19b796a01bd52cd91",
                "args": {
                  "city": "London",
                  "date": "[date]",
                  "preferred_activities": ""
                }
              }
            }
          }
        ]
      }
    ]
  }
]

Provide feedback for a session

Endpoint: POST /v1beta1/engine/chat/sessions/{session_id}/feedback

Request

Give feedback for a specific session identified by the session_id

Name
models
Type
array
Description
Contains the list of models that the user wants to query for remaining tokens. It is an array of strings where each string is the name of the model.
Name
feedback
Type
string
Description
The feedback of the user. It can be positive or negative.
Name
session_id
Type
string
Description
The session ID, obtained from the Create Session API, uniquely identifies a session

bash

curl \
-X POST \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/chat/sessions/{session_id}/feedback \
 -d '{"feedback":"positive"}'

Responses

On a successful request returns the remaining tokens for the models that have been queried

json

{
  "model_tokens": {
    "talkative-01": 9999099,
    "creative-01": 5000000
  }
}

Retrieve remaining tokens

Endpoint: GET /v1beta1/engine/credit/remaining_tokens?models=talkative-01,creative-01&[email protected]

Request

Request for retrieving the amount of tokens left for each model

Name
models
Type
array
Description
Contains the list of models that the user wants to query for remaining tokens. It is an array of strings where each string is the name of the model.
Name
email
Type
string
Description
The email of the user

bash

curl \
-X GET \
-H Authorization: bearer <your token here> \
https://agentverse.ai/v1beta1/engine/credit/remaining_tokens?models=talkative-01,creative-01&[email protected]

Responses

On a successful request returns the remaining tokens for the models that have been queried

json

{
  "model_tokens": {
    "talkative-01": 9999099,
    "creative-01": 5000000
  }
}

Was this page helpful?

Fetch Page 🛠️📲Services API