Agent API/Conversations
Get Conversation History
Retrieve the full conversation history including all messages exchanged.
Book appointments: Assistant messages that confirmed an appointment also include bookingCard (same shape as Send Message: when, confirmation code, and calendarUrl for an .ics file). If you are not using scheduling, this field is never returned.
Product cards: Assistant messages that showed a product also include productCards (same shape as Send Message).
GET
https://agent.askhandle.com/api/v1/public/conversations/{conversationId}Requires X-API-Key — Your public API key (starts with pk_live_)
Best practice
Timeouts. Use this to pick up a reply when Send Message timed out.
- Poll every 2 seconds, for up to a minute.
- Do not resend the user message while you are polling.
- An unchanged list means the turn is still running, or it failed.
Request
Headers
X-API-Keystringrequired
Your public API key
Query Parameters
conversationIdstringrequired
The conversation ID
Response
Success 200
JSON
{
"conversationId": "conv_abc123def456",
"messages": [
{
"role": "assistant",
"content": "👋 Welcome! How can I help you today?"
},
{
"role": "user",
"content": "I need help with my order"
},
{
"role": "assistant",
"content": "I'd be happy to help! What's your order number?"
}
]
}Errors
401
API key is missing or invalid
Error
{
"error": "Missing API key. Include X-API-Key header."
}404
Conversation doesn't exist or has expired
Error
{
"error": "Conversation not found or expired."
}Code examples
const conversationId = 'conv_abc123def456';
const response = await fetch(
`https://agent.askhandle.com/api/v1/public/conversations/${conversationId}`,
{
headers: {
'X-API-Key': 'pk_live_your_api_key_here'
}
}
);
const data = await response.json();
console.log('Conversation history:', data.messages);