Agent API/Conversations
Start Conversation
Start a new conversation with your AI agent. Returns a conversation ID and the initial greeting message.
POST
https://agent.askhandle.com/api/v1/public/conversations/startRequires X-API-Key — Your public API key (starts with pk_live_)
Request
Headers
Content-Typestringrequired
Must be application/json
X-API-Keystringrequired
Your public API key
Body
Optional metadata object
JSON
{
"metadata": {
"userId": "user_123",
"customField": "optional_value"
}
}Response
Success 200
JSON
{
"conversationId": "conv_abc123def456",
"message": "👋 Welcome! How can I help you today?",
"workflowName": "Customer Support Bot"
}Errors
401
API key is missing or invalid
Error
{
"error": "Missing API key. Include X-API-Key header."
}404
Workflow doesn't exist or hasn't been published
Error
{
"error": "Workflow not found or not published."
}500
Workflow configuration error
Error
{
"error": "Workflow does not have a Start node configured."
}Code examples
const response = await fetch('https://agent.askhandle.com/api/v1/public/conversations/start', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'pk_live_your_api_key_here'
},
body: JSON.stringify({
metadata: {
userId: 'user_123'
}
})
});
const data = await response.json();
console.log('Conversation ID:', data.conversationId);
console.log('Message:', data.message);