Agent API/Conversations
Send Message
Send a message in an existing conversation. The AI agent processes the message and returns the reply on this same request. There is no separate stream.
Human Handoff: If the AI agent includes a Human Handoff node, the response may contain ended: true, which means the conversation has been transferred and closed. A support ticket or conversation has been created in the configured platform (HubSpot or Intercom) for a human agent to follow up.
Book appointments: If this agent has the Book appointments skill and an appointment is confirmed on this turn, the response includes bookingCard — when (label, startsAt, endsAt, timezone), confirmationCode, scheduleName, and calendarUrl (a .ics file the visitor can add to their calendar). If you are not using scheduling, this field is omitted. You can ignore it.
Product cards: If the agent shows a product from its photo catalog, the response includes productCards — an array of { id, name, description, priceLabel, imageUrl, sku, category, buyUrl, ctaLabel, options, variants }. Omitted when no product was shown.
https://agent.askhandle.com/api/v1/public/conversations/{conversationId}/messagesRequires X-API-Key — Your public API key (starts with pk_live_)
Best practice
Timeouts. Longer answers can take up to 60 seconds. Allow at least 60 seconds on this call.
If the request times out:
- Do not send the same message again. That can run the turn twice.
- Poll Get Conversation History every 2 seconds, for up to a minute.
- Read
messages. The reply is stored when the turn finishes. - Send again only if your message never appears in that history.
Request
Headers
Content-TypeMust be application/json
X-API-KeyYour public API key
Query Parameters
conversationIdThe conversation ID returned from Start Conversation
Body
Message object containing the user's input
{
"message": "I need help with my order"
}Response
Success 200
{
"reply": "I'd be happy to help! What's your order number?",
"conversationId": "conv_abc123def456",
"ended": false
}Errors
API key is missing or invalid
{
"error": "Missing API key. Include X-API-Key header."
}Conversation doesn't exist or has expired (30 minutes inactivity)
{
"error": "Conversation not found or expired."
}Message field is missing or empty
{
"error": "Message is required."
}Code examples
const conversationId = 'conv_abc123def456';
const response = await fetch(
`https://agent.askhandle.com/api/v1/public/conversations/${conversationId}/messages`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'pk_live_your_api_key_here'
},
body: JSON.stringify({
message: 'I need help with my order'
}),
// Longer answers can take up to 60s. A shorter timeout drops the reply.
signal: AbortSignal.timeout(60_000)
}
);
const data = await response.json();
console.log('Bot reply:', data.reply);
console.log('Conversation ended:', data.ended);
if (data.bookingCard) {
console.log('Appointment:', data.bookingCard.label, data.bookingCard.confirmationCode);
console.log('Add to calendar:', data.bookingCard.calendarUrl);
}