API Integration

Getting Started

Welcome to the AI Voice Agent API documentation. Our API allows you to integrate AI-powered voice interactions into your applications.

Base URL

https://api.nevoxai.com/v1

Authentication

All API requests require authentication using an API key in the header.

Authentication Header

Authorization: Bearer YOUR_API_KEY

Voice Agents

Create and manage AI voice agents for your applications.

Create Voice Agent

POST /agents

{
    "name": "Customer Support Agent",
    "language": "en-US",
    "voice_type": "female",
    "personality": "professional",
    "custom_responses": {
        "greeting": "Hello, how can I help you today?",
        "farewell": "Thank you for your time. Have a great day!"
    }
}
                            

Parameters

Parameter	Type	Description
name required	string	Name of the voice agent
language	string	Language code (default: en-US)
voice_type	string	Voice type (male/female)

Response

Success Response

{
    "agent_id": "agt_123456",
    "name": "Customer Support Agent",
    "status": "active",
    "created_at": "2024-01-01T12:00:00Z"
}
                            

Conversations

Manage voice conversations between AI agents and users. Track interactions, get transcripts, and analyze conversation metrics.

Start Conversation

POST /conversations

{
    "agent_id": "agt_123456",
    "user_id": "usr_789012",
    "language": "en-US",
    "initial_context": {
        "customer_name": "John Doe",
        "previous_interaction": "Product Inquiry"
    },
    "settings": {
        "voice_speed": 1.0,
        "voice_pitch": "medium",
        "recording_enabled": true
    }
}
        

Parameters

Parameter	Type	Description
agent_id required	string	ID of the AI voice agent
user_id required	string	Unique identifier for the user
language	string	Conversation language (default: en-US)
initial_context	object	Additional context for the conversation

Response

Success Response

{
    "conversation_id": "conv_123456",
    "status": "active",
    "created_at": "2024-01-01T12:00:00Z",
    "connection_details": {
        "websocket_url": "wss://api.nevoxai.com/v1/ws/conv_123456",
        "token": "cvt_789012"
    }
}
        

Get Conversation History

GET /conversations/{conversation_id}

// Response
{
    "conversation_id": "conv_123456",
    "status": "completed",
    "duration": 180,
    "messages": [
        {
            "id": "msg_001",
            "type": "user",
            "content": "Hello, I need help with my order",
            "timestamp": "2024-01-01T12:00:00Z"
        },
        {
            "id": "msg_002",
            "type": "agent",
            "content": "I'd be happy to help you with your order. Could you please provide your order number?",
            "timestamp": "2024-01-01T12:00:05Z"
        }
    ],
    "metrics": {
        "sentiment_score": 0.8,
        "user_satisfaction": "high",
        "resolution_status": "resolved"
    }
}
        

End Conversation

POST /conversations/{conversation_id}/end

{
    "reason": "resolved",
    "feedback": {
        "rating": 5,
        "comments": "Issue resolved successfully"
    }
}
        

Webhooks

Set up webhooks to receive real-time notifications about conversation events and agent activities.

Create Webhook

POST /webhooks

{
    "url": "https://your-domain.com/webhook",
    "events": [
        "conversation.started",
        "conversation.ended",
        "message.received",
        "agent.handoff"
    ],
    "secret": "whsec_123456789",
    "description": "Production webhook for conversation events"
}
        

Parameters

Parameter	Type	Description
url required	string	HTTPS URL to receive webhook events
events required	array	Array of event types to subscribe to
secret	string	Secret key for webhook signature verification

Example Webhook Events

Conversation Started Event

{
    "event": "conversation.started",
    "created_at": "2024-01-01T12:00:00Z",
    "data": {
        "conversation_id": "conv_123456",
        "agent_id": "agt_123456",
        "user_id": "usr_789012",
        "initial_context": {
            "customer_name": "John Doe",
            "previous_interaction": "Product Inquiry"
        }
    }
}
        

Webhook Security

All webhook requests include a signature in the X-Signature header. Verify this signature to ensure the request came from our servers.

Signature Verification (Python)

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
        

List Available Events

Event Type	Description
conversation.started	New conversation initiated
conversation.ended	Conversation completed
message.received	New message in conversation
agent.handoff	Conversation transferred to human agent
error.occurred	Error during conversation

Error Handling

            Error Response
        

{
    "error": {
        "code": "webhook_error",
        "message": "Failed to deliver webhook",
        "type": "delivery_failure",
        "retry_count": 3,
        "next_retry": "2024-01-01T12:30:00Z"
    }
}
        

AI Voice Agent API Integration

Getting Started

Authentication

Voice Agents

Create Voice Agent

Parameters

Response

Conversations

Start Conversation

Parameters

Response

Get Conversation History

End Conversation

Webhooks

Create Webhook

Parameters

Example Webhook Events

Webhook Security

List Available Events

Error Handling

API Keys

Live API Key