RESTful API Documentation

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

{
  "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

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

{
  "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
  }
}

Get Conversation History

Webhooks

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

Create Webhook

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

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"
  }
}

Webhook Security

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

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"
  }
}