Add analytics to any OpenAI compatible chat
With Inkeep’s Analytics API, you can log your AI chat conversations to:
- Get Inkeep’s analytics and reporting for the chats
- Provide and track “Thumbs up/down” feedback
- Power “Share” or “Saved Chats” experiences
The Inkeep Analytics API is designed to be flexible and can log any OpenAI-compatible conversation, including those with tool calls or custom functionality.
If you’re using Inkeep’s Chat API to create your own chat UX or custom copilot, you should use the Analytics API to enable the same reporting as provided by the @inkeep/uikit
component library.
Get an API key
You can use any API key generated for any Integration, including the one you use to call the Inkeep Chat API.
Log a conversation
Initial message
To log a new conversation, make a POST request to the /conversations
endpoint.
const initialConversationData = {
id: "conv_1234", // optional
type: "openai",
messages: [
{
role: "user",
content: "Can I log any OpenAI-compatible conversation?"
},
{
role: "assistant",
content: "Yes, our analytics engine is agnostic. You can log full conversations of your agent or custom copilot, even if not all interactions hit Inkeep's API endpoint."
}
],
properties: {
// Add any custom properties here
},
userProperties: {
// Add any user-specific properties here
}
};
let currentConversation = await fetch('https://api.analytics.inkeep.com/conversations', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify(initialConversationData)
}).then(response => {
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return response.json();
});
console.log(currentConversation);
Follow-up messages
To log additional messages in an existing conversation, include the id
returned from the initial submission:
const continueConversationData = {
id: currentConversation.id,
type: "openai",
messages: [
...currentConversation.messages,
// Add new messages
{
role: "user",
content: "Does that mean it supports logging tool calls?"
},
{
role: "assistant",
content: "Yup, Inkeep's Analytics API is fully compatible with OpenAI chat completions endpoints, including tool calling."
}
]
};
currentConversation = await fetch('https://api.analytics.inkeep.com/conversations', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify(continueConversationData)
}).then(response => {
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return response.json();
});
console.log(currentConversation);
POST /conversation
works like an upsert operation.Submit feedback
Use the /feedback
endpoint to log 👍 / 👎 feedback from your UI.
const feedbackData = {
type: "positive", // or "negative"
messageId: "{assistant_message_id}", // e.g. currentConversation.messages[1].id
reasons: [
{
label: "accurate_code_snippet",
details: "The code worked perfectly."
}
],
userProperties: {
// Add any user-specific properties here
}
};
fetch('https://api.analytics.inkeep.com/feedback', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify(feedbackData)
})
.then(response => response.json())
.then(data => console.log(data));
Monitor
To view analytics for your logged conversations and feedback:
- Go to portal.inkeep.com
- Navigate to Projects and select the relevant one
- View the Chat Sessions, Insights, and Analytics tabs
Use for “Share” or “Saved Chats”
You can use the GET /conversations
endpoint to retrieve logged conversations and power “Share” or “Saved Chats” features.
Here’s an example of how to fetch a specific conversation:
fetch('https://api.analytics.inkeep.com/conversations/{existing_conversation_id}', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
})
.then(response => response.json())
.then(data => {
// Use the conversation data to rehydrate your UI
console.log(data);
});
The response will contain detailed information about the conversation:
{
"id": "conv_123456789",
"type": "openai",
"createdAt": "2024-07-11T10:15:30.123Z",
"updatedAt": "2024-07-11T10:16:45.678Z",
"projectId": "proj_987654321",
"integrationId": "intg_246813579",
"properties": {
"source": "web_chat"
},
"userProperties": {
"userId": "user_135792468"
},
"messages": [
{
"id": "msg_1",
"type": "openai",
"conversationId": "conv_123456789",
"createdAt": "2024-07-11T10:15:30.123Z",
"updatedAt": "2024-07-11T10:15:30.123Z",
"role": "user",
"content": "Can I log any OpenAI-compatible conversation?",
"name": null,
"links": null,
"properties": {},
"userProperties": {}
},
{
"id": "msg_2",
"type": "openai",
"conversationId": "conv_123456789",
"createdAt": "2024-07-11T10:15:40.456Z",
"updatedAt": "2024-07-11T10:15:40.456Z",
"role": "assistant",
"content": "Yes, our analytics engine is agnostic. You can log full conversations of your agent or custom copilot, even if not all interactions hit Inkeep's API endpoint.",
"name": null,
"links": null,
"properties": {},
"userProperties": {}
},
{
"id": "msg_3",
"type": "openai",
"conversationId": "conv_123456789",
"createdAt": "2024-07-11T10:16:15.789Z",
"updatedAt": "2024-07-11T10:16:15.789Z",
"role": "user",
"content": "Does that mean it supports logging tool calls?",
"name": null,
"links": null,
"properties": {},
"userProperties": {}
},
{
"id": "msg_4",
"type": "openai",
"conversationId": "conv_123456789",
"createdAt": "2024-07-11T10:16:45.678Z",
"updatedAt": "2024-07-11T10:18:45.678Z",
"role": "assistant",
"content": "Yup, Inkeep's Analytics API is fully compatible with OpenAI chat completion endpoints, including tool calling.",
"name": null,
"links": null,
"properties": {},
"userProperties": {}
}
],
"messagesOpenAIFormat": [
{
"role": "user",
"content": "Can I log any OpenAI-compatible conversation?"
},
{
"role": "assistant",
"content": "Yes, Inkeep's analytics engine is agnostic. You can log full conversations of your agent or custom copilot, even if not all interactions hit Inkeep's API endpoint."
},
{
"role": "user",
"content": "Does that mean it supports logging tool calls?"
},
{
"role": "assistant",
"content": "Yup, Inkeep's Analytics API is fully compatible with OpenAI chat completions endpoints, including tool calling."
}
]
}
This response includes all extended details about the conversation and its messages, including any properties you associated with it.
The messagesOpenAIFormat
property provides the messages of the conversation in a format compatible with OpenAI’s chat completions API. You can use this to implement Share a chat, Saved Chats, or any other functionality that requires retrieving an existing chat.
Here’s how:
- Share a chat - Create an entry point in your application or UI that parses a query parameter, e.g.
?chatId=<id>
. Then, use theGET /conversations/{id}
endpoint to get the last state of a conversation and hydrate the chat UI in your own application. If you want to be able to “fork” shared chats, then simply use a differentid
when logging the continuation of a shared conversation toPOST /conversations
. This will log it as a separate conversation from the original. - Saved Chats - Whenever a user creates a new conversation, associate that
id
with the user in your database or application. This way, you have a relationship ofchats<>user
and can display a user’s history in your UI. You can also store that relationship in a user’s browser session for unauthenticated contexts.
Log usage events
In addition to logging conversations and feedback, you can also track specific usage events related to conversations or messages using the /events
endpoint.
For example, you may want to track events like:
message:copied
: When a user copies a messagemessage:code_snippet:copied
: When a user runs a code snippet from a messageconversation:shared
: When a user shares a conversation
When logged, they will be incorporated in the Inkeep Analytics reporting.
The below shows an example of how to log these events.
// Message event
const eventData = {
type: "message:copied",
entityType: "message" // 'message' or 'conversation'
messageId: "{message_id}",
};
fetch('https://api.analytics.inkeep.com/events', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify(eventData)
})
.then(response => response.json())
.then(data => console.log(data));
// Conversation Event
const conversationEventData = {
type: "conversation:shared",
entityType: "conversation"
conversationId: "{conversation_id}",
};
fetch('https://api.analytics.inkeep.com/events', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify(conversationEventData)
})
.then(response => response.json())