Chats API
List chats
Newest first. Messages are left out of the list; fetch one chat for them.
Query parameters
Default 50
Returns
200 with the fields below.
Chats, newest first. Messages are left out; fetch one chat to read them.
15 properties
The chat's id. Same as `chat_id`.
The chat's id.
Always `api_chat`: a chat started through the API.
`ongoing` or `ended`.
The agent the chat is with.
The agent version the chat runs. 0 is the live draft.
The JSON object you attached to the chat. Empty when you attached none.
The values that fill `{{name}}` placeholders in the agent's prompt for this chat.
How many user and agent messages the chat holds.
The conversation as plain text, one line per message.
Show 5 more parameters
Start time in milliseconds since the Unix epoch.
End time in milliseconds since the Unix epoch. Null while the chat is ongoing.
Why the chat ended, such as `user_ended` or `agent_ended`. Null while it is ongoing.
The post-chat analysis, with `call_summary`, `user_sentiment`, `call_successful` and your custom fields under `variables`. Null until analysis has run.
What the chat has cost. Hidden (null) for dashboard users with the member role, since spend is visible to owners and admins only.
2 properties
What the chat has cost so far, in units of $0.0001.
How many agent replies were billed.
True when more chats follow this page.
Pass this as `pagination_key` to fetch the next page. Null on the last page.
curl "https://api.dialgem.com/v1/chats" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"chats": [
{
"id": "string",
"chat_id": "chat_123",
"chat_type": "string",
"chat_status": "string",
"agent_id": "agent_123",
"agent_version": 0,
"metadata": {},
"dynamic_variables": {},
"start_timestamp": 0,
"end_timestamp": 0,
"end_reason": "string",
"message_count": 0
}
],
"has_more": false,
"pagination_key": "string"
}Create chat
Start a chat. If the agent has a first message it is already in `messages`.
Request body application/json
Returns
201 with the fields below.
The chat's id. Same as `chat_id`.
The chat's id.
Always `api_chat`: a chat started through the API.
`ongoing` or `ended`.
The agent the chat is with.
The agent version the chat runs. 0 is the live draft.
The JSON object you attached to the chat. Empty when you attached none.
The values that fill `{{name}}` placeholders in the agent's prompt for this chat.
How many user and agent messages the chat holds.
The conversation as plain text, one line per message.
Show 6 more parameters
Every message in order, including tool calls and their results.
4 properties
The message's id.
`user`, `agent`, `tool_call_invocation` or `tool_call_result`.
The message text. Empty for a tool call invocation.
When the message was created, in milliseconds since the Unix epoch.
Start time in milliseconds since the Unix epoch.
End time in milliseconds since the Unix epoch. Null while the chat is ongoing.
Why the chat ended, such as `user_ended` or `agent_ended`. Null while it is ongoing.
The post-chat analysis, with `call_summary`, `user_sentiment`, `call_successful` and your custom fields under `variables`. Null until analysis has run.
What the chat has cost. Hidden (null) for dashboard users with the member role, since spend is visible to owners and admins only.
2 properties
What the chat has cost so far, in units of $0.0001.
How many agent replies were billed.
curl -X POST "https://api.dialgem.com/v1/chats" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_123"
}'{
"id": "string",
"chat_id": "chat_123",
"chat_type": "string",
"chat_status": "string",
"agent_id": "agent_123",
"agent_version": 0,
"metadata": {},
"dynamic_variables": {},
"start_timestamp": 0,
"end_timestamp": 0,
"end_reason": "string",
"message_count": 0
}Get chat
Path parameters
Returns
200 with the fields below.
The chat's id. Same as `chat_id`.
The chat's id.
Always `api_chat`: a chat started through the API.
`ongoing` or `ended`.
The agent the chat is with.
The agent version the chat runs. 0 is the live draft.
The JSON object you attached to the chat. Empty when you attached none.
The values that fill `{{name}}` placeholders in the agent's prompt for this chat.
How many user and agent messages the chat holds.
The conversation as plain text, one line per message.
Show 6 more parameters
Every message in order, including tool calls and their results.
4 properties
The message's id.
`user`, `agent`, `tool_call_invocation` or `tool_call_result`.
The message text. Empty for a tool call invocation.
When the message was created, in milliseconds since the Unix epoch.
Start time in milliseconds since the Unix epoch.
End time in milliseconds since the Unix epoch. Null while the chat is ongoing.
Why the chat ended, such as `user_ended` or `agent_ended`. Null while it is ongoing.
The post-chat analysis, with `call_summary`, `user_sentiment`, `call_successful` and your custom fields under `variables`. Null until analysis has run.
What the chat has cost. Hidden (null) for dashboard users with the member role, since spend is visible to owners and admins only.
2 properties
What the chat has cost so far, in units of $0.0001.
How many agent replies were billed.
curl "https://api.dialgem.com/v1/chats/CHAT_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"chat_id": "chat_123",
"chat_type": "string",
"chat_status": "string",
"agent_id": "agent_123",
"agent_version": 0,
"metadata": {},
"dynamic_variables": {},
"start_timestamp": 0,
"end_timestamp": 0,
"end_reason": "string",
"message_count": 0
}Update chat
Replace the chat's metadata (the whole object, like a call's).
Path parameters
Request body application/json
Returns
200 with the fields below.
The chat's id. Same as `chat_id`.
The chat's id.
Always `api_chat`: a chat started through the API.
`ongoing` or `ended`.
The agent the chat is with.
The agent version the chat runs. 0 is the live draft.
The JSON object you attached to the chat. Empty when you attached none.
The values that fill `{{name}}` placeholders in the agent's prompt for this chat.
How many user and agent messages the chat holds.
The conversation as plain text, one line per message.
Show 6 more parameters
Every message in order, including tool calls and their results.
4 properties
The message's id.
`user`, `agent`, `tool_call_invocation` or `tool_call_result`.
The message text. Empty for a tool call invocation.
When the message was created, in milliseconds since the Unix epoch.
Start time in milliseconds since the Unix epoch.
End time in milliseconds since the Unix epoch. Null while the chat is ongoing.
Why the chat ended, such as `user_ended` or `agent_ended`. Null while it is ongoing.
The post-chat analysis, with `call_summary`, `user_sentiment`, `call_successful` and your custom fields under `variables`. Null until analysis has run.
What the chat has cost. Hidden (null) for dashboard users with the member role, since spend is visible to owners and admins only.
2 properties
What the chat has cost so far, in units of $0.0001.
How many agent replies were billed.
curl -X PATCH "https://api.dialgem.com/v1/chats/CHAT_ID" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'{
"id": "string",
"chat_id": "chat_123",
"chat_type": "string",
"chat_status": "string",
"agent_id": "agent_123",
"agent_version": 0,
"metadata": {},
"dynamic_variables": {},
"start_timestamp": 0,
"end_timestamp": 0,
"end_reason": "string",
"message_count": 0
}Delete chat
Path parameters
Returns
200 with the fields below.
Always true on success.
The id of the chat that was deleted.
curl -X DELETE "https://api.dialgem.com/v1/chats/CHAT_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"deleted": false,
"id": "string"
}Send message
Send the user's message and wait for the agent's reply.
Path parameters
Request body application/json
Returns
200 with the fields below.
The chat the message went to.
`ongoing`, or `ended` if the agent ended the chat with this reply.
The new messages in order: yours, any tool use, then the agent's reply.
4 properties
The message's id.
`user`, `agent`, `tool_call_invocation` or `tool_call_result`.
The message text. Empty for a tool call invocation.
When the message was created, in milliseconds since the Unix epoch.
curl -X POST "https://api.dialgem.com/v1/chats/CHAT_ID/messages" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "string"
}'{
"chat_id": "chat_123",
"chat_status": "string",
"messages": [
{
"message_id": "message_123",
"role": "string",
"content": "string",
"created_timestamp": 0
}
]
}End chat
End the chat. Ending twice is fine and changes nothing. The analysis arrives a moment later.
Path parameters
Returns
200 with the fields below.
The chat's id. Same as `chat_id`.
The chat's id.
Always `api_chat`: a chat started through the API.
`ongoing` or `ended`.
The agent the chat is with.
The agent version the chat runs. 0 is the live draft.
The JSON object you attached to the chat. Empty when you attached none.
The values that fill `{{name}}` placeholders in the agent's prompt for this chat.
How many user and agent messages the chat holds.
The conversation as plain text, one line per message.
Show 6 more parameters
Every message in order, including tool calls and their results.
4 properties
The message's id.
`user`, `agent`, `tool_call_invocation` or `tool_call_result`.
The message text. Empty for a tool call invocation.
When the message was created, in milliseconds since the Unix epoch.
Start time in milliseconds since the Unix epoch.
End time in milliseconds since the Unix epoch. Null while the chat is ongoing.
Why the chat ended, such as `user_ended` or `agent_ended`. Null while it is ongoing.
The post-chat analysis, with `call_summary`, `user_sentiment`, `call_successful` and your custom fields under `variables`. Null until analysis has run.
What the chat has cost. Hidden (null) for dashboard users with the member role, since spend is visible to owners and admins only.
2 properties
What the chat has cost so far, in units of $0.0001.
How many agent replies were billed.
curl -X POST "https://api.dialgem.com/v1/chats/CHAT_ID/end" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"chat_id": "chat_123",
"chat_type": "string",
"chat_status": "string",
"agent_id": "agent_123",
"agent_version": 0,
"metadata": {},
"dynamic_variables": {},
"start_timestamp": 0,
"end_timestamp": 0,
"end_reason": "string",
"message_count": 0
}Rerun chat analysis
Analyse an ended chat again with the agent's *current* analysis settings and return it.
Path parameters
Returns
200 with the fields below.
The chat's id. Same as `chat_id`.
The chat's id.
Always `api_chat`: a chat started through the API.
`ongoing` or `ended`.
The agent the chat is with.
The agent version the chat runs. 0 is the live draft.
The JSON object you attached to the chat. Empty when you attached none.
The values that fill `{{name}}` placeholders in the agent's prompt for this chat.
How many user and agent messages the chat holds.
The conversation as plain text, one line per message.
Show 6 more parameters
Every message in order, including tool calls and their results.
4 properties
The message's id.
`user`, `agent`, `tool_call_invocation` or `tool_call_result`.
The message text. Empty for a tool call invocation.
When the message was created, in milliseconds since the Unix epoch.
Start time in milliseconds since the Unix epoch.
End time in milliseconds since the Unix epoch. Null while the chat is ongoing.
Why the chat ended, such as `user_ended` or `agent_ended`. Null while it is ongoing.
The post-chat analysis, with `call_summary`, `user_sentiment`, `call_successful` and your custom fields under `variables`. Null until analysis has run.
What the chat has cost. Hidden (null) for dashboard users with the member role, since spend is visible to owners and admins only.
2 properties
What the chat has cost so far, in units of $0.0001.
How many agent replies were billed.
curl -X POST "https://api.dialgem.com/v1/chats/CHAT_ID/rerun-analysis" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"chat_id": "chat_123",
"chat_type": "string",
"chat_status": "string",
"agent_id": "agent_123",
"agent_version": 0,
"metadata": {},
"dynamic_variables": {},
"start_timestamp": 0,
"end_timestamp": 0,
"end_reason": "string",
"message_count": 0
}