POST
/
agents
/
{id}
/
query
Example of how to ask something to your agent via programming

Tip: On the first request, you don’t need to provide the conversationId parameter. A new ID will be generated, which you can then save and use in subsequent requests for the same conversation. This will group the messages into a single conversation.

import {
  EventStreamContentType,
  fetchEventSource,
} from '@microsoft/fetch-event-source';

let buffer = '';
let bufferEndpointResponse = '';
const ctrl = new AbortController();

await fetchEventSource(queryAgentURL, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': '{Chatvolt-API-Key}',
        },
        signal: ctrl.signal,
        body: JSON.stringify({
          streaming: false,
          query,
          conversationId, //optional
          visitorId,      //optional
        }),

        async onopen(response) {
          if (response.status === 402) {
            throw new ApiError(ApiErrorType.USAGE_LIMIT);
          }
        },
        onmessage: (event) => {
          if (event.data === '[DONE]') {
            // End of stream
            ctrl.abort();

            try {
              const { sources, conversationId, visitorId } = JSON.parse(
                bufferEndpointResponse
              ) as ChatResponse;
            } catch {}
          } else if (event.data?.startsWith('[ERROR]')) {
            // ...
          } else if (event.event === "endpoint_response") {
            bufferEndpointResponse += event.data;
          } else if (event.event === "answer") {
            buffer += event.data;
            // ...
          }
       },
  });

Authorizations

Authorization
string
headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

ID of the agent to be queried.

Body

application/json
query
string
required

Text of the question or command to be sent to the agent.

conversationId
string

ID of the existing conversation. If not provided or invalid, a new conversation will be created.

contactId
string

ID of an existing contact in the system. If provided, associates the conversation with this contact. Alternative to the contact object.

contact
object

Contact details. Used to find an existing contact (by email, phoneNumber, or userId) or create a new one if not found.

visitorId
string

ID of the visitor/participant who is sending the query. If not provided, a new ID will be generated.

temperature
number

Model temperature (min 0.0, max 1.0). Controls the randomness of the response.

modelName
string

Allows overriding the LLM model configured in the agent for this specific query. Use valid model names.

presencePenalty
number

Presence penalty (between -2.0 and 2.0). Positive values encourage the model to talk about new topics.

frequencyPenalty
number

Frequency penalty (between -2.0 and 2.0). Positive values discourage the model from repeating textual lines.

topP
number

Nucleus sampling (alternative to temperature). Considers tokens with accumulated probability mass top_p. (Ex: 0.1 considers the top 10%). It is recommended to change topP or temperature, not both.

filters
object
systemPrompt
string

Allows overriding the system prompt configured in the agent for this specific query.

context
object

Object to pass additional context data that can be used by tools or in the prompt.

callbackURL
string

Optional URL. If provided, the API will return 202 immediately and will deliver the response to the Agent via a POST request to this URL when it is ready.

Response

200 - application/json
answer
string

The agent's textual response.

conversationId
string

ID of the conversation (existing or new).

visitorId
string

ID of the visitor/participant.

messageId
string

ID of the agent's response message in the database.

sources
object[]

Datasource chunks used to generate the response (if applicable).

metadata
object

Additional metadata returned (may vary).

Was this page helpful?

AuthenticationGet Agent