API_DOCS.md

vBot API Documentation

Overview

The vBot API provides endpoints for call processing and customer management. All API requests require authentication using an API key.

Authentication

All API requests must include your API key in the X-API-Key header:

curl -X POST https://vbot-server.com/api/process-call \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/call.wav"

Endpoints

Call Processing

Process Call

POST /api/process-call

Process a call recording and receive analysis results via webhook.

Headers:

• X-API-Key: Your API key
• Content-Type: multipart/form-data

Parameters:

• file: Call recording file (WAV format)
• caller_number: Caller's phone number
• called_number: Called phone number

Response:

{
  "status": "success",
  "message": "Call processing started",
  "call_id": "uuid"
}

Webhook Payload:

{
  "call_id": "uuid",
  "caller_number": "+1234567890",
  "called_number": "+0987654321",
  "transcription": "Call transcript...",
  "summary": "Call summary...",
  "sentiment": "positive",
  "keywords": "keyword1, keyword2",
  "timestamp": "2024-03-14T12:00:00Z",
  "customer_id": 123
}

Customer Management

List Customers (Admin Only)

GET /api/customers

List all customers.

Headers:

• Authorization: Bearer token (admin only)

Response:

{
  "customers": [
    {
      "id": 1,
      "name": "Customer Name",
      "company_name": "Company Name",
      "email": "customer@example.com",
      "api_key": "api_key_here",
      "is_active": true,
      "created_at": "2024-03-14T12:00:00Z",
      "updated_at": "2024-03-14T12:00:00Z"
    }
  ]
}

Create Customer (Admin Only)

POST /api/customers

Create a new customer.

Headers:

• Authorization: Bearer token (admin only)
• Content-Type: application/json

Request Body:

{
  "name": "Customer Name",
  "company_name": "Company Name",
  "email": "customer@example.com"
}

Response:

{
  "id": 1,
  "name": "Customer Name",
  "company_name": "Company Name",
  "email": "customer@example.com",
  "api_key": "generated_api_key",
  "is_active": true,
  "created_at": "2024-03-14T12:00:00Z",
  "updated_at": "2024-03-14T12:00:00Z"
}

Update Customer (Admin Only)

PUT /api/customers/{customer_id}

Update customer details.

Headers:

• Authorization: Bearer token (admin only)
• Content-Type: application/json

Request Body:

{
  "name": "Updated Name",
  "company_name": "Updated Company",
  "email": "updated@example.com",
  "is_active": true
}

Response:

{
  "id": 1,
  "name": "Updated Name",
  "company_name": "Updated Company",
  "email": "updated@example.com",
  "api_key": "existing_api_key",
  "is_active": true,
  "created_at": "2024-03-14T12:00:00Z",
  "updated_at": "2024-03-14T12:00:00Z"
}

Delete Customer (Admin Only)

DELETE /api/customers/{customer_id}

Delete a customer.

Headers:

• Authorization: Bearer token (admin only)

Response:

{
  "status": "success",
  "message": "Customer deleted successfully"
}

Health Check

Check API Health

GET /health

Check API health status.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-03-14T12:00:00Z"
}

Error Responses

All endpoints may return the following error responses:

401 Unauthorized

{
  "status": "error",
  "message": "Invalid API key"
}

403 Forbidden

{
  "status": "error",
  "message": "Insufficient permissions"
}

404 Not Found

{
  "status": "error",
  "message": "Resource not found"
}

400 Bad Request

{
  "status": "error",
  "message": "Invalid request parameters"
}

500 Internal Server Error

{
  "status": "error",
  "message": "Internal server error"
}

Rate Limits

• API requests are limited to 100 requests per minute per API key
• Webhook delivery attempts are limited to 3 retries
• Call processing is limited to 10 concurrent calls per customer

Best Practices

1. Always use HTTPS for API requests
2. Store API keys securely
3. Implement webhook retry logic
4. Monitor API usage and rate limits
5. Keep API keys confidential
6. Use appropriate error handling
7. Implement request timeouts
8. Monitor webhook delivery status