HoopAI’s AI features are not limited to the platform interface. Through the REST API, you can programmatically create and manage AI agents, retrieve conversation data, control bot status, manage knowledge bases, access Voice AI transcripts, and pull analytics. This reference covers the key endpoints, authentication, webhooks, and code examples you need to integrate AI capabilities into your own applications and workflows.
For the full platform API documentation, see the API introduction .
Authentication All AI API requests require authentication using a Bearer token. You can generate API keys from Settings > Business Profile > API Keys in your HoopAI account.
Every request must include the locationId parameter (either in the URL path or as a query parameter) to identify which HoopAI account the request applies to.
curl -X GET "https://services.leadconnectorhq.com/conversations/" -H "Authorization: Bearer YOUR_API_KEY" -H "Version: 2021-07-28" -H "Content-Type: application/json"
Never expose your API key in client-side code or public repositories. Store it in environment variables or a secrets manager.
API base URL and versioning Property Value Base URL https://services.leadconnectorhq.com Version header Version: 2021-07-28 (required on all requests) Authentication Bearer token via Authorization header Content type application/json
All endpoints described below are relative to the base URL.
Agent management endpoints These endpoints let you create, read, update, and delete AI agents programmatically.
List all bots Retrieve all Conversation AI bots for a account.
GET /conversations/bots?locationId={locationId}
Get bot details Retrieve configuration details for a specific bot.
GET /conversations/bots/{botId}?locationId={locationId}
Create a bot Create a new Conversation AI bot with a system prompt and model configuration.
Request body: { "locationId" : "loc_abc123" , "name" : "Sales Assistant" , "systemPrompt" : "You are a sales assistant for our company..." , "model" : "gpt-4" , "temperature" : 0.7 , "maxTokens" : 500 , "status" : "draft" }
Update a bot Modify an existing bot’s configuration.
PUT /conversations/bots/{botId}
Delete a bot Remove a bot permanently. This action cannot be undone.
DELETE /conversations/bots/{botId}?locationId={locationId}
Deleting a bot removes its configuration and knowledge base associations. Conversation history is retained on the contact record but will no longer be linked to the bot.
Bot status control Toggle a bot’s active/inactive status without deleting it.
PATCH /conversations/bots/{botId}/status
Request body: { "locationId" : "loc_abc123" , "status" : "active" }
Valid status values: active , inactive , draft .
// Activate a bot const response = await client . patch ( "/conversations/bots/" + botId + "/status" , { locationId: "loc_abc123" , status: "active" } ); console . log ( "Bot status: " + response . data . status );
Conversation endpoints Retrieve and manage AI-powered conversations.
List conversations GET /conversations/?locationId={locationId}&botId={botId}&limit=20&offset=0
Query parameters: Parameter Type Description locationId string Required. The account ID botId string Optional. Filter by specific bot contactId string Optional. Filter by contact status string Optional. Filter by status: open, closed, escalated limit integer Optional. Results per page (default: 20, max: 100) offset integer Optional. Pagination offset
Get conversation messages Retrieve all messages in a specific conversation, including both contact and AI messages.
GET /conversations/{conversationId}/messages?locationId={locationId}
Send a message Inject a message into a conversation programmatically.
POST /conversations/{conversationId}/messages
Knowledge base endpoints Manage the documents and content your AI agents reference.
List knowledge base items GET /conversations/bots/{botId}/knowledge?locationId={locationId}
Add a knowledge base entry POST /conversations/bots/{botId}/knowledge
You can add text entries (with a title and content body) or URL entries (providing a URL for the AI to crawl and index).
Delete a knowledge base entry DELETE /conversations/bots/{botId}/knowledge/{entryId}?locationId={locationId}
// Add a knowledge base entry const response = await client . post ( "/conversations/bots/" + botId + "/knowledge" , { locationId: "loc_abc123" , type: "text" , title: "Pricing FAQ" , content: "Our plans start at ninety-nine dollars per month..." } ); console . log ( "Added knowledge entry: " + response . data . id );
Voice AI call data Retrieve call logs, transcripts, and analytics for Voice AI agents.
List voice calls GET /voice-ai/calls?locationId={locationId}&agentId={agentId}
Query parameters: Parameter Type Description locationId string Required. The account ID agentId string Optional. Filter by Voice AI agent direction string Optional. inbound or outbound startDate string Optional. ISO 8601 date for range filter endDate string Optional. ISO 8601 date for range filter
Get call transcript GET /voice-ai/calls/{callId}/transcript?locationId={locationId}
Returns the full transcript with timestamps, speaker labels, and sentiment scores for each segment.
Get call recording GET /voice-ai/calls/{callId}/recording?locationId={locationId}
Returns a signed URL to download the call recording (valid for 24 hours).
Webhook events HoopAI sends webhook events for key AI-related activities. Configure webhook endpoints in Settings > Webhooks or via the API.
Available AI events Event Description ConversationBotMessage Fired when an AI bot sends a message in a conversation ConversationEscalated Fired when a conversation is escalated to a human BotStatusChanged Fired when a bot’s status changes (active, inactive, draft) VoiceCallCompleted Fired when a Voice AI call ends VoiceCallEscalated Fired when a Voice AI call is transferred to a human KnowledgeBaseUpdated Fired when a knowledge base entry is added, updated, or removed
Use webhook events to trigger external workflows — for example, create a ticket in your help desk when a conversation is escalated, or log Voice AI call data to a business intelligence dashboard.
Rate limits HoopAI’s API enforces rate limits to ensure platform stability.
Tier Requests per minute Burst limit Standard 60 10 requests/second Agency 120 20 requests/second Enterprise Custom Contact support
When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how long to wait.
// Handle rate limiting with retry logic async function apiRequestWithRetry ( config , maxRetries = 3 ) { for ( let attempt = 0 ; attempt < maxRetries ; attempt ++ ) { try { return await client . request ( config ); } catch ( error ) { if ( error . response && error . response . status === 429 ) { const retryAfter = error . response . headers [ "retry-after" ] || 5 ; console . log ( "Rate limited. Retrying in " + retryAfter + "s..." ); await new Promise ( r => setTimeout ( r , retryAfter * 1000 )); } else { throw error ; } } } throw new Error ( "Max retries exceeded" ); }
Error handling The API uses standard HTTP status codes. Common error responses:
Status code Meaning Common cause 400 Bad Request Missing required field or invalid parameter 401 Unauthorized Invalid or expired API key 403 Forbidden API key lacks permission for this resource 404 Not Found Bot, conversation, or resource does not exist 422 Unprocessable Entity Valid syntax but semantically incorrect (e.g., invalid model name) 429 Too Many Requests Rate limit exceeded 500 Internal Server Error Platform issue — retry after a delay
For 500 errors, wait 30 seconds and retry. If the error persists, check the HoopAI status page or contact support.
Next steps
API introduction Full HoopAI platform API documentation and authentication guide.
AI actions in workflows Use AI within workflows without writing API code.
Bot settings Configure AI agents through the platform interface.
AI migration Migrate AI configurations between accounts and platforms.
