GET
/
conversation

​
Example JS Code to Get Conversations by Date

const apiUrl = 'https://api.chatvolt.ai';
const apiKey = 'XXX';

const res = await fetch(
  `${apiUrl}/conversation?agentId=XXX&createdAt=2024-11-01 00:00:00&status=RESOLVED`,
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  }
);

​
Response Body

The response will be an array of conversation objects. Each object will contain the following fields:

  • id: The conversation ID.
  • title: The title of the conversation.
  • assignees: An array of objects containing the id and email of the users assigned to the conversation.
  • ... and other conversation fields.

​
Example Response

[
  {
    "id": "some_conversation_id",
    "title": "A conversation",
    "assignees": [
      {
        "id": "user_id_1",
        "email": "user1@example.com"
      }
    ]
  }
]

Authorizations

Authorization
string
headerrequired

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

Query Parameters

agentId
string

Agent ID to filter conversations. If 'null' (string), searches for conversations not assigned to any agent. Optional.

channel
string

Channel filter. Optional.

createdAt
string

Filters conversations created from this date/time (inclusive). Accepted formats include 'YYYY-MM-DD HH:mm:ss', 'YYYY-MM-DD HH:mm', 'YYYY-MM-DD', or a complete ISO 8601 format. Optional.

endDate
string

Filters conversations created until this date/time (inclusive). Accepted formats include 'YYYY-MM-DD HH:mm:ss' or complete ISO 8601 format. Optional.

status
enum<string>

Filters conversations by status. Optional.

Available options:
RESOLVED,
UNRESOLVED,
HUMAN_REQUESTED
priority
enum<string>

Filters conversations by priority. Optional.

Available options:
LOW,
MEDIUM,
HIGH
assigneeId
string

Filters by the assigned membership ID, or 'unassigned' for conversations without assignees. Optional.

unread
boolean

If true, filters only conversations that have unread messages. Optional.

tag
string

Filters conversations by a specific tag. Optional.

ai
enum<string>

Filters conversations based on their AI enabled state. Optional.

Available options:
enabled,
disabled
adSourceId
string

Filters conversations originating from a specific Meta Ad source ID. Optional.

crmScenarioId
string

Filters conversations that are active in a specific CRM scenario. Optional.

crmStepId
string

Filters conversations that are active in a specific CRM step. Must be used with crmScenarioId. Optional.

frustrationMin
number

Minimum frustration score (0 to 1). Optional.

frustrationMax
number

Maximum frustration score (0 to 1). Optional.

limit
integer
default: 25

Number of conversations to return (maximum 100, defaults to 25). Optional.

cursor
string

Cursor for pagination. A URL-safe JSON string containing lastCreatedAt and lastId (e.g. {"lastCreatedAt":"2026-06-08T15:00:00.000Z","lastId":"some-id"}). Optional.

Response

200 - application/json
id
string

The unique identifier for the conversation

title
string | null

The title of the conversation, if available

unreadMessagesCount
integer

The number of unread messages in the conversation

isAiEnabled
boolean

Indicates whether AI is enabled for the conversation

channel
string

The channel through which the conversation took place (e.g., 'dashboard', 'whatsapp')

status
enum<string>

The current status of the conversation

Available options:
RESOLVED,
UNRESOLVED,
HUMAN_REQUESTED
blocked
boolean

Indicates whether the conversation is blocked

metadata
object | null

Metadata associated with the conversation, if any

channelExternalId
string | null

External ID of the channel, if any

channelCredentialsId
string | null

ID of the credentials used for the channel

organizationId
string

The organization ID associated with the conversation

mailInboxId
string | null

The mailbox ID, if relevant

priority
enum<string>

The priority of the conversation

Available options:
LOW,
MEDIUM,
HIGH
formId
string | null

ID of the form used, if any

agentId
string | null

The ID of the agent handling the conversation

userId
string | null

The ID of the user associated with the conversation

visitorId
string | null

The ID of the visitor, if applicable

isGroup
boolean

Indicates whether the conversation is a group conversation

frustration
number | null

Frustration level of the conversation, if applicable

aiUserIdentifier
string | null

AI user identifier

whatsappChatLid
string | null

WhatsApp Chat LID

npsStep
integer

Current step of the NPS flow

npsRating
integer | null

NPS rating score

npsComment
string | null

NPS comment

npsStartedAt
string | null

Timestamp when the NPS flow was started

npsCompletedAt
string | null

Timestamp when the NPS flow was completed

createdAt
string

The date and time when the conversation was created

updatedAt
string

The date and time when the conversation was last updated

lastHumanInteractionAt
string | null

Timestamp of the last human interaction

participantsContacts
object[]

List of contacts associated with the conversation

ctwaAttributions
object[]

Contact click-to-WhatsApp attributions

conversationVariables
object[]

List of variables associated with the conversation

conversationContexts
object[]

List of contexts associated with the conversation.

assignees
object[]

List of assignees for the conversation.

tags
object[]

List of tags associated with the conversation.

crmScenarioConversations
object[]

Lista de vínculos entre a conversa e cenários CRM.

Was this page helpful?

Get one MessageGet Conversation By Id