{ "openapi": "3.1.0", "info": { "title": "Telvana API", "version": "1.0.0", "description": "Welcome to the Telvana API - the comprehensive platform for building and managing AI-powered voice agents.\n\nTelvana enables developers to create sophisticated voice AI agents that can handle phone conversations with natural language understanding and generation. Our platform provides the infrastructure to build, deploy, and scale voice applications for customer service, sales, support, and more.\n\n**Key Features:** Outbound calling to any number, conversation management with detailed transcripts and analytics, real-time processing with low-latency responses, webhook integration for real-time updates, and comprehensive analytics and insights.\n\n**Getting Started:** Sign up for a Telvana account at telvana.com, generate an API key from your dashboard, configure your agent with custom prompts and behavior, then start making calls using the /outbound endpoint.\n\n**Authentication:** All API endpoints require authentication using an API key passed in the x-api-key header. Your API key can be found in your Telvana dashboard.\n\n**Rate Limits:** API requests are rate-limited to ensure fair usage and system stability. Contact support if you need higher limits for your use case.\n\nFor technical support, documentation, or questions about integration, visit our support portal or contact our team." }, "servers": [ { "url": "https://api.telvana.com", "description": "Production server" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/tags": { "get": { "summary": "List system tags", "description": "Retrieve all system-defined tags and their descriptions. These tags are automatically applied to conversations by the AI analyzer.", "operationId": "getTags", "tags": [ "Tags" ], "security": [], "responses": { "200": { "description": "System tags retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "string" } } } }, "example": { "data": { "transferred": "The Agent initiated a transfer to a human representative. Do not apply when the Agent was transferred by an IVR or routing system.", "voicemail": "The Agent successfully left a voicemail message. Do not apply if the call simply reached voicemail but no message was left.", "appointment_booked": "An appointment or callback was scheduled between the User and the Agent", "not_interested": "The User is not interested or asked not to be contacted", "action_needed": "A real conversation took place and the User raised a question, concern, or request that requires human follow-up. Do NOT apply when the call reached a voicemail system, busy signal, disconnected number, or any automated telecom message with no real human interaction." } } } } } } } }, "/outbound": { "post": { "summary": "Initiate an outbound call", "description": "Create an outbound call from an AI agent to a phone number", "operationId": "initiateOutbound", "tags": [ "Outbound" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\+?1?\\d{10,11}$", "description": "The agent's phone number in Telvana (e.g., +15559876543)" }, "to": { "type": "string", "pattern": "^\\+?1?\\d{10,11}$", "description": "The call recipient's phone number (e.g., +15551234567)" }, "outboundPromptId": { "type": "string", "description": "ID of the outbound prompt to use. Defaults to the first prompt for the agent." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Object containing the call's variables. These will be dynamically injected into the prompt. For example: 'Hi {{firstName}}.'" } }, "required": [ "from", "to" ], "additionalProperties": false }, "example": { "from": "+15559876543", "to": "+15551234567", "outboundPromptId": "clx8y9z1a2b3c4d5e6f7g8h9i", "variables": { "firstName": "John", "lastName": "Smith", "appointmentTime": "2:00 PM", "propertyAddress": "123 Main St, Anytown, CA" } } } } }, "responses": { "200": { "description": "Outbound call request queued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "conversationId": { "type": "string" }, "outboundPromptId": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "from", "to", "conversationId" ], "additionalProperties": false }, "message": { "type": "string" } }, "example": { "data": { "from": "+15559876543", "to": "+15551234567", "conversationId": "clx8y9z1a2b3c4d5e6f7g8h9i", "outboundPromptId": "clx8y9z1a2b3c4d5e6f7g8h9i", "variables": { "firstName": "John", "lastName": "Smith", "appointmentTime": "2:00 PM", "propertyAddress": "123 Main St, Anytown, CA" } }, "message": "Request queued for outbound processing" } } } } }, "400": { "description": "Bad request - Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Bad request - Invalid input", "statusCode": 400 } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Phone number not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Phone number not found", "statusCode": 404 } } } } } } } } }, "/conversation/{id}": { "get": { "summary": "Get conversation by ID", "description": "Retrieve details of a specific conversation including transcript and analytics", "operationId": "getConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier for the conversation", "schema": { "type": "string", "example": "clx8y9z1a2b3c4d5e6f7g8h9i" } } ], "responses": { "200": { "description": "Conversation retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of conversation" }, "dateInitiated": { "type": "string", "format": "date-time", "description": "Date initialized of conversation (ISO timestamp)" }, "agentId": { "type": "string", "description": "ID of Agent used in the conversation" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of call: OUTBOUND (Calling a Human) or INBOUND (Incoming Call from Human)" }, "tags": { "type": "array", "items": { "type": "string", "description": "Conversation tag label (e.g., appointment_booked, not_interested, or custom tag names)" }, "description": "Zero or more tags for the conversation (built-in and custom)" }, "summary": { "type": "string", "nullable": true, "description": "AI-generated summary of the conversation" }, "durationSeconds": { "type": "number", "description": "Precise call duration in seconds" }, "cost": { "type": "number", "description": "Cost of the call in cents" }, "humanPhoneNumber": { "type": "string", "description": "The customer/human's phone number" }, "agentPhoneNumber": { "type": "string", "description": "The phone number used by the AI agent" }, "sentimentClassification": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "N_A" ], "nullable": true, "description": "Sentiment classification of the conversation. N_A indicates no sentiment is available (e.g., the call failed to connect)." }, "transcript": { "type": "string", "description": "Full text transcript of the conversation" }, "recordingUrl": { "type": "string", "description": "Pre-signed S3 URL for downloading the audio recording (expires in 1 hour)" } }, "required": [ "id", "dateInitiated", "agentId", "direction", "tags", "summary", "durationSeconds", "cost", "humanPhoneNumber", "agentPhoneNumber", "sentimentClassification" ], "additionalProperties": false } }, "example": { "data": { "id": "clx8y9z1a2b3c4d5e6f7g8h9i", "dateInitiated": "2025-12-01T14:30:00.000Z", "agentId": "agent_abc123", "direction": "OUTBOUND", "tags": [ "appointment_booked" ], "summary": "Successfully confirmed customer appointment for tomorrow at 2:00 PM. Customer was polite and confirmed availability.", "durationSeconds": 210, "cost": 125, "humanPhoneNumber": "+15551234567", "agentPhoneNumber": "+15559876543", "sentimentClassification": "POSITIVE", "transcript": "Agent: Hello, this is Sarah from Telvana calling to confirm your appointment tomorrow at 2:00 PM. Is this still convenient for you?\n\nCustomer: Yes, that works perfectly. Thank you for calling to confirm.\n\nAgent: Great! We look forward to seeing you tomorrow. Have a wonderful day!\n\nCustomer: Thank you, you too!", "recordingUrl": "https://s3.amazonaws.com/recordings/clx8y9z1a2b3c4d5e6f7g8h9i.wav" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Conversation not found", "statusCode": 404 } } } } } } } } }, "/conversations": { "get": { "summary": "Get conversations list", "description": "Retrieve a list of conversations with optional filtering. Results are ordered by date initiated (most recent first).", "operationId": "getConversations", "tags": [ "Conversations" ], "parameters": [ { "name": "datetime_start", "in": "query", "required": false, "description": "Start timestamp for filtering conversations (Unix timestamp in milliseconds, e.g., 1764547200000)", "schema": { "type": "integer", "format": "int64", "example": 1764547200000 } }, { "name": "datetime_end", "in": "query", "required": false, "description": "End timestamp for filtering conversations (Unix timestamp in milliseconds, e.g., 1764720000000)", "schema": { "type": "integer", "format": "int64", "example": 1764720000000 } }, { "name": "agent_id", "in": "query", "required": false, "description": "Filter by agent ID" }, { "name": "direction", "in": "query", "required": false, "description": "Filter by call direction", "schema": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "example": "OUTBOUND" } }, { "name": "sentiment", "in": "query", "required": false, "description": "Filter by sentiment classification", "schema": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE" ], "example": "POSITIVE" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 100 } }, { "name": "skip", "in": "query", "required": false, "description": "Number of records to skip for pagination (default: 0)", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Conversations retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of conversation" }, "dateInitiated": { "type": "string", "format": "date-time", "description": "Date initialized of conversation (ISO timestamp)" }, "agentId": { "type": "string", "description": "ID of Agent used in the conversation" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of call: OUTBOUND (Calling a Human) or INBOUND (Incoming Call from Human)" }, "tags": { "type": "array", "items": { "type": "string", "description": "Conversation tag label (e.g., appointment_booked, not_interested, or custom tag names)" }, "description": "Zero or more tags for the conversation (built-in and custom)" }, "summary": { "type": "string", "nullable": true, "description": "AI-generated summary of the conversation" }, "durationSeconds": { "type": "number", "description": "Precise call duration in seconds" }, "cost": { "type": "number", "description": "Cost of the call in cents" }, "humanPhoneNumber": { "type": "string", "description": "The customer/human's phone number" }, "agentPhoneNumber": { "type": "string", "description": "The phone number used by the AI agent" }, "sentimentClassification": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "N_A" ], "nullable": true, "description": "Sentiment classification of the conversation. N_A indicates no sentiment is available (e.g., the call failed to connect)." }, "transcript": { "type": "string", "description": "Full text transcript of the conversation" }, "recordingUrl": { "type": "string", "description": "Pre-signed S3 URL for downloading the audio recording (expires in 1 hour)" } }, "required": [ "id", "dateInitiated", "agentId", "direction", "tags", "summary", "durationSeconds", "cost", "humanPhoneNumber", "agentPhoneNumber", "sentimentClassification" ], "additionalProperties": false } }, "example": { "data": [ { "id": "clx8y9z1a2b3c4d5e6f7g8h9i", "dateInitiated": "2025-12-01T14:30:00.000Z", "agentId": "agent_abc123", "direction": "OUTBOUND", "tags": [ "appointment_booked" ], "summary": "Successfully confirmed customer appointment for tomorrow at 2:00 PM. Customer was polite and confirmed availability.", "durationSeconds": 210, "cost": 125, "humanPhoneNumber": "+15551234567", "agentPhoneNumber": "+15559876543", "sentimentClassification": "POSITIVE", "transcript": "Agent: Hello, this is Sarah from Telvana calling to confirm your appointment tomorrow at 2:00 PM. Is this still convenient for you?\n\nCustomer: Yes, that works perfectly. Thank you for calling to confirm." } ] } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } } } } }, "/agents/{agentId}": { "get": { "summary": "Get agent details", "description": "Retrieve details of a specific agent including configuration settings", "operationId": "getAgent", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Unique identifier for the agent", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } } ], "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the agent" }, "name": { "type": "string", "description": "Agent name" }, "description": { "type": "string", "nullable": true, "description": "Agent description" }, "isActive": { "type": "boolean", "description": "Whether the agent is active" }, "inboundPrompt": { "type": "string", "nullable": true, "description": "Prompt for inbound calls" }, "hasCallTransfer": { "type": "boolean", "description": "Whether call transfer is enabled" }, "hasEndCall": { "type": "boolean", "description": "Whether end call tool is enabled" }, "transferCallerId": { "type": "string", "description": "Caller ID mode for transfers: \"human\" or \"agent\"" }, "hasAutoInboundTransfer": { "type": "boolean", "description": "Whether auto inbound transfer is enabled" }, "inboundTransferNumber": { "type": "string", "nullable": true, "description": "Phone number for auto inbound transfer" }, "isMultilingual": { "type": "boolean", "description": "Whether multilingual support is enabled" }, "hasBargeIn": { "type": "boolean", "description": "Whether barge-in (interruption) is enabled" }, "hasPostConversationWebhook": { "type": "boolean", "description": "Whether post-conversation webhook is enabled" }, "postConversationWebhookUrl": { "type": "string", "nullable": true, "description": "URL for post-conversation webhook" }, "hasHints": { "type": "boolean", "description": "Whether speech recognition hints are enabled" }, "hints": { "type": "string", "nullable": true, "description": "Speech recognition hints (comma-separated)" }, "hasLanguage": { "type": "boolean", "description": "Whether custom language is enabled" }, "language": { "type": "string", "nullable": true, "description": "Language code (e.g., en-US)" }, "voiceId": { "type": "string", "nullable": true, "description": "Voice ID for TTS" }, "integrationIds": { "type": "array", "items": { "type": "string" }, "description": "Array of integration IDs" }, "disabledToolNames": { "type": "array", "items": { "type": "string" }, "description": "Array of disabled workspace tool names" }, "phoneNumberId": { "type": "string", "nullable": true, "description": "Associated phone number ID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "description", "isActive", "inboundPrompt", "hasCallTransfer", "hasEndCall", "transferCallerId", "hasAutoInboundTransfer", "inboundTransferNumber", "isMultilingual", "hasBargeIn", "hasPostConversationWebhook", "postConversationWebhookUrl", "hasHints", "hints", "hasLanguage", "language", "voiceId", "integrationIds", "disabledToolNames", "phoneNumberId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "example": { "data": { "id": "jm1u1cawc7dka1x84mrjvb4y", "name": "Customer Service Agent", "description": "Handles customer inquiries", "isActive": true, "inboundPrompt": "You are a helpful customer service agent...", "hasCallTransfer": true, "hasEndCall": true, "hasAutoInboundTransfer": false, "inboundTransferNumber": null, "isMultilingual": false, "hasBargeIn": true, "hasPostConversationWebhook": false, "postConversationWebhookUrl": null, "hasHints": false, "hints": null, "hasLanguage": true, "language": "en-US", "voiceId": "pNInz6obpgDQGcFmaJgB", "integrationIds": [], "phoneNumberId": "ph_abc123", "createdAt": "2025-01-01T00:00:00.000Z", "updatedAt": "2025-01-15T00:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Agent not found", "statusCode": 404 } } } } } } } } }, "/agents/{agentId}/inbound-prompt": { "put": { "summary": "Update inbound prompt", "description": "Update the inbound prompt for an agent", "operationId": "updateInboundPrompt", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Unique identifier for the agent", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inboundPrompt": { "type": "string", "description": "The new inbound prompt for the agent" } }, "required": [ "inboundPrompt" ], "additionalProperties": false }, "example": { "inboundPrompt": "You are a helpful customer service agent for Acme Corp. Be polite and helpful." } } } }, "responses": { "200": { "description": "Inbound prompt updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the agent" }, "name": { "type": "string", "description": "Agent name" }, "description": { "type": "string", "nullable": true, "description": "Agent description" }, "isActive": { "type": "boolean", "description": "Whether the agent is active" }, "inboundPrompt": { "type": "string", "nullable": true, "description": "Prompt for inbound calls" }, "hasCallTransfer": { "type": "boolean", "description": "Whether call transfer is enabled" }, "hasEndCall": { "type": "boolean", "description": "Whether end call tool is enabled" }, "transferCallerId": { "type": "string", "description": "Caller ID mode for transfers: \"human\" or \"agent\"" }, "hasAutoInboundTransfer": { "type": "boolean", "description": "Whether auto inbound transfer is enabled" }, "inboundTransferNumber": { "type": "string", "nullable": true, "description": "Phone number for auto inbound transfer" }, "isMultilingual": { "type": "boolean", "description": "Whether multilingual support is enabled" }, "hasBargeIn": { "type": "boolean", "description": "Whether barge-in (interruption) is enabled" }, "hasPostConversationWebhook": { "type": "boolean", "description": "Whether post-conversation webhook is enabled" }, "postConversationWebhookUrl": { "type": "string", "nullable": true, "description": "URL for post-conversation webhook" }, "hasHints": { "type": "boolean", "description": "Whether speech recognition hints are enabled" }, "hints": { "type": "string", "nullable": true, "description": "Speech recognition hints (comma-separated)" }, "hasLanguage": { "type": "boolean", "description": "Whether custom language is enabled" }, "language": { "type": "string", "nullable": true, "description": "Language code (e.g., en-US)" }, "voiceId": { "type": "string", "nullable": true, "description": "Voice ID for TTS" }, "integrationIds": { "type": "array", "items": { "type": "string" }, "description": "Array of integration IDs" }, "disabledToolNames": { "type": "array", "items": { "type": "string" }, "description": "Array of disabled workspace tool names" }, "phoneNumberId": { "type": "string", "nullable": true, "description": "Associated phone number ID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "description", "isActive", "inboundPrompt", "hasCallTransfer", "hasEndCall", "transferCallerId", "hasAutoInboundTransfer", "inboundTransferNumber", "isMultilingual", "hasBargeIn", "hasPostConversationWebhook", "postConversationWebhookUrl", "hasHints", "hints", "hasLanguage", "language", "voiceId", "integrationIds", "disabledToolNames", "phoneNumberId", "createdAt", "updatedAt" ], "additionalProperties": false }, "message": { "type": "string" } }, "example": { "data": { "id": "jm1u1cawc7dka1x84mrjvb4y", "name": "Customer Service Agent", "inboundPrompt": "You are a helpful customer service agent for Acme Corp. Be polite and helpful." }, "message": "Inbound prompt updated successfully" } } } } }, "400": { "description": "Bad request - Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": "Invalid request data", "details": [ { "path": "inboundPrompt", "message": "Required" } ] } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Agent not found", "statusCode": 404 } } } } } } } } }, "/agents/{agentId}/settings": { "put": { "summary": "Update agent settings", "description": "Update agent configuration settings including call transfer, multilingual support, webhooks, and more", "operationId": "updateAgentSettings", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Unique identifier for the agent", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hasCallTransfer": { "type": "boolean", "description": "Enable/disable call transfer" }, "hasEndCall": { "type": "boolean", "description": "Enable/disable end call tool" }, "transferCallerId": { "type": "string", "enum": [ "human", "agent" ], "description": "Caller ID shown on transfer: \"human\" (caller number) or \"agent\" (business number)" }, "hasAutoInboundTransfer": { "type": "boolean", "description": "Enable/disable auto inbound transfer" }, "inboundTransferNumber": { "type": "string", "nullable": true, "description": "Phone number for auto inbound transfer" }, "isMultilingual": { "type": "boolean", "description": "Enable/disable multilingual support" }, "hasBargeIn": { "type": "boolean", "description": "Enable/disable barge-in (interruption)" }, "hasPostConversationWebhook": { "type": "boolean", "description": "Enable/disable post-conversation webhook" }, "postConversationWebhookUrl": { "type": "string", "nullable": true, "description": "URL for post-conversation webhook" }, "hasHints": { "type": "boolean", "description": "Enable/disable speech recognition hints" }, "hints": { "type": "string", "nullable": true, "description": "Speech recognition hints (comma-separated)" }, "hasLanguage": { "type": "boolean", "description": "Enable/disable custom language" }, "language": { "type": "string", "nullable": true, "description": "Language code (e.g., en-US)" }, "voiceId": { "type": "string", "nullable": true, "description": "Voice ID for TTS" }, "integrationIds": { "type": "array", "items": { "type": "string" }, "description": "Array of integration IDs" }, "disabledToolNames": { "type": "array", "items": { "type": "string" }, "description": "Array of disabled workspace tool names" } }, "additionalProperties": false }, "example": { "hasCallTransfer": true, "hasEndCall": true, "hasBargeIn": true, "language": "en-US", "voiceId": "pNInz6obpgDQGcFmaJgB" } } } }, "responses": { "200": { "description": "Agent settings updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the agent" }, "name": { "type": "string", "description": "Agent name" }, "description": { "type": "string", "nullable": true, "description": "Agent description" }, "isActive": { "type": "boolean", "description": "Whether the agent is active" }, "inboundPrompt": { "type": "string", "nullable": true, "description": "Prompt for inbound calls" }, "hasCallTransfer": { "type": "boolean", "description": "Whether call transfer is enabled" }, "hasEndCall": { "type": "boolean", "description": "Whether end call tool is enabled" }, "transferCallerId": { "type": "string", "description": "Caller ID mode for transfers: \"human\" or \"agent\"" }, "hasAutoInboundTransfer": { "type": "boolean", "description": "Whether auto inbound transfer is enabled" }, "inboundTransferNumber": { "type": "string", "nullable": true, "description": "Phone number for auto inbound transfer" }, "isMultilingual": { "type": "boolean", "description": "Whether multilingual support is enabled" }, "hasBargeIn": { "type": "boolean", "description": "Whether barge-in (interruption) is enabled" }, "hasPostConversationWebhook": { "type": "boolean", "description": "Whether post-conversation webhook is enabled" }, "postConversationWebhookUrl": { "type": "string", "nullable": true, "description": "URL for post-conversation webhook" }, "hasHints": { "type": "boolean", "description": "Whether speech recognition hints are enabled" }, "hints": { "type": "string", "nullable": true, "description": "Speech recognition hints (comma-separated)" }, "hasLanguage": { "type": "boolean", "description": "Whether custom language is enabled" }, "language": { "type": "string", "nullable": true, "description": "Language code (e.g., en-US)" }, "voiceId": { "type": "string", "nullable": true, "description": "Voice ID for TTS" }, "integrationIds": { "type": "array", "items": { "type": "string" }, "description": "Array of integration IDs" }, "disabledToolNames": { "type": "array", "items": { "type": "string" }, "description": "Array of disabled workspace tool names" }, "phoneNumberId": { "type": "string", "nullable": true, "description": "Associated phone number ID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "description", "isActive", "inboundPrompt", "hasCallTransfer", "hasEndCall", "transferCallerId", "hasAutoInboundTransfer", "inboundTransferNumber", "isMultilingual", "hasBargeIn", "hasPostConversationWebhook", "postConversationWebhookUrl", "hasHints", "hints", "hasLanguage", "language", "voiceId", "integrationIds", "disabledToolNames", "phoneNumberId", "createdAt", "updatedAt" ], "additionalProperties": false }, "message": { "type": "string" } }, "example": { "data": { "id": "jm1u1cawc7dka1x84mrjvb4y", "hasCallTransfer": true, "hasEndCall": true, "hasBargeIn": true, "language": "en-US" }, "message": "Agent settings updated successfully" } } } } }, "400": { "description": "Bad request - Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": "Invalid request data", "details": [ { "path": "hasCallTransfer", "message": "Expected boolean" } ] } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Agent not found", "statusCode": 404 } } } } } } } } }, "/agents/{agentId}/outbound-prompts": { "get": { "summary": "List outbound prompts", "description": "Retrieve all outbound prompts for an agent", "operationId": "listOutboundPrompts", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Unique identifier for the agent", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } } ], "responses": { "200": { "description": "Outbound prompts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the outbound prompt" }, "title": { "type": "string", "description": "Title of the outbound prompt" }, "instructions": { "type": "string", "description": "Instructions/prompt for outbound calls" }, "agentId": { "type": "string", "description": "ID of the agent this prompt belongs to" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "title", "instructions", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "example": { "data": [ { "id": "prompt_abc123", "title": "Appointment Confirmation", "instructions": "Call to confirm the appointment for {{firstName}} at {{appointmentTime}}.", "agentId": "jm1u1cawc7dka1x84mrjvb4y", "createdAt": "2025-01-01T00:00:00.000Z", "updatedAt": "2025-01-01T00:00:00.000Z" }, { "id": "prompt_def456", "title": "Follow-up Call", "instructions": "Follow up with {{firstName}} regarding their recent inquiry.", "agentId": "jm1u1cawc7dka1x84mrjvb4y", "createdAt": "2025-01-02T00:00:00.000Z", "updatedAt": "2025-01-02T00:00:00.000Z" } ] } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Agent not found", "statusCode": 404 } } } } } } } }, "post": { "summary": "Create outbound prompt", "description": "Create a new outbound prompt for an agent", "operationId": "createOutboundPrompt", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Unique identifier for the agent", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Title of the outbound prompt" }, "instructions": { "type": "string", "minLength": 1, "description": "Instructions/prompt for outbound calls" } }, "required": [ "title", "instructions" ], "additionalProperties": false }, "example": { "title": "Appointment Reminder", "instructions": "Call {{firstName}} to remind them of their appointment at {{appointmentTime}}. Be friendly and confirm they can still make it." } } } }, "responses": { "201": { "description": "Outbound prompt created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the outbound prompt" }, "title": { "type": "string", "description": "Title of the outbound prompt" }, "instructions": { "type": "string", "description": "Instructions/prompt for outbound calls" }, "agentId": { "type": "string", "description": "ID of the agent this prompt belongs to" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "title", "instructions", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false }, "message": { "type": "string" } }, "example": { "data": { "id": "prompt_xyz789", "title": "Appointment Reminder", "instructions": "Call {{firstName}} to remind them of their appointment at {{appointmentTime}}. Be friendly and confirm they can still make it.", "agentId": "jm1u1cawc7dka1x84mrjvb4y", "createdAt": "2025-01-15T00:00:00.000Z", "updatedAt": "2025-01-15T00:00:00.000Z" }, "message": "Outbound prompt created successfully" } } } } }, "400": { "description": "Bad request - Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": "Invalid request data", "details": [ { "path": "title", "message": "Required" } ] } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Agent not found", "statusCode": 404 } } } } } } } } }, "/agents/{agentId}/outbound-prompts/{promptId}": { "get": { "summary": "Get outbound prompt", "description": "Retrieve a specific outbound prompt by ID", "operationId": "getOutboundPrompt", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Unique identifier for the agent", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } }, { "name": "promptId", "in": "path", "required": true, "description": "Unique identifier for the outbound prompt", "schema": { "type": "string", "example": "prompt_abc123" } } ], "responses": { "200": { "description": "Outbound prompt retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the outbound prompt" }, "title": { "type": "string", "description": "Title of the outbound prompt" }, "instructions": { "type": "string", "description": "Instructions/prompt for outbound calls" }, "agentId": { "type": "string", "description": "ID of the agent this prompt belongs to" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "title", "instructions", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "example": { "data": { "id": "prompt_abc123", "title": "Appointment Confirmation", "instructions": "Call to confirm the appointment for {{firstName}} at {{appointmentTime}}.", "agentId": "jm1u1cawc7dka1x84mrjvb4y", "createdAt": "2025-01-01T00:00:00.000Z", "updatedAt": "2025-01-01T00:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent or outbound prompt not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Outbound prompt not found", "statusCode": 404 } } } } } } } }, "put": { "summary": "Update outbound prompt", "description": "Update an existing outbound prompt", "operationId": "updateOutboundPrompt", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Unique identifier for the agent", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } }, { "name": "promptId", "in": "path", "required": true, "description": "Unique identifier for the outbound prompt", "schema": { "type": "string", "example": "prompt_abc123" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Updated title" }, "instructions": { "type": "string", "minLength": 1, "description": "Updated instructions" } }, "additionalProperties": false }, "example": { "title": "Updated Appointment Confirmation", "instructions": "Call {{firstName}} to confirm their appointment at {{appointmentTime}}. Be professional and courteous." } } } }, "responses": { "200": { "description": "Outbound prompt updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the outbound prompt" }, "title": { "type": "string", "description": "Title of the outbound prompt" }, "instructions": { "type": "string", "description": "Instructions/prompt for outbound calls" }, "agentId": { "type": "string", "description": "ID of the agent this prompt belongs to" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "title", "instructions", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false }, "message": { "type": "string" } }, "example": { "data": { "id": "prompt_abc123", "title": "Updated Appointment Confirmation", "instructions": "Call {{firstName}} to confirm their appointment at {{appointmentTime}}. Be professional and courteous.", "agentId": "jm1u1cawc7dka1x84mrjvb4y", "createdAt": "2025-01-01T00:00:00.000Z", "updatedAt": "2025-01-15T00:00:00.000Z" }, "message": "Outbound prompt updated successfully" } } } } }, "400": { "description": "Bad request - Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": "Invalid request data", "details": [ { "path": "title", "message": "String must contain at least 1 character(s)" } ] } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent or outbound prompt not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Outbound prompt not found", "statusCode": 404 } } } } } } } }, "delete": { "summary": "Delete outbound prompt", "description": "Delete an outbound prompt", "operationId": "deleteOutboundPrompt", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Unique identifier for the agent", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } }, { "name": "promptId", "in": "path", "required": true, "description": "Unique identifier for the outbound prompt", "schema": { "type": "string", "example": "prompt_abc123" } } ], "responses": { "200": { "description": "Outbound prompt deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "message": { "type": "string" } }, "example": { "data": null, "message": "Outbound prompt deleted successfully" } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent or outbound prompt not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Outbound prompt not found", "statusCode": 404 } } } } } } } } }, "/knowledge-bases": { "get": { "summary": "List knowledge bases", "description": "Retrieve a paginated list of knowledge bases in your workspace. Supports sorting and pagination.", "operationId": "listKnowledgeBases", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number (default: 1)", "schema": { "type": "integer", "default": 1, "example": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of items per page (default: 25)", "schema": { "type": "integer", "default": 25, "example": 25 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field to sort by (default: createdAt)", "schema": { "type": "string", "default": "createdAt", "example": "createdAt" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort order", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "example": "desc" } } ], "responses": { "200": { "description": "Knowledge bases retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "knowledgeBases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "_count": { "type": "object", "properties": { "documents": { "type": "integer" }, "agents": { "type": "integer" } } } } } }, "pageCount": { "type": "integer" }, "pageIndex": { "type": "integer" }, "pageSize": { "type": "integer" }, "sortBy": { "type": "string" }, "sortOrder": { "type": "string" } } } } }, "example": { "data": { "knowledgeBases": [ { "id": "kb_abc123", "workspaceId": "ws_xyz789", "name": "Product Documentation", "description": "Documentation for all products", "createdAt": "2025-06-01T00:00:00.000Z", "updatedAt": "2025-06-15T00:00:00.000Z", "_count": { "documents": 12, "agents": 3 } } ], "pageCount": 1, "pageIndex": 1, "pageSize": 25, "sortBy": "createdAt", "sortOrder": "desc" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } } } }, "post": { "summary": "Create knowledge base", "description": "Create a new knowledge base. This also creates a corresponding vector collection for document embeddings.", "operationId": "createKnowledgeBase", "tags": [ "Knowledge Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 } }, "required": [ "name", "description" ], "additionalProperties": false }, "example": { "name": "Product Documentation", "description": "Documentation for all products and services" } } } }, "responses": { "201": { "description": "Knowledge base created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } }, "example": { "data": { "id": "kb_abc123", "workspaceId": "ws_xyz789", "name": "Product Documentation", "description": "Documentation for all products and services", "createdAt": "2025-06-01T00:00:00.000Z", "updatedAt": "2025-06-01T00:00:00.000Z" }, "message": "Knowledge base created successfully" } } } }, "400": { "description": "Bad request - Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": "Invalid request data", "details": [ { "path": "name", "message": "Required" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } } } } }, "/knowledge-bases/workspace": { "get": { "summary": "List knowledge bases for dropdown", "description": "Retrieve a lightweight list of knowledge bases in your workspace, suitable for dropdown/selection UI components. Returns only id, name, and description.", "operationId": "listWorkspaceKnowledgeBases", "tags": [ "Knowledge Bases" ], "responses": { "200": { "description": "Knowledge bases retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "example": { "data": [ { "id": "kb_abc123", "name": "Product Documentation", "description": "Documentation for all products" }, { "id": "kb_def456", "name": "FAQ", "description": "Frequently asked questions" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } } } } }, "/knowledge-bases/{id}": { "get": { "summary": "Get knowledge base", "description": "Retrieve details of a specific knowledge base", "operationId": "getKnowledgeBase", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge base ID", "schema": { "type": "string", "example": "kb_abc123" } } ], "responses": { "200": { "description": "Knowledge base retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "example": { "data": { "id": "kb_abc123", "workspaceId": "ws_xyz789", "name": "Product Documentation", "description": "Documentation for all products", "createdAt": "2025-06-01T00:00:00.000Z", "updatedAt": "2025-06-15T00:00:00.000Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Knowledge base not found", "statusCode": 404 } } } } } } } }, "put": { "summary": "Update knowledge base", "description": "Update the name or description of a knowledge base", "operationId": "updateKnowledgeBase", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge base ID", "schema": { "type": "string", "example": "kb_abc123" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "example": { "name": "Updated Product Docs", "description": "Updated description for the product documentation" } } } }, "responses": { "200": { "description": "Knowledge base updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } }, "message": { "type": "string" } } }, "example": { "data": { "id": "kb_abc123", "name": "Updated Product Docs", "description": "Updated description for the product documentation" }, "message": "Knowledge base updated successfully" } } } }, "400": { "description": "Bad request - Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": "Invalid request data", "details": [ { "path": "description", "message": "Knowledge base description cannot be empty" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Knowledge base not found", "statusCode": 404 } } } } } } } }, "delete": { "summary": "Delete knowledge base", "description": "Delete a knowledge base and all associated data including documents, text chunks, vector embeddings (Qdrant), and files (S3).", "operationId": "deleteKnowledgeBase", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge base ID", "schema": { "type": "string", "example": "kb_abc123" } } ], "responses": { "200": { "description": "Knowledge base deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "message": { "type": "string" } } }, "example": { "data": null, "message": "Knowledge base deleted successfully" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Knowledge base not found", "statusCode": 404 } } } } } } } } }, "/knowledge-bases/{id}/documents": { "get": { "summary": "List documents", "description": "Retrieve all documents in a knowledge base with chunk count information", "operationId": "listKnowledgeBaseDocuments", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge base ID", "schema": { "type": "string", "example": "kb_abc123" } } ], "responses": { "200": { "description": "Documents retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "knowledgeBaseId": { "type": "string" }, "filename": { "type": "string" }, "originalName": { "type": "string" }, "fileType": { "type": "string", "enum": [ "PDF", "DOCX", "TXT", "MD", "CSV", "JSON" ] }, "fileSize": { "type": "integer", "description": "File size in bytes" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "chunkCount": { "type": "integer", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "processedAt": { "type": "string", "format": "date-time", "nullable": true }, "_count": { "type": "object", "properties": { "chunks": { "type": "integer" } } } } } } } }, "example": { "data": [ { "id": "doc_abc123", "knowledgeBaseId": "kb_abc123", "filename": "a1b2c3d4-product-guide.pdf", "originalName": "product-guide.pdf", "fileType": "PDF", "fileSize": 2048576, "status": "COMPLETED", "chunkCount": 47, "errorMessage": null, "createdAt": "2025-06-01T00:00:00.000Z", "processedAt": "2025-06-01T00:01:30.000Z", "_count": { "chunks": 47 } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Knowledge base not found", "statusCode": 404 } } } } } } } }, "post": { "summary": "Upload document", "description": "Upload a document to a knowledge base. The document is processed through a pipeline:\n\n1. **Upload** — File is stored in S3\n2. **Parse** — Text is extracted from the file (PDF, DOCX, TXT, MD, CSV, JSON supported)\n3. **Chunk** — Text is split into ~2200 character chunks with sentence-boundary overlap\n4. **Embed** — Each chunk is converted to a 3072-dimension vector using Google Gemini embeddings\n5. **Index** — Vectors are upserted into the Qdrant collection for semantic search\n\nThe endpoint returns the document record immediately after processing completes. If parsing or embedding fails, the document is marked as FAILED with an error message.\n\n**Supported file types:** PDF, DOCX, TXT, MD, CSV, JSON\n\n**Maximum file size:** 50 MB", "operationId": "uploadKnowledgeBaseDocument", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Knowledge base ID", "schema": { "type": "string", "example": "kb_abc123" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The document file to upload. Supported types: PDF, DOCX, TXT, MD, CSV, JSON. Max size: 50MB." } } } } } }, "responses": { "201": { "description": "Document uploaded and processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "knowledgeBaseId": { "type": "string" }, "filename": { "type": "string" }, "originalName": { "type": "string" }, "fileType": { "type": "string" }, "fileSize": { "type": "integer" }, "status": { "type": "string" }, "chunkCount": { "type": "integer" }, "processedAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } }, "example": { "data": { "id": "doc_abc123", "knowledgeBaseId": "kb_abc123", "filename": "a1b2c3d4-product-guide.pdf", "originalName": "product-guide.pdf", "fileType": "PDF", "fileSize": 2048576, "status": "COMPLETED", "chunkCount": 47, "processedAt": "2025-06-01T00:01:30.000Z" }, "message": "Document uploaded successfully" } } } }, "400": { "description": "Bad request - Invalid file type or size", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unsupported file type. Allowed: PDF, DOCX, TXT, MD, CSV, JSON", "statusCode": 400 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Knowledge base not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Knowledge base not found", "statusCode": 404 } } } } } } } } }, "/knowledge-bases/documents/{documentId}": { "delete": { "summary": "Delete document", "description": "Delete a document from a knowledge base. This removes the document from the database, S3 storage, and deletes its vector embeddings from Qdrant.", "operationId": "deleteKnowledgeBaseDocument", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "Document ID", "schema": { "type": "string", "example": "doc_abc123" } } ], "responses": { "200": { "description": "Document deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "message": { "type": "string" } } }, "example": { "data": null, "message": "Document deleted successfully" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "403": { "description": "Forbidden - Document belongs to another workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Forbidden", "statusCode": 403 } } } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Document not found", "statusCode": 404 } } } } } } } } }, "/agents/{agentId}/knowledge-bases": { "get": { "summary": "Get agent knowledge bases", "description": "Retrieve the knowledge bases associated with an agent", "operationId": "getAgentKnowledgeBases", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent ID", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } } ], "responses": { "200": { "description": "Agent knowledge bases retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "example": { "data": [ { "id": "kb_abc123", "workspaceId": "ws_xyz789", "name": "Product Documentation", "description": "Documentation for all products", "createdAt": "2025-06-01T00:00:00.000Z", "updatedAt": "2025-06-15T00:00:00.000Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Agent not found", "statusCode": 404 } } } } } } } }, "put": { "summary": "Update agent knowledge bases", "description": "Replace the set of knowledge bases associated with an agent. Pass an array of knowledge base IDs — all previous associations are removed and replaced with the new set. Pass an empty array to remove all associations.", "operationId": "updateAgentKnowledgeBases", "tags": [ "Knowledge Bases" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "description": "Agent ID", "schema": { "type": "string", "example": "jm1u1cawc7dka1x84mrjvb4y" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "knowledgeBaseIds" ], "additionalProperties": false }, "example": { "knowledgeBaseIds": [ "kb_abc123", "kb_def456" ] } } } }, "responses": { "200": { "description": "Agent knowledge bases updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "message": { "type": "string" } } }, "example": { "data": null, "message": "Agent knowledge bases updated successfully" } } } }, "400": { "description": "Bad request - Invalid knowledge base IDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Invalid knowledge base IDs", "statusCode": 400 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false, "example": { "error": { "message": "Agent not found", "statusCode": 404 } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for authentication. Obtain from your Telvana dashboard under the API Keys page. Include in all requests as: x-api-key: tlv_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" } }, "schemas": { "OutboundRequest": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\+?1?\\d{10,11}$", "description": "The agent's phone number in Telvana (e.g., +15559876543)" }, "to": { "type": "string", "pattern": "^\\+?1?\\d{10,11}$", "description": "The call recipient's phone number (e.g., +15551234567)" }, "outboundPromptId": { "type": "string", "description": "ID of the outbound prompt to use. Defaults to the first prompt for the agent." }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Object containing the call's variables. These will be dynamically injected into the prompt. For example: 'Hi {{firstName}}.'" } }, "required": [ "from", "to" ], "additionalProperties": false }, "OutboundResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "conversationId": { "type": "string" }, "outboundPromptId": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "from", "to", "conversationId" ], "additionalProperties": false }, "message": { "type": "string" } }, "required": [ "data", "message" ], "additionalProperties": false }, "ConversationResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of conversation" }, "dateInitiated": { "type": "string", "format": "date-time", "description": "Date initialized of conversation (ISO timestamp)" }, "agentId": { "type": "string", "description": "ID of Agent used in the conversation" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of call: OUTBOUND (Calling a Human) or INBOUND (Incoming Call from Human)" }, "tags": { "type": "array", "items": { "type": "string", "description": "Conversation tag label (e.g., appointment_booked, not_interested, or custom tag names)" }, "description": "Zero or more tags for the conversation (built-in and custom)" }, "summary": { "type": "string", "nullable": true, "description": "AI-generated summary of the conversation" }, "durationSeconds": { "type": "number", "description": "Precise call duration in seconds" }, "cost": { "type": "number", "description": "Cost of the call in cents" }, "humanPhoneNumber": { "type": "string", "description": "The customer/human's phone number" }, "agentPhoneNumber": { "type": "string", "description": "The phone number used by the AI agent" }, "sentimentClassification": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "N_A" ], "nullable": true, "description": "Sentiment classification of the conversation. N_A indicates no sentiment is available (e.g., the call failed to connect)." }, "transcript": { "type": "string", "description": "Full text transcript of the conversation" }, "recordingUrl": { "type": "string", "description": "Pre-signed S3 URL for downloading the audio recording (expires in 1 hour)" } }, "required": [ "id", "dateInitiated", "agentId", "direction", "tags", "summary", "durationSeconds", "cost", "humanPhoneNumber", "agentPhoneNumber", "sentimentClassification" ], "additionalProperties": false }, "PostConversationWebhook": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "Unique identifier for the conversation" }, "dateInitiated": { "type": "string", "format": "date-time", "description": "When the conversation started (ISO timestamp)" }, "agentId": { "type": "string", "description": "ID of the AI agent that handled the call" }, "workspaceId": { "type": "string", "description": "ID of the workspace/organization" }, "transcript": { "type": "string", "description": "Full text transcript of the conversation (empty string for failed calls)" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of call: OUTBOUND (Calling a Human) or INBOUND (Incoming Call from Human)" }, "cost": { "type": "number", "description": "Cost in cents (0 for failed calls)" }, "agentPhoneNumber": { "type": "string", "description": "The phone number used by the AI agent" }, "humanPhoneNumber": { "type": "string", "description": "The customer's phone number" }, "duration": { "type": "number", "description": "Call duration in seconds (0 for failed calls)" }, "summary": { "type": "string", "description": "AI-generated summary of the conversation (empty string for failed calls)" }, "sentiment": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "N_A" ], "description": "Sentiment classification of the conversation. N_A indicates no sentiment is available (e.g., the call failed to connect and no human was reached)." }, "disposition": { "type": "string", "description": "Call outcome (e.g., COMPLETED, FAILED, VOICEMAIL). For failed calls this is \"FAILED\"." }, "tags": { "type": "array", "items": { "type": "string", "description": "Conversation tag label (e.g., appointment_booked, not_interested, or custom tag names)" }, "description": "Zero or more tags that apply to this conversation (built-in and custom)" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs passed during call initiation" } }, "required": [ "conversationId", "dateInitiated", "agentId", "workspaceId", "transcript", "direction", "cost", "agentPhoneNumber", "humanPhoneNumber", "duration", "summary", "sentiment", "disposition", "tags", "variables" ], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "statusCode": { "type": "number", "description": "HTTP status code" } }, "required": [ "error", "statusCode" ], "additionalProperties": false }, "AgentResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the agent" }, "name": { "type": "string", "description": "Agent name" }, "description": { "type": "string", "nullable": true, "description": "Agent description" }, "isActive": { "type": "boolean", "description": "Whether the agent is active" }, "inboundPrompt": { "type": "string", "nullable": true, "description": "Prompt for inbound calls" }, "hasCallTransfer": { "type": "boolean", "description": "Whether call transfer is enabled" }, "hasEndCall": { "type": "boolean", "description": "Whether end call tool is enabled" }, "transferCallerId": { "type": "string", "description": "Caller ID mode for transfers: \"human\" or \"agent\"" }, "hasAutoInboundTransfer": { "type": "boolean", "description": "Whether auto inbound transfer is enabled" }, "inboundTransferNumber": { "type": "string", "nullable": true, "description": "Phone number for auto inbound transfer" }, "isMultilingual": { "type": "boolean", "description": "Whether multilingual support is enabled" }, "hasBargeIn": { "type": "boolean", "description": "Whether barge-in (interruption) is enabled" }, "hasPostConversationWebhook": { "type": "boolean", "description": "Whether post-conversation webhook is enabled" }, "postConversationWebhookUrl": { "type": "string", "nullable": true, "description": "URL for post-conversation webhook" }, "hasHints": { "type": "boolean", "description": "Whether speech recognition hints are enabled" }, "hints": { "type": "string", "nullable": true, "description": "Speech recognition hints (comma-separated)" }, "hasLanguage": { "type": "boolean", "description": "Whether custom language is enabled" }, "language": { "type": "string", "nullable": true, "description": "Language code (e.g., en-US)" }, "voiceId": { "type": "string", "nullable": true, "description": "Voice ID for TTS" }, "integrationIds": { "type": "array", "items": { "type": "string" }, "description": "Array of integration IDs" }, "disabledToolNames": { "type": "array", "items": { "type": "string" }, "description": "Array of disabled workspace tool names" }, "phoneNumberId": { "type": "string", "nullable": true, "description": "Associated phone number ID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "description", "isActive", "inboundPrompt", "hasCallTransfer", "hasEndCall", "transferCallerId", "hasAutoInboundTransfer", "inboundTransferNumber", "isMultilingual", "hasBargeIn", "hasPostConversationWebhook", "postConversationWebhookUrl", "hasHints", "hints", "hasLanguage", "language", "voiceId", "integrationIds", "disabledToolNames", "phoneNumberId", "createdAt", "updatedAt" ], "additionalProperties": false }, "UpdateInboundPromptRequest": { "type": "object", "properties": { "inboundPrompt": { "type": "string", "description": "The new inbound prompt for the agent" } }, "required": [ "inboundPrompt" ], "additionalProperties": false }, "UpdateAgentSettingsRequest": { "type": "object", "properties": { "hasCallTransfer": { "type": "boolean", "description": "Enable/disable call transfer" }, "hasEndCall": { "type": "boolean", "description": "Enable/disable end call tool" }, "transferCallerId": { "type": "string", "enum": [ "human", "agent" ], "description": "Caller ID shown on transfer: \"human\" (caller number) or \"agent\" (business number)" }, "hasAutoInboundTransfer": { "type": "boolean", "description": "Enable/disable auto inbound transfer" }, "inboundTransferNumber": { "type": "string", "nullable": true, "description": "Phone number for auto inbound transfer" }, "isMultilingual": { "type": "boolean", "description": "Enable/disable multilingual support" }, "hasBargeIn": { "type": "boolean", "description": "Enable/disable barge-in (interruption)" }, "hasPostConversationWebhook": { "type": "boolean", "description": "Enable/disable post-conversation webhook" }, "postConversationWebhookUrl": { "type": "string", "nullable": true, "description": "URL for post-conversation webhook" }, "hasHints": { "type": "boolean", "description": "Enable/disable speech recognition hints" }, "hints": { "type": "string", "nullable": true, "description": "Speech recognition hints (comma-separated)" }, "hasLanguage": { "type": "boolean", "description": "Enable/disable custom language" }, "language": { "type": "string", "nullable": true, "description": "Language code (e.g., en-US)" }, "voiceId": { "type": "string", "nullable": true, "description": "Voice ID for TTS" }, "integrationIds": { "type": "array", "items": { "type": "string" }, "description": "Array of integration IDs" }, "disabledToolNames": { "type": "array", "items": { "type": "string" }, "description": "Array of disabled workspace tool names" } }, "additionalProperties": false }, "OutboundPrompt": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the outbound prompt" }, "title": { "type": "string", "description": "Title of the outbound prompt" }, "instructions": { "type": "string", "description": "Instructions/prompt for outbound calls" }, "agentId": { "type": "string", "description": "ID of the agent this prompt belongs to" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "title", "instructions", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false }, "CreateOutboundPromptRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Title of the outbound prompt" }, "instructions": { "type": "string", "minLength": 1, "description": "Instructions/prompt for outbound calls" } }, "required": [ "title", "instructions" ], "additionalProperties": false }, "UpdateOutboundPromptRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Updated title" }, "instructions": { "type": "string", "minLength": 1, "description": "Updated instructions" } }, "additionalProperties": false }, "CreateKnowledgeBaseRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 } }, "required": [ "name", "description" ], "additionalProperties": false }, "UpdateKnowledgeBaseRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "UpdateAgentKnowledgeBasesRequest": { "type": "object", "properties": { "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "knowledgeBaseIds" ], "additionalProperties": false } } }, "tags": [ { "name": "Outbound", "description": "Endpoints for initiating outbound calls" }, { "name": "Conversations", "description": "Endpoints for managing and retrieving conversation data" }, { "name": "Agents", "description": "Endpoints for managing agent configuration, settings, and outbound prompts" }, { "name": "Knowledge Bases", "description": "Endpoints for managing knowledge bases, documents, and agent-knowledge base associations. Supports document upload with automatic parsing, chunking, and vector embedding for semantic search." }, { "name": "Tags", "description": "Endpoints for retrieving system-defined conversation tags" }, { "name": "Webhooks", "description": "Webhook payloads sent by Telvana to customer endpoints (not API endpoints to call)" } ], "webhooks": { "postConversation": { "post": { "summary": "Post-conversation webhook", "description": "This webhook is triggered automatically after each conversation completes if you have the setting turned on in agent configurations. Configure your webhook URL and secret in the Telvana dashboard under Settings > Webhooks.\n\n**Webhook URL Priority:**\n\nWebhook URLs can be configured at both the agent level and the workspace level. When a conversation completes, Telvana will send the webhook to the agent's webhook URL if one is configured. If no agent webhook URL is set, the workspace webhook URL will be used instead. This allows you to have a default webhook endpoint for your workspace while still being able to override it for specific agents.\n\n**Complete Implementation Example:**\n\nFor a full working example with signature verification, error handling, and best practices, see our example repository: https://github.com/telvana-ai/post-conversation-webhook-example\n\n**Security:**\n\nAll webhook requests from Telvana include an `X-Webhook-Signature` header containing an HMAC SHA-256 signature of the request body. You should verify this signature to ensure the request came from Telvana.\n\n**Signature Verification Steps:**\n\n1. Extract the `X-Webhook-Signature` header from the request\n2. Compute HMAC SHA-256 of the raw request body using your webhook secret\n3. Compare the computed signature with the header value\n4. Reject requests with invalid or missing signatures\n\n**Example Verification (Node.js):**\n\n```javascript\nconst crypto = require('crypto');\n\n// Get the signature from headers\nconst receivedSignature = req.headers['x-webhook-signature'];\n\n// Compute expected signature using raw body\nconst expectedSignature = crypto\n.createHmac('sha256', YOUR_WEBHOOK_SECRET)\n.update(rawRequestBody)\n.digest('hex');\n\n// Verify signatures match\nif (receivedSignature !== expectedSignature) {\nreturn res.status(401).json({ error: 'Invalid signature' });\n}\n```\n\n**Example Verification (Python):**\n\n```python\nimport hmac\nimport hashlib\n\n# Get the signature from headers\nreceived_signature = request.headers.get('X-Webhook-Signature')\n\n# Compute expected signature using raw body\nexpected_signature = hmac.new(\n YOUR_WEBHOOK_SECRET.encode('utf-8'),\n request.body,\n hashlib.sha256\n).hexdigest()\n\n# Verify signatures match\nif received_signature != expected_signature:\n return {'error': 'Invalid signature'}, 401\n```\n\n**Important Notes:**\n\n- Always use the raw request body for signature verification (before JSON parsing)\n- Store your webhook secret securely (environment variables, secrets manager)\n", "operationId": "postConversationWebhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "Unique identifier for the conversation" }, "dateInitiated": { "type": "string", "format": "date-time", "description": "When the conversation started (ISO timestamp)" }, "agentId": { "type": "string", "description": "ID of the AI agent that handled the call" }, "workspaceId": { "type": "string", "description": "ID of the workspace/organization" }, "transcript": { "type": "string", "description": "Full text transcript of the conversation (empty string for failed calls)" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of call: OUTBOUND (Calling a Human) or INBOUND (Incoming Call from Human)" }, "cost": { "type": "number", "description": "Cost in cents (0 for failed calls)" }, "agentPhoneNumber": { "type": "string", "description": "The phone number used by the AI agent" }, "humanPhoneNumber": { "type": "string", "description": "The customer's phone number" }, "duration": { "type": "number", "description": "Call duration in seconds (0 for failed calls)" }, "summary": { "type": "string", "description": "AI-generated summary of the conversation (empty string for failed calls)" }, "sentiment": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "N_A" ], "description": "Sentiment classification of the conversation. N_A indicates no sentiment is available (e.g., the call failed to connect and no human was reached)." }, "disposition": { "type": "string", "description": "Call outcome (e.g., COMPLETED, FAILED, VOICEMAIL). For failed calls this is \"FAILED\"." }, "tags": { "type": "array", "items": { "type": "string", "description": "Conversation tag label (e.g., appointment_booked, not_interested, or custom tag names)" }, "description": "Zero or more tags that apply to this conversation (built-in and custom)" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs passed during call initiation" } }, "required": [ "conversationId", "dateInitiated", "agentId", "workspaceId", "transcript", "direction", "cost", "agentPhoneNumber", "humanPhoneNumber", "duration", "summary", "sentiment", "disposition", "tags", "variables" ], "additionalProperties": false }, "example": { "conversationId": "clx8y9z1a2b3c4d5e6f7g8h9i", "dateInitiated": "2025-12-01T14:30:00.000Z", "agentId": "agent_abc123", "workspaceId": "workspace_xyz789", "transcript": "Agent: Hello, this is Sarah from Telvana calling to confirm your appointment tomorrow at 2:00 PM. Is this still convenient for you?\n\nCustomer: Yes, that works perfectly. Thank you for calling to confirm.\n\nAgent: Great! We look forward to seeing you tomorrow. Have a wonderful day!\n\nCustomer: Thank you, you too!", "direction": "OUTBOUND", "cost": 125, "agentPhoneNumber": "+15559876543", "humanPhoneNumber": "+15551234567", "duration": 210, "recordingUrl": "https://s3.amazonaws.com/recordings/clx8y9z1a2b3c4d5e6f7g8h9i.wav", "summary": "Successfully confirmed customer appointment for tomorrow at 2:00 PM. Customer was polite and confirmed availability.", "sentiment": "POSITIVE", "disposition": "COMPLETED", "tags": [ "appointment_booked" ], "variables": { "firstName": "John", "lastName": "Smith", "appointmentTime": "2:00 PM" } } } } }, "responses": { "200": { "description": "Webhook received successfully. Your endpoint should return 200 OK to acknowledge receipt." }, "401": { "description": "Invalid webhook signature" } }, "x-custom-headers": { "X-Webhook-Signature": { "description": "HMAC SHA-256 signature of the request body using your webhook secret. Format: hex-encoded string (64 characters)", "example": "7d8e9f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e", "required": true } } } } } }