Spaces:
Sleeping
Sleeping
Ajit Panday
commited on
Commit
·
36a486d
1
Parent(s):
3a6a328
Update documentation to reflect distributed architecture and API-based approach
Browse files- API_DOCS.md +256 -0
- README.md +172 -144
- SETUP_GUIDE.md +244 -350
- USER_MANUAL.md +210 -173
- app/models.py +8 -3
API_DOCS.md
ADDED
|
@@ -0,0 +1,256 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# vBot API Documentation
|
| 2 |
+
|
| 3 |
+
## Overview
|
| 4 |
+
|
| 5 |
+
The vBot API provides endpoints for call processing and customer management. All API requests require authentication using an API key.
|
| 6 |
+
|
| 7 |
+
## Authentication
|
| 8 |
+
|
| 9 |
+
All API requests must include your API key in the `X-API-Key` header:
|
| 10 |
+
|
| 11 |
+
```bash
|
| 12 |
+
curl -X POST https://vbot-server.com/api/process-call \
|
| 13 |
+
-H "X-API-Key: your_api_key" \
|
| 14 |
+
-H "Content-Type: multipart/form-data" \
|
| 15 |
+
-F "file=@/path/to/call.wav"
|
| 16 |
+
```
|
| 17 |
+
|
| 18 |
+
## Endpoints
|
| 19 |
+
|
| 20 |
+
### Call Processing
|
| 21 |
+
|
| 22 |
+
#### Process Call
|
| 23 |
+
```http
|
| 24 |
+
POST /api/process-call
|
| 25 |
+
```
|
| 26 |
+
|
| 27 |
+
Process a call recording and receive analysis results via webhook.
|
| 28 |
+
|
| 29 |
+
**Headers:**
|
| 30 |
+
- `X-API-Key`: Your API key
|
| 31 |
+
- `Content-Type`: multipart/form-data
|
| 32 |
+
|
| 33 |
+
**Parameters:**
|
| 34 |
+
- `file`: Call recording file (WAV format)
|
| 35 |
+
- `caller_number`: Caller's phone number
|
| 36 |
+
- `called_number`: Called phone number
|
| 37 |
+
|
| 38 |
+
**Response:**
|
| 39 |
+
```json
|
| 40 |
+
{
|
| 41 |
+
"status": "success",
|
| 42 |
+
"message": "Call processing started",
|
| 43 |
+
"call_id": "uuid"
|
| 44 |
+
}
|
| 45 |
+
```
|
| 46 |
+
|
| 47 |
+
**Webhook Payload:**
|
| 48 |
+
```json
|
| 49 |
+
{
|
| 50 |
+
"call_id": "uuid",
|
| 51 |
+
"caller_number": "+1234567890",
|
| 52 |
+
"called_number": "+0987654321",
|
| 53 |
+
"transcription": "Call transcript...",
|
| 54 |
+
"summary": "Call summary...",
|
| 55 |
+
"sentiment": "positive",
|
| 56 |
+
"keywords": "keyword1, keyword2",
|
| 57 |
+
"timestamp": "2024-03-14T12:00:00Z",
|
| 58 |
+
"customer_id": 123
|
| 59 |
+
}
|
| 60 |
+
```
|
| 61 |
+
|
| 62 |
+
### Customer Management
|
| 63 |
+
|
| 64 |
+
#### List Customers (Admin Only)
|
| 65 |
+
```http
|
| 66 |
+
GET /api/customers
|
| 67 |
+
```
|
| 68 |
+
|
| 69 |
+
List all customers.
|
| 70 |
+
|
| 71 |
+
**Headers:**
|
| 72 |
+
- `Authorization`: Bearer token (admin only)
|
| 73 |
+
|
| 74 |
+
**Response:**
|
| 75 |
+
```json
|
| 76 |
+
{
|
| 77 |
+
"customers": [
|
| 78 |
+
{
|
| 79 |
+
"id": 1,
|
| 80 |
+
"name": "Customer Name",
|
| 81 |
+
"company_name": "Company Name",
|
| 82 |
+
"email": "customer@example.com",
|
| 83 |
+
"api_key": "api_key_here",
|
| 84 |
+
"is_active": true,
|
| 85 |
+
"created_at": "2024-03-14T12:00:00Z",
|
| 86 |
+
"updated_at": "2024-03-14T12:00:00Z"
|
| 87 |
+
}
|
| 88 |
+
]
|
| 89 |
+
}
|
| 90 |
+
```
|
| 91 |
+
|
| 92 |
+
#### Create Customer (Admin Only)
|
| 93 |
+
```http
|
| 94 |
+
POST /api/customers
|
| 95 |
+
```
|
| 96 |
+
|
| 97 |
+
Create a new customer.
|
| 98 |
+
|
| 99 |
+
**Headers:**
|
| 100 |
+
- `Authorization`: Bearer token (admin only)
|
| 101 |
+
- `Content-Type`: application/json
|
| 102 |
+
|
| 103 |
+
**Request Body:**
|
| 104 |
+
```json
|
| 105 |
+
{
|
| 106 |
+
"name": "Customer Name",
|
| 107 |
+
"company_name": "Company Name",
|
| 108 |
+
"email": "customer@example.com"
|
| 109 |
+
}
|
| 110 |
+
```
|
| 111 |
+
|
| 112 |
+
**Response:**
|
| 113 |
+
```json
|
| 114 |
+
{
|
| 115 |
+
"id": 1,
|
| 116 |
+
"name": "Customer Name",
|
| 117 |
+
"company_name": "Company Name",
|
| 118 |
+
"email": "customer@example.com",
|
| 119 |
+
"api_key": "generated_api_key",
|
| 120 |
+
"is_active": true,
|
| 121 |
+
"created_at": "2024-03-14T12:00:00Z",
|
| 122 |
+
"updated_at": "2024-03-14T12:00:00Z"
|
| 123 |
+
}
|
| 124 |
+
```
|
| 125 |
+
|
| 126 |
+
#### Update Customer (Admin Only)
|
| 127 |
+
```http
|
| 128 |
+
PUT /api/customers/{customer_id}
|
| 129 |
+
```
|
| 130 |
+
|
| 131 |
+
Update customer details.
|
| 132 |
+
|
| 133 |
+
**Headers:**
|
| 134 |
+
- `Authorization`: Bearer token (admin only)
|
| 135 |
+
- `Content-Type`: application/json
|
| 136 |
+
|
| 137 |
+
**Request Body:**
|
| 138 |
+
```json
|
| 139 |
+
{
|
| 140 |
+
"name": "Updated Name",
|
| 141 |
+
"company_name": "Updated Company",
|
| 142 |
+
"email": "updated@example.com",
|
| 143 |
+
"is_active": true
|
| 144 |
+
}
|
| 145 |
+
```
|
| 146 |
+
|
| 147 |
+
**Response:**
|
| 148 |
+
```json
|
| 149 |
+
{
|
| 150 |
+
"id": 1,
|
| 151 |
+
"name": "Updated Name",
|
| 152 |
+
"company_name": "Updated Company",
|
| 153 |
+
"email": "updated@example.com",
|
| 154 |
+
"api_key": "existing_api_key",
|
| 155 |
+
"is_active": true,
|
| 156 |
+
"created_at": "2024-03-14T12:00:00Z",
|
| 157 |
+
"updated_at": "2024-03-14T12:00:00Z"
|
| 158 |
+
}
|
| 159 |
+
```
|
| 160 |
+
|
| 161 |
+
#### Delete Customer (Admin Only)
|
| 162 |
+
```http
|
| 163 |
+
DELETE /api/customers/{customer_id}
|
| 164 |
+
```
|
| 165 |
+
|
| 166 |
+
Delete a customer.
|
| 167 |
+
|
| 168 |
+
**Headers:**
|
| 169 |
+
- `Authorization`: Bearer token (admin only)
|
| 170 |
+
|
| 171 |
+
**Response:**
|
| 172 |
+
```json
|
| 173 |
+
{
|
| 174 |
+
"status": "success",
|
| 175 |
+
"message": "Customer deleted successfully"
|
| 176 |
+
}
|
| 177 |
+
```
|
| 178 |
+
|
| 179 |
+
### Health Check
|
| 180 |
+
|
| 181 |
+
#### Check API Health
|
| 182 |
+
```http
|
| 183 |
+
GET /health
|
| 184 |
+
```
|
| 185 |
+
|
| 186 |
+
Check API health status.
|
| 187 |
+
|
| 188 |
+
**Response:**
|
| 189 |
+
```json
|
| 190 |
+
{
|
| 191 |
+
"status": "healthy",
|
| 192 |
+
"version": "1.0.0",
|
| 193 |
+
"timestamp": "2024-03-14T12:00:00Z"
|
| 194 |
+
}
|
| 195 |
+
```
|
| 196 |
+
|
| 197 |
+
## Error Responses
|
| 198 |
+
|
| 199 |
+
All endpoints may return the following error responses:
|
| 200 |
+
|
| 201 |
+
### 401 Unauthorized
|
| 202 |
+
```json
|
| 203 |
+
{
|
| 204 |
+
"status": "error",
|
| 205 |
+
"message": "Invalid API key"
|
| 206 |
+
}
|
| 207 |
+
```
|
| 208 |
+
|
| 209 |
+
### 403 Forbidden
|
| 210 |
+
```json
|
| 211 |
+
{
|
| 212 |
+
"status": "error",
|
| 213 |
+
"message": "Insufficient permissions"
|
| 214 |
+
}
|
| 215 |
+
```
|
| 216 |
+
|
| 217 |
+
### 404 Not Found
|
| 218 |
+
```json
|
| 219 |
+
{
|
| 220 |
+
"status": "error",
|
| 221 |
+
"message": "Resource not found"
|
| 222 |
+
}
|
| 223 |
+
```
|
| 224 |
+
|
| 225 |
+
### 400 Bad Request
|
| 226 |
+
```json
|
| 227 |
+
{
|
| 228 |
+
"status": "error",
|
| 229 |
+
"message": "Invalid request parameters"
|
| 230 |
+
}
|
| 231 |
+
```
|
| 232 |
+
|
| 233 |
+
### 500 Internal Server Error
|
| 234 |
+
```json
|
| 235 |
+
{
|
| 236 |
+
"status": "error",
|
| 237 |
+
"message": "Internal server error"
|
| 238 |
+
}
|
| 239 |
+
```
|
| 240 |
+
|
| 241 |
+
## Rate Limits
|
| 242 |
+
|
| 243 |
+
- API requests are limited to 100 requests per minute per API key
|
| 244 |
+
- Webhook delivery attempts are limited to 3 retries
|
| 245 |
+
- Call processing is limited to 10 concurrent calls per customer
|
| 246 |
+
|
| 247 |
+
## Best Practices
|
| 248 |
+
|
| 249 |
+
1. Always use HTTPS for API requests
|
| 250 |
+
2. Store API keys securely
|
| 251 |
+
3. Implement webhook retry logic
|
| 252 |
+
4. Monitor API usage and rate limits
|
| 253 |
+
5. Keep API keys confidential
|
| 254 |
+
6. Use appropriate error handling
|
| 255 |
+
7. Implement request timeouts
|
| 256 |
+
8. Monitor webhook delivery status
|
README.md
CHANGED
|
@@ -11,27 +11,54 @@ pinned: false
|
|
| 11 |
|
| 12 |
# vBot - Intelligent Call Analysis System
|
| 13 |
|
| 14 |
-
vBot is
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 15 |
|
| 16 |
## Features
|
| 17 |
|
| 18 |
-
-
|
| 19 |
-
-
|
|
|
|
|
|
|
| 20 |
- Sentiment analysis and keyword extraction
|
| 21 |
- Modern admin interface for customer management
|
| 22 |
-
-
|
| 23 |
-
- Webhook support for customer integration
|
| 24 |
-
- Detailed call analytics and reporting
|
| 25 |
|
| 26 |
## System Requirements
|
| 27 |
|
|
|
|
| 28 |
- Python 3.8 or higher
|
| 29 |
-
- MySQL 5.7 or higher
|
| 30 |
-
- Asterisk PBX system
|
| 31 |
- Hugging Face Space (for deployment)
|
| 32 |
-
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 33 |
|
| 34 |
-
## Quick Start
|
| 35 |
|
| 36 |
1. Clone the repository:
|
| 37 |
```bash
|
|
@@ -61,13 +88,13 @@ vBot is an intelligent call analysis system that processes, transcribes, and ana
|
|
| 61 |
python main.py
|
| 62 |
```
|
| 63 |
|
| 64 |
-
## Admin Setup
|
| 65 |
|
| 66 |
1. Access the admin interface:
|
| 67 |
- URL: `https://your-domain.com/admin`
|
| 68 |
- Default credentials: admin/admin (change immediately)
|
| 69 |
|
| 70 |
-
2. Create
|
| 71 |
- Click "Add Customer"
|
| 72 |
- Fill in customer details:
|
| 73 |
- Name
|
|
@@ -76,112 +103,113 @@ vBot is an intelligent call analysis system that processes, transcribes, and ana
|
|
| 76 |
- System will generate a unique API key
|
| 77 |
|
| 78 |
3. Configure customer webhook:
|
| 79 |
-
-
|
| 80 |
- Optional: Set webhook secret for additional security
|
| 81 |
|
| 82 |
-
##
|
| 83 |
-
|
| 84 |
-
1.
|
| 85 |
-
|
| 86 |
-
|
| 87 |
-
|
| 88 |
-
|
| 89 |
-
|
| 90 |
-
|
| 91 |
-
|
| 92 |
-
|
| 93 |
-
|
| 94 |
-
|
| 95 |
-
|
| 96 |
-
|
| 97 |
-
|
| 98 |
-
|
| 99 |
-
|
| 100 |
-
|
| 101 |
-
|
| 102 |
-
|
| 103 |
-
|
| 104 |
-
|
| 105 |
-
|
| 106 |
-
|
| 107 |
-
|
| 108 |
-
|
| 109 |
-
|
| 110 |
-
|
| 111 |
-
|
| 112 |
-
|
| 113 |
-
|
| 114 |
-
|
| 115 |
-
|
| 116 |
-
|
| 117 |
-
|
| 118 |
-
|
| 119 |
-
|
| 120 |
-
|
| 121 |
-
|
| 122 |
-
|
| 123 |
-
|
| 124 |
-
|
| 125 |
-
|
| 126 |
-
|
| 127 |
-
|
| 128 |
-
|
| 129 |
-
|
| 130 |
-
|
| 131 |
-
|
| 132 |
-
|
| 133 |
-
|
| 134 |
-
|
| 135 |
-
|
| 136 |
-
|
| 137 |
-
|
| 138 |
-
|
| 139 |
-
|
| 140 |
-
|
| 141 |
-
|
| 142 |
-
|
| 143 |
-
|
| 144 |
-
|
| 145 |
-
|
| 146 |
-
|
| 147 |
-
|
| 148 |
-
|
| 149 |
-
|
| 150 |
-
|
| 151 |
-
|
| 152 |
-
|
| 153 |
-
|
| 154 |
-
|
| 155 |
-
|
| 156 |
-
|
| 157 |
-
|
| 158 |
-
|
| 159 |
-
|
| 160 |
-
|
| 161 |
-
|
| 162 |
-
|
| 163 |
-
|
| 164 |
-
|
| 165 |
-
|
| 166 |
-
|
| 167 |
-
|
| 168 |
-
|
| 169 |
-
|
| 170 |
-
|
| 171 |
-
|
| 172 |
-
|
| 173 |
-
|
| 174 |
-
|
| 175 |
-
|
| 176 |
-
|
| 177 |
-
|
| 178 |
-
|
| 179 |
-
|
| 180 |
-
|
| 181 |
-
|
| 182 |
-
|
| 183 |
-
|
| 184 |
-
|
|
|
|
| 185 |
|
| 186 |
## Security
|
| 187 |
|
|
@@ -191,44 +219,45 @@ vBot is an intelligent call analysis system that processes, transcribes, and ana
|
|
| 191 |
- Keys can be regenerated if compromised
|
| 192 |
|
| 193 |
2. Webhook Security:
|
| 194 |
-
- Optional webhook secret for signature validation
|
| 195 |
- HTTPS required for webhook endpoints
|
|
|
|
| 196 |
- Input validation and sanitization
|
| 197 |
|
| 198 |
3. Data Protection:
|
| 199 |
-
- Call recordings are temporary
|
| 200 |
-
- Analysis results
|
| 201 |
-
-
|
| 202 |
-
|
| 203 |
-
|
| 204 |
-
|
| 205 |
-
|
| 206 |
-
|
| 207 |
-
|
| 208 |
-
|
| 209 |
-
|
| 210 |
-
|
| 211 |
-
|
| 212 |
-
|
| 213 |
-
|
| 214 |
-
|
| 215 |
-
|
| 216 |
-
|
| 217 |
-
|
| 218 |
-
- Log rotation
|
| 219 |
|
| 220 |
## Troubleshooting
|
| 221 |
|
| 222 |
1. Common Issues:
|
| 223 |
-
- Database connection errors
|
| 224 |
-
- API key validation failures
|
| 225 |
- Webhook delivery failures
|
|
|
|
|
|
|
|
|
|
| 226 |
|
| 227 |
2. Solutions:
|
| 228 |
-
- Check
|
| 229 |
- Verify API key
|
| 230 |
-
- Test
|
| 231 |
-
- Review
|
|
|
|
| 232 |
|
| 233 |
## Support
|
| 234 |
|
|
@@ -278,5 +307,4 @@ vBot follows a modern API-first architecture:
|
|
| 278 |
|
| 279 |
## API Endpoints
|
| 280 |
|
| 281 |
-
### Admin Endpoints
|
| 282 |
-
- `
|
|
|
|
| 11 |
|
| 12 |
# vBot - Intelligent Call Analysis System
|
| 13 |
|
| 14 |
+
vBot is a distributed call analysis system where a central server ONLY handles AI-powered transcription and analysis, while each customer maintains their own complete infrastructure (Asterisk, database, web server) and receives results via webhooks.
|
| 15 |
+
|
| 16 |
+
## System Architecture
|
| 17 |
+
|
| 18 |
+
### Central Server (vBot)
|
| 19 |
+
- ONLY handles call transcription and analysis
|
| 20 |
+
- ONLY manages customer accounts and API keys
|
| 21 |
+
- ONLY sends results via webhooks
|
| 22 |
+
- Hosted on Hugging Face Space
|
| 23 |
+
- Does NOT store customer data
|
| 24 |
+
- Does NOT connect to customer databases
|
| 25 |
+
- Does NOT manage customer infrastructure
|
| 26 |
+
- Does NOT store call recordings permanently
|
| 27 |
+
|
| 28 |
+
### Customer Infrastructure (Remote)
|
| 29 |
+
Each customer maintains their own complete system:
|
| 30 |
+
- Asterisk PBX server for call handling
|
| 31 |
+
- MySQL database for storing call records
|
| 32 |
+
- Web server (Apache/Nginx) for webhook handling
|
| 33 |
+
- SSL certificate for secure webhooks
|
| 34 |
+
- Complete control over their data and infrastructure
|
| 35 |
+
- Full ownership of their call recordings
|
| 36 |
|
| 37 |
## Features
|
| 38 |
|
| 39 |
+
- Centralized AI-powered call analysis
|
| 40 |
+
- Distributed customer infrastructure
|
| 41 |
+
- Secure customer isolation
|
| 42 |
+
- Real-time call processing
|
| 43 |
- Sentiment analysis and keyword extraction
|
| 44 |
- Modern admin interface for customer management
|
| 45 |
+
- Webhook-based result delivery
|
|
|
|
|
|
|
| 46 |
|
| 47 |
## System Requirements
|
| 48 |
|
| 49 |
+
### Central Server (vBot)
|
| 50 |
- Python 3.8 or higher
|
|
|
|
|
|
|
| 51 |
- Hugging Face Space (for deployment)
|
| 52 |
+
- No database required (only manages customer accounts)
|
| 53 |
+
|
| 54 |
+
### Customer Infrastructure
|
| 55 |
+
- Asterisk PBX server
|
| 56 |
+
- Web server (Apache/Nginx)
|
| 57 |
+
- PHP 7.4 or higher
|
| 58 |
+
- MySQL 5.7 or higher
|
| 59 |
+
- SSL certificate (for secure webhooks)
|
| 60 |
|
| 61 |
+
## Quick Start (Central Server)
|
| 62 |
|
| 63 |
1. Clone the repository:
|
| 64 |
```bash
|
|
|
|
| 88 |
python main.py
|
| 89 |
```
|
| 90 |
|
| 91 |
+
## Admin Setup (Central Server)
|
| 92 |
|
| 93 |
1. Access the admin interface:
|
| 94 |
- URL: `https://your-domain.com/admin`
|
| 95 |
- Default credentials: admin/admin (change immediately)
|
| 96 |
|
| 97 |
+
2. Create a new customer:
|
| 98 |
- Click "Add Customer"
|
| 99 |
- Fill in customer details:
|
| 100 |
- Name
|
|
|
|
| 103 |
- System will generate a unique API key
|
| 104 |
|
| 105 |
3. Configure customer webhook:
|
| 106 |
+
- Customer provides their webhook URL
|
| 107 |
- Optional: Set webhook secret for additional security
|
| 108 |
|
| 109 |
+
## Customer Setup
|
| 110 |
+
|
| 111 |
+
### 1. Asterisk Configuration
|
| 112 |
+
On your Asterisk server:
|
| 113 |
+
```ini
|
| 114 |
+
[from-internal]
|
| 115 |
+
exten => _X.,1,Answer()
|
| 116 |
+
same => n,Record(/tmp/calls/${UNIQUEID}.wav,0,0)
|
| 117 |
+
same => n,Set(CALL_ID=${UNIQUEID})
|
| 118 |
+
same => n,Set(CALLER=${CALLERID(num)})
|
| 119 |
+
same => n,Set(CALLED=${EXTEN})
|
| 120 |
+
same => n,AGI(agi://localhost:4573/process_call)
|
| 121 |
+
same => n,Hangup()
|
| 122 |
+
```
|
| 123 |
+
|
| 124 |
+
### 2. Download Webhook Handler
|
| 125 |
+
```bash
|
| 126 |
+
git clone https://huggingface.co/spaces/iajitpanday/vBot/customer_webhook
|
| 127 |
+
```
|
| 128 |
+
|
| 129 |
+
### 3. Deploy to Your Web Server
|
| 130 |
+
```bash
|
| 131 |
+
cp -r customer_webhook/* /var/www/html/vbot-webhook/
|
| 132 |
+
```
|
| 133 |
+
|
| 134 |
+
### 4. Create Database
|
| 135 |
+
On your MySQL server:
|
| 136 |
+
```sql
|
| 137 |
+
CREATE DATABASE vbot_calls;
|
| 138 |
+
USE vbot_calls;
|
| 139 |
+
|
| 140 |
+
CREATE TABLE call_records (
|
| 141 |
+
id VARCHAR(36) PRIMARY KEY,
|
| 142 |
+
customer_id INT NOT NULL,
|
| 143 |
+
caller_number VARCHAR(20) NOT NULL,
|
| 144 |
+
called_number VARCHAR(20) NOT NULL,
|
| 145 |
+
transcription TEXT,
|
| 146 |
+
summary TEXT,
|
| 147 |
+
sentiment VARCHAR(50),
|
| 148 |
+
keywords TEXT,
|
| 149 |
+
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
| 150 |
+
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
|
| 151 |
+
);
|
| 152 |
+
```
|
| 153 |
+
|
| 154 |
+
### 5. Configure Webhook Handler
|
| 155 |
+
- Copy `config/config.example.php` to `config/config.php`
|
| 156 |
+
- Update database credentials
|
| 157 |
+
- Add your API key (provided by vBot admin)
|
| 158 |
+
|
| 159 |
+
### 6. Configure Web Server
|
| 160 |
+
|
| 161 |
+
#### Apache Configuration
|
| 162 |
+
```apache
|
| 163 |
+
# Place in Apache configuration or .htaccess
|
| 164 |
+
RewriteEngine On
|
| 165 |
+
RewriteBase /vbot-webhook/
|
| 166 |
+
RewriteCond %{REQUEST_FILENAME} !-f
|
| 167 |
+
RewriteCond %{REQUEST_FILENAME} !-d
|
| 168 |
+
RewriteRule ^(.*)$ webhook.php [QSA,L]
|
| 169 |
+
```
|
| 170 |
+
|
| 171 |
+
#### Nginx Configuration
|
| 172 |
+
```nginx
|
| 173 |
+
location /vbot-webhook/ {
|
| 174 |
+
root /var/www/html;
|
| 175 |
+
index webhook.php;
|
| 176 |
+
|
| 177 |
+
location ~ \.php$ {
|
| 178 |
+
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
|
| 179 |
+
fastcgi_index webhook.php;
|
| 180 |
+
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
|
| 181 |
+
include fastcgi_params;
|
| 182 |
+
}
|
| 183 |
+
}
|
| 184 |
+
```
|
| 185 |
+
|
| 186 |
+
## API Integration
|
| 187 |
+
|
| 188 |
+
### 1. Process a Call (from your Asterisk server)
|
| 189 |
+
```bash
|
| 190 |
+
curl -X POST https://vbot-server.com/api/process-call \
|
| 191 |
+
-H "X-API-Key: your_api_key" \
|
| 192 |
+
-H "Content-Type: multipart/form-data" \
|
| 193 |
+
-F "file=@/tmp/calls/${UNIQUEID}.wav" \
|
| 194 |
+
-H "caller_number=${CALLER}" \
|
| 195 |
+
-H "called_number=${CALLED}"
|
| 196 |
+
```
|
| 197 |
+
|
| 198 |
+
### 2. Receive Webhook Data
|
| 199 |
+
Your webhook endpoint will receive POST requests with call analysis results:
|
| 200 |
+
```json
|
| 201 |
+
{
|
| 202 |
+
"call_id": "uuid",
|
| 203 |
+
"caller_number": "+1234567890",
|
| 204 |
+
"called_number": "+0987654321",
|
| 205 |
+
"transcription": "Call transcript...",
|
| 206 |
+
"summary": "Call summary...",
|
| 207 |
+
"sentiment": "positive",
|
| 208 |
+
"keywords": "keyword1, keyword2",
|
| 209 |
+
"timestamp": "2024-03-14T12:00:00Z",
|
| 210 |
+
"customer_id": 123
|
| 211 |
+
}
|
| 212 |
+
```
|
| 213 |
|
| 214 |
## Security
|
| 215 |
|
|
|
|
| 219 |
- Keys can be regenerated if compromised
|
| 220 |
|
| 221 |
2. Webhook Security:
|
|
|
|
| 222 |
- HTTPS required for webhook endpoints
|
| 223 |
+
- Optional webhook secret for signature validation
|
| 224 |
- Input validation and sanitization
|
| 225 |
|
| 226 |
3. Data Protection:
|
| 227 |
+
- Call recordings are temporary on central server
|
| 228 |
+
- Analysis results sent securely via webhooks
|
| 229 |
+
- Each customer maintains their own database
|
| 230 |
+
- Complete data isolation between customers
|
| 231 |
+
- No shared infrastructure
|
| 232 |
+
|
| 233 |
+
## Monitoring
|
| 234 |
+
|
| 235 |
+
### Central Server (vBot)
|
| 236 |
+
- Application logs: `logs/app.log`
|
| 237 |
+
- Error logs: `logs/error.log`
|
| 238 |
+
- Access logs: `logs/access.log`
|
| 239 |
+
- Health endpoint: `/health`
|
| 240 |
+
|
| 241 |
+
### Customer Infrastructure
|
| 242 |
+
- Asterisk logs
|
| 243 |
+
- Webhook logs: `logs/webhook.log`
|
| 244 |
+
- Database monitoring
|
| 245 |
+
- Web server logs
|
|
|
|
| 246 |
|
| 247 |
## Troubleshooting
|
| 248 |
|
| 249 |
1. Common Issues:
|
|
|
|
|
|
|
| 250 |
- Webhook delivery failures
|
| 251 |
+
- API key validation errors
|
| 252 |
+
- Database connection issues
|
| 253 |
+
- Asterisk integration problems
|
| 254 |
|
| 255 |
2. Solutions:
|
| 256 |
+
- Check webhook URL and SSL
|
| 257 |
- Verify API key
|
| 258 |
+
- Test database connection
|
| 259 |
+
- Review Asterisk logs
|
| 260 |
+
- Check webhook logs
|
| 261 |
|
| 262 |
## Support
|
| 263 |
|
|
|
|
| 307 |
|
| 308 |
## API Endpoints
|
| 309 |
|
| 310 |
+
### Admin Endpoints
|
|
|
SETUP_GUIDE.md
CHANGED
|
@@ -1,441 +1,335 @@
|
|
| 1 |
# vBot Setup Guide
|
| 2 |
|
| 3 |
-
|
| 4 |
|
| 5 |
-
|
| 6 |
|
| 7 |
-
|
| 8 |
-
- Go to [Hugging Face](https://huggingface.co)
|
| 9 |
-
- Sign up for a free account
|
| 10 |
-
- Create a new Space
|
| 11 |
|
| 12 |
-
|
| 13 |
-
- Click "Use this Space"
|
| 14 |
-
- Choose "Docker" as the SDK
|
| 15 |
-
- Select "FastAPI" as the framework
|
| 16 |
-
- Deploy the space
|
| 17 |
|
| 18 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 19 |
```bash
|
| 20 |
-
|
| 21 |
-
|
| 22 |
-
|
| 23 |
-
# Set these environment variables in your Space settings
|
| 24 |
-
JWT_SECRET=<generated-secret>
|
| 25 |
-
ADMIN_USERNAME=your-admin-username
|
| 26 |
-
ADMIN_PASSWORD=your-secure-password
|
| 27 |
-
DATABASE_URL=mysql+pymysql://username:password@host:port/database
|
| 28 |
```
|
| 29 |
|
| 30 |
-
|
| 31 |
-
|
| 32 |
-
|
| 33 |
-
|
| 34 |
-
|
| 35 |
-
- [Clever Cloud](https://www.clever-cloud.com/)
|
| 36 |
-
|
| 37 |
-
2. **Create Database**
|
| 38 |
-
- Sign up for an account
|
| 39 |
-
- Create a new MySQL database
|
| 40 |
-
- Get your database connection URL
|
| 41 |
-
- Update the `DATABASE_URL` environment variable
|
| 42 |
-
|
| 43 |
-
3. **Verify Database Connection**
|
| 44 |
-
- The application will automatically create necessary tables
|
| 45 |
-
- Check the logs for any connection issues
|
| 46 |
-
|
| 47 |
-
## Step 3: Admin Setup
|
| 48 |
-
|
| 49 |
-
1. **Access Admin Dashboard**
|
| 50 |
-
- Go to your Space URL
|
| 51 |
-
- Click "Admin Login"
|
| 52 |
-
- Use your admin credentials
|
| 53 |
-
|
| 54 |
-
2. **Create First Customer**
|
| 55 |
-
- Click "Add New Customer"
|
| 56 |
-
- Fill in customer details:
|
| 57 |
-
- Name
|
| 58 |
-
- Company Name
|
| 59 |
-
- Email
|
| 60 |
-
- Save the customer
|
| 61 |
-
- Copy the generated API key
|
| 62 |
|
| 63 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 64 |
|
| 65 |
-
|
| 66 |
-
- Install Asterisk if not already installed
|
| 67 |
-
- Configure your dialplan
|
| 68 |
-
- Set up call recording
|
| 69 |
|
| 70 |
-
|
| 71 |
-
-
|
| 72 |
-
-
|
| 73 |
-
- Set up the API key
|
| 74 |
|
| 75 |
-
|
| 76 |
-
-
|
| 77 |
-
-
|
| 78 |
-
-
|
| 79 |
|
| 80 |
-
|
| 81 |
|
| 82 |
-
1.
|
| 83 |
```bash
|
| 84 |
-
curl
|
| 85 |
-
-H "Content-Type: application/x-www-form-urlencoded" \
|
| 86 |
-
-d "username=admin&password=your-password"
|
| 87 |
```
|
| 88 |
|
| 89 |
-
2.
|
| 90 |
-
|
| 91 |
-
-
|
| 92 |
-
|
| 93 |
-
|
| 94 |
-
3. **Monitor Logs**
|
| 95 |
-
- Check Space logs for errors
|
| 96 |
-
- Monitor database connections
|
| 97 |
-
- Verify API responses
|
| 98 |
-
|
| 99 |
-
## Step 6: Production Deployment
|
| 100 |
-
|
| 101 |
-
1. **Security Checklist**
|
| 102 |
-
- [ ] Secure JWT secret
|
| 103 |
-
- [ ] Strong admin password
|
| 104 |
-
- [ ] HTTPS enabled
|
| 105 |
-
- [ ] API keys properly configured
|
| 106 |
-
- [ ] Database credentials secured
|
| 107 |
-
|
| 108 |
-
2. **Performance Optimization**
|
| 109 |
-
- Configure database connection pooling
|
| 110 |
-
- Set up caching if needed
|
| 111 |
-
- Monitor resource usage
|
| 112 |
-
|
| 113 |
-
3. **Monitoring Setup**
|
| 114 |
-
- Enable Space monitoring
|
| 115 |
-
- Set up database monitoring
|
| 116 |
-
- Configure alerting
|
| 117 |
-
|
| 118 |
-
## Step 7: Maintenance
|
| 119 |
-
|
| 120 |
-
1. **Regular Tasks**
|
| 121 |
-
- Monitor system logs
|
| 122 |
-
- Check database performance
|
| 123 |
-
- Update dependencies
|
| 124 |
-
- Backup data
|
| 125 |
-
|
| 126 |
-
2. **Customer Management**
|
| 127 |
-
- Monitor customer usage
|
| 128 |
-
- Handle customer requests
|
| 129 |
-
- Update customer configurations
|
| 130 |
-
|
| 131 |
-
3. **System Updates**
|
| 132 |
-
- Keep dependencies updated
|
| 133 |
-
- Monitor for security patches
|
| 134 |
-
- Plan for feature updates
|
| 135 |
-
|
| 136 |
-
## Troubleshooting
|
| 137 |
-
|
| 138 |
-
1. **Common Issues**
|
| 139 |
-
- Database connection errors
|
| 140 |
-
- API authentication issues
|
| 141 |
-
- Call processing failures
|
| 142 |
-
- Performance problems
|
| 143 |
|
| 144 |
-
|
| 145 |
-
- Check environment variables
|
| 146 |
-
- Verify database credentials
|
| 147 |
-
- Monitor system logs
|
| 148 |
-
- Test API endpoints
|
| 149 |
|
| 150 |
-
|
| 151 |
-
- Check documentation
|
| 152 |
-
- Review logs
|
| 153 |
-
- Contact support if needed
|
| 154 |
|
| 155 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 156 |
|
| 157 |
-
|
| 158 |
-
|
| 159 |
-
-
|
| 160 |
-
|
| 161 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 162 |
|
| 163 |
-
|
| 164 |
-
|
| 165 |
-
|
| 166 |
-
|
| 167 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 168 |
|
| 169 |
-
|
| 170 |
-
|
| 171 |
-
|
| 172 |
-
|
| 173 |
-
|
| 174 |
|
| 175 |
-
|
|
|
|
|
|
|
|
|
|
| 176 |
|
| 177 |
-
###
|
| 178 |
|
| 179 |
-
1.
|
| 180 |
-
```
|
| 181 |
-
|
| 182 |
-
USE vbot_main;
|
| 183 |
```
|
| 184 |
|
| 185 |
-
2.
|
| 186 |
-
```
|
| 187 |
-
|
| 188 |
-
|
| 189 |
-
|
| 190 |
-
|
| 191 |
-
|
| 192 |
-
|
| 193 |
-
|
| 194 |
-
|
| 195 |
-
|
| 196 |
-
|
| 197 |
-
|
| 198 |
-
|
| 199 |
-
|
| 200 |
-
db_user VARCHAR(100),
|
| 201 |
-
db_password VARCHAR(255)
|
| 202 |
-
);
|
| 203 |
```
|
| 204 |
|
| 205 |
-
3.
|
| 206 |
-
```
|
| 207 |
-
|
| 208 |
-
|
| 209 |
-
CREATE INDEX idx_is_active ON customers(is_active);
|
| 210 |
```
|
| 211 |
|
| 212 |
-
###
|
| 213 |
|
| 214 |
-
1.
|
| 215 |
-
```
|
| 216 |
-
|
| 217 |
-
USE customer_db_name;
|
| 218 |
```
|
| 219 |
|
| 220 |
-
2.
|
| 221 |
```sql
|
|
|
|
|
|
|
|
|
|
| 222 |
CREATE TABLE call_records (
|
| 223 |
id VARCHAR(36) PRIMARY KEY,
|
| 224 |
customer_id INT NOT NULL,
|
| 225 |
caller_number VARCHAR(20) NOT NULL,
|
| 226 |
called_number VARCHAR(20) NOT NULL,
|
| 227 |
-
file_path VARCHAR(255),
|
| 228 |
transcription TEXT,
|
| 229 |
summary TEXT,
|
| 230 |
-
sentiment VARCHAR(
|
| 231 |
keywords TEXT,
|
| 232 |
-
created_at
|
| 233 |
-
updated_at
|
| 234 |
-
FOREIGN KEY (customer_id) REFERENCES customers(id)
|
| 235 |
);
|
| 236 |
```
|
| 237 |
|
| 238 |
-
3.
|
| 239 |
```sql
|
| 240 |
-
CREATE
|
| 241 |
-
|
| 242 |
-
CREATE INDEX idx_caller_number ON call_records(caller_number);
|
| 243 |
-
CREATE INDEX idx_called_number ON call_records(called_number);
|
| 244 |
-
```
|
| 245 |
-
|
| 246 |
-
### 3. Database User Setup
|
| 247 |
-
|
| 248 |
-
1. **Main Database User**
|
| 249 |
-
```sql
|
| 250 |
-
-- Create user for main database
|
| 251 |
-
CREATE USER 'vbot_admin'@'%' IDENTIFIED BY 'your_secure_password';
|
| 252 |
-
GRANT ALL PRIVILEGES ON vbot_main.* TO 'vbot_admin'@'%';
|
| 253 |
FLUSH PRIVILEGES;
|
| 254 |
```
|
| 255 |
|
| 256 |
-
|
| 257 |
-
```sql
|
| 258 |
-
-- Create user for customer database
|
| 259 |
-
CREATE USER 'customer_user'@'%' IDENTIFIED BY 'customer_secure_password';
|
| 260 |
-
GRANT ALL PRIVILEGES ON customer_db_name.* TO 'customer_user'@'%';
|
| 261 |
-
FLUSH PRIVILEGES;
|
| 262 |
-
```
|
| 263 |
|
| 264 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 265 |
|
| 266 |
-
|
| 267 |
```bash
|
| 268 |
-
|
| 269 |
-
|
| 270 |
-
|
| 271 |
-
|
| 272 |
-
|
| 273 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 274 |
```
|
| 275 |
|
| 276 |
-
|
| 277 |
```bash
|
| 278 |
-
|
| 279 |
-
|
| 280 |
-
|
| 281 |
-
# Test queries
|
| 282 |
-
USE customer_db_name;
|
| 283 |
-
SELECT * FROM call_records;
|
| 284 |
```
|
| 285 |
|
| 286 |
-
### 5.
|
| 287 |
|
| 288 |
-
1.
|
| 289 |
```bash
|
| 290 |
-
|
| 291 |
-
|
| 292 |
-
|
| 293 |
-
BACKUP_DIR="/path/to/backups"
|
| 294 |
-
DATE=$(date +%Y%m%d_%H%M%S)
|
| 295 |
-
|
| 296 |
-
# Create backup
|
| 297 |
-
mysqldump -h your-main-db-host -u vbot_admin -p vbot_main > \
|
| 298 |
-
"$BACKUP_DIR/vbot_main_$DATE.sql"
|
| 299 |
-
|
| 300 |
-
# Compress backup
|
| 301 |
-
gzip "$BACKUP_DIR/vbot_main_$DATE.sql"
|
| 302 |
-
|
| 303 |
-
# Keep only last 7 days of backups
|
| 304 |
-
find $BACKUP_DIR -name "vbot_main_*.sql.gz" -mtime +7 -delete
|
| 305 |
-
EOF
|
| 306 |
-
|
| 307 |
-
# Make script executable
|
| 308 |
-
chmod +x backup_main.sh
|
| 309 |
```
|
| 310 |
|
| 311 |
-
2.
|
| 312 |
```bash
|
| 313 |
-
#
|
| 314 |
-
|
| 315 |
-
|
| 316 |
-
|
| 317 |
-
DATE=$(date +%Y%m%d_%H%M%S)
|
| 318 |
-
|
| 319 |
-
# Create backup
|
| 320 |
-
mysqldump -h customer-db-host -u customer_user -p customer_db_name > \
|
| 321 |
-
"$BACKUP_DIR/customer_db_$DATE.sql"
|
| 322 |
-
|
| 323 |
-
# Compress backup
|
| 324 |
-
gzip "$BACKUP_DIR/customer_db_$DATE.sql"
|
| 325 |
-
|
| 326 |
-
# Keep only last 7 days of backups
|
| 327 |
-
find $BACKUP_DIR -name "customer_db_*.sql.gz" -mtime +7 -delete
|
| 328 |
-
EOF
|
| 329 |
-
|
| 330 |
-
# Make script executable
|
| 331 |
-
chmod +x backup_customer.sh
|
| 332 |
```
|
| 333 |
|
| 334 |
-
|
| 335 |
-
|
| 336 |
-
1. **Set Up Monitoring Queries**
|
| 337 |
```sql
|
| 338 |
-
|
| 339 |
-
SELECT table_schema AS "Database",
|
| 340 |
-
ROUND(SUM(data_length + index_length) / 1024 / 1024, 2) AS "Size (MB)"
|
| 341 |
-
FROM information_schema.tables
|
| 342 |
-
GROUP BY table_schema;
|
| 343 |
-
|
| 344 |
-
-- Check table sizes
|
| 345 |
-
SELECT table_name AS "Table",
|
| 346 |
-
ROUND(((data_length + index_length) / 1024 / 1024), 2) AS "Size (MB)"
|
| 347 |
-
FROM information_schema.tables
|
| 348 |
-
WHERE table_schema = "customer_db_name"
|
| 349 |
-
ORDER BY (data_length + index_length) DESC;
|
| 350 |
-
|
| 351 |
-
-- Check record counts
|
| 352 |
-
SELECT COUNT(*) FROM call_records;
|
| 353 |
```
|
| 354 |
|
| 355 |
-
|
|
|
|
|
|
|
| 356 |
```bash
|
| 357 |
-
|
| 358 |
-
|
| 359 |
-
|
| 360 |
-
|
| 361 |
-
# Check database size
|
| 362 |
-
DB_SIZE=$(mysql -h customer-db-host -u customer_user -p -N -e "
|
| 363 |
-
SELECT ROUND(SUM(data_length + index_length) / 1024 / 1024, 2)
|
| 364 |
-
FROM information_schema.tables
|
| 365 |
-
WHERE table_schema = 'customer_db_name'
|
| 366 |
-
")
|
| 367 |
-
|
| 368 |
-
# Alert if size exceeds 1GB
|
| 369 |
-
if (( $(echo "$DB_SIZE > 1024" | bc -l) )); then
|
| 370 |
-
echo "Database size exceeds 1GB: $DB_SIZE MB"
|
| 371 |
-
# Add your alert mechanism here (email, Slack, etc.)
|
| 372 |
-
fi
|
| 373 |
-
EOF
|
| 374 |
-
|
| 375 |
-
# Make script executable
|
| 376 |
-
chmod +x monitor_db.sh
|
| 377 |
```
|
| 378 |
|
| 379 |
-
|
|
|
|
|
|
|
|
|
|
| 380 |
|
| 381 |
-
|
|
|
|
|
|
|
|
|
|
| 382 |
|
| 383 |
-
|
| 384 |
-
-
|
| 385 |
-
-
|
|
|
|
|
|
|
| 386 |
|
| 387 |
-
|
| 388 |
-
- Port 5060 (SIP) - For VoIP communication
|
| 389 |
-
- Port 10000-20000 (RTP) - For audio streaming
|
| 390 |
-
- Port 5038 (AMI) - For Asterisk Manager Interface (optional)
|
| 391 |
|
| 392 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 393 |
|
| 394 |
-
|
| 395 |
```bash
|
| 396 |
-
#
|
| 397 |
-
sudo
|
| 398 |
|
| 399 |
-
#
|
| 400 |
-
sudo
|
| 401 |
-
sudo ufw allow 10000:20000/udp
|
| 402 |
```
|
| 403 |
|
| 404 |
-
|
| 405 |
-
-
|
| 406 |
-
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 407 |
|
| 408 |
-
|
| 409 |
```bash
|
| 410 |
-
#
|
| 411 |
-
|
| 412 |
|
| 413 |
-
#
|
| 414 |
-
|
| 415 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 416 |
|
| 417 |
-
#
|
| 418 |
-
|
|
|
|
| 419 |
```
|
| 420 |
|
| 421 |
-
|
| 422 |
|
| 423 |
-
1.
|
| 424 |
-
-
|
| 425 |
-
-
|
| 426 |
-
-
|
|
|
|
| 427 |
|
| 428 |
-
2.
|
| 429 |
```bash
|
| 430 |
-
#
|
| 431 |
-
|
| 432 |
-
|
| 433 |
-
|
| 434 |
-
|
| 435 |
-
|
| 436 |
-
|
| 437 |
-
|
| 438 |
-
|
| 439 |
-
|
| 440 |
-
|
| 441 |
-
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
# vBot Setup Guide
|
| 2 |
|
| 3 |
+
## Overview
|
| 4 |
|
| 5 |
+
This guide provides detailed instructions for setting up both the central vBot server and customer infrastructure. The system is designed with a distributed architecture where the central server handles only transcription and analysis, while customers maintain their own infrastructure.
|
| 6 |
|
| 7 |
+
## Central Server Setup
|
|
|
|
|
|
|
|
|
|
| 8 |
|
| 9 |
+
### 1. Deploy to Hugging Face Space
|
|
|
|
|
|
|
|
|
|
|
|
|
| 10 |
|
| 11 |
+
1. Create a Hugging Face account if you don't have one
|
| 12 |
+
2. Create a new Space:
|
| 13 |
+
- Go to https://huggingface.co/spaces
|
| 14 |
+
- Click "New Space"
|
| 15 |
+
- Choose "Gradio" as the SDK
|
| 16 |
+
- Set the Space name (e.g., "vBot")
|
| 17 |
+
- Set visibility (public/private)
|
| 18 |
+
|
| 19 |
+
3. Clone the repository:
|
| 20 |
```bash
|
| 21 |
+
git clone https://huggingface.co/spaces/iajitpanday/vBot
|
| 22 |
+
cd vBot
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 23 |
```
|
| 24 |
|
| 25 |
+
4. Configure environment variables:
|
| 26 |
+
```bash
|
| 27 |
+
cp .env.example .env
|
| 28 |
+
# Edit .env with your configuration
|
| 29 |
+
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 30 |
|
| 31 |
+
5. Push to Hugging Face:
|
| 32 |
+
```bash
|
| 33 |
+
git add .
|
| 34 |
+
git commit -m "Initial deployment"
|
| 35 |
+
git push
|
| 36 |
+
```
|
| 37 |
|
| 38 |
+
### 2. Configure Admin Account
|
|
|
|
|
|
|
|
|
|
| 39 |
|
| 40 |
+
1. Access the admin interface:
|
| 41 |
+
- URL: `https://your-space.huggingface.space/admin`
|
| 42 |
+
- Default credentials: admin/admin
|
|
|
|
| 43 |
|
| 44 |
+
2. Change admin password:
|
| 45 |
+
- Click "Change Password"
|
| 46 |
+
- Enter new secure password
|
| 47 |
+
- Save changes
|
| 48 |
|
| 49 |
+
### 3. Test System Health
|
| 50 |
|
| 51 |
+
1. Check health endpoint:
|
| 52 |
```bash
|
| 53 |
+
curl https://your-space.huggingface.space/health
|
|
|
|
|
|
|
| 54 |
```
|
| 55 |
|
| 56 |
+
2. Verify logs:
|
| 57 |
+
```bash
|
| 58 |
+
tail -f logs/app.log
|
| 59 |
+
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 60 |
|
| 61 |
+
## Customer Infrastructure Setup
|
|
|
|
|
|
|
|
|
|
|
|
|
| 62 |
|
| 63 |
+
### 1. Asterisk Server Setup
|
|
|
|
|
|
|
|
|
|
| 64 |
|
| 65 |
+
1. Install Asterisk:
|
| 66 |
+
```bash
|
| 67 |
+
sudo apt update
|
| 68 |
+
sudo apt install asterisk
|
| 69 |
+
```
|
| 70 |
|
| 71 |
+
2. Configure dialplan:
|
| 72 |
+
```ini
|
| 73 |
+
[from-internal]
|
| 74 |
+
exten => _X.,1,Answer()
|
| 75 |
+
same => n,Record(/tmp/calls/${UNIQUEID}.wav,0,0)
|
| 76 |
+
same => n,Set(CALL_ID=${UNIQUEID})
|
| 77 |
+
same => n,Set(CALLER=${CALLERID(num)})
|
| 78 |
+
same => n,Set(CALLED=${EXTEN})
|
| 79 |
+
same => n,AGI(agi://localhost:4573/process_call)
|
| 80 |
+
same => n,Hangup()
|
| 81 |
+
```
|
| 82 |
|
| 83 |
+
3. Configure AGI script:
|
| 84 |
+
```bash
|
| 85 |
+
sudo nano /etc/asterisk/agi-bin/process_call
|
| 86 |
+
```
|
| 87 |
+
```bash
|
| 88 |
+
#!/bin/bash
|
| 89 |
+
CALL_ID=$1
|
| 90 |
+
CALLER=$2
|
| 91 |
+
CALLED=$3
|
| 92 |
+
|
| 93 |
+
curl -X POST https://vbot-server.com/api/process-call \
|
| 94 |
+
-H "X-API-Key: your_api_key" \
|
| 95 |
+
-H "Content-Type: multipart/form-data" \
|
| 96 |
+
-F "file=@/tmp/calls/${CALL_ID}.wav" \
|
| 97 |
+
-H "caller_number=${CALLER}" \
|
| 98 |
+
-H "called_number=${CALLED}"
|
| 99 |
+
```
|
| 100 |
|
| 101 |
+
4. Set permissions:
|
| 102 |
+
```bash
|
| 103 |
+
sudo chmod +x /etc/asterisk/agi-bin/process_call
|
| 104 |
+
sudo chown asterisk:asterisk /etc/asterisk/agi-bin/process_call
|
| 105 |
+
```
|
| 106 |
|
| 107 |
+
5. Restart Asterisk:
|
| 108 |
+
```bash
|
| 109 |
+
sudo systemctl restart asterisk
|
| 110 |
+
```
|
| 111 |
|
| 112 |
+
### 2. Web Server Setup
|
| 113 |
|
| 114 |
+
1. Install Apache:
|
| 115 |
+
```bash
|
| 116 |
+
sudo apt install apache2 php php-mysql
|
|
|
|
| 117 |
```
|
| 118 |
|
| 119 |
+
2. Configure virtual host:
|
| 120 |
+
```apache
|
| 121 |
+
<VirtualHost *:80>
|
| 122 |
+
ServerName your-domain.com
|
| 123 |
+
DocumentRoot /var/www/html/vbot-webhook
|
| 124 |
+
|
| 125 |
+
<Directory /var/www/html/vbot-webhook>
|
| 126 |
+
Options Indexes FollowSymLinks
|
| 127 |
+
AllowOverride All
|
| 128 |
+
Require all granted
|
| 129 |
+
</Directory>
|
| 130 |
+
|
| 131 |
+
ErrorLog ${APACHE_LOG_DIR}/vbot-error.log
|
| 132 |
+
CustomLog ${APACHE_LOG_DIR}/vbot-access.log combined
|
| 133 |
+
</VirtualHost>
|
|
|
|
|
|
|
|
|
|
| 134 |
```
|
| 135 |
|
| 136 |
+
3. Enable SSL:
|
| 137 |
+
```bash
|
| 138 |
+
sudo apt install certbot python3-certbot-apache
|
| 139 |
+
sudo certbot --apache -d your-domain.com
|
|
|
|
| 140 |
```
|
| 141 |
|
| 142 |
+
### 3. Database Setup
|
| 143 |
|
| 144 |
+
1. Install MySQL:
|
| 145 |
+
```bash
|
| 146 |
+
sudo apt install mysql-server
|
|
|
|
| 147 |
```
|
| 148 |
|
| 149 |
+
2. Create database:
|
| 150 |
```sql
|
| 151 |
+
CREATE DATABASE vbot_calls;
|
| 152 |
+
USE vbot_calls;
|
| 153 |
+
|
| 154 |
CREATE TABLE call_records (
|
| 155 |
id VARCHAR(36) PRIMARY KEY,
|
| 156 |
customer_id INT NOT NULL,
|
| 157 |
caller_number VARCHAR(20) NOT NULL,
|
| 158 |
called_number VARCHAR(20) NOT NULL,
|
|
|
|
| 159 |
transcription TEXT,
|
| 160 |
summary TEXT,
|
| 161 |
+
sentiment VARCHAR(50),
|
| 162 |
keywords TEXT,
|
| 163 |
+
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
| 164 |
+
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
|
|
|
|
| 165 |
);
|
| 166 |
```
|
| 167 |
|
| 168 |
+
3. Create database user:
|
| 169 |
```sql
|
| 170 |
+
CREATE USER 'vbot_user'@'localhost' IDENTIFIED BY 'your_password';
|
| 171 |
+
GRANT ALL PRIVILEGES ON vbot_calls.* TO 'vbot_user'@'localhost';
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 172 |
FLUSH PRIVILEGES;
|
| 173 |
```
|
| 174 |
|
| 175 |
+
### 4. Webhook Handler Setup
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 176 |
|
| 177 |
+
1. Download webhook handler:
|
| 178 |
+
```bash
|
| 179 |
+
git clone https://huggingface.co/spaces/iajitpanday/vBot/customer_webhook
|
| 180 |
+
sudo cp -r customer_webhook/* /var/www/html/vbot-webhook/
|
| 181 |
+
```
|
| 182 |
|
| 183 |
+
2. Configure webhook handler:
|
| 184 |
```bash
|
| 185 |
+
sudo cp /var/www/html/vbot-webhook/config/config.example.php /var/www/html/vbot-webhook/config/config.php
|
| 186 |
+
sudo nano /var/www/html/vbot-webhook/config/config.php
|
| 187 |
+
```
|
| 188 |
+
```php
|
| 189 |
+
<?php
|
| 190 |
+
return [
|
| 191 |
+
'db' => [
|
| 192 |
+
'host' => 'localhost',
|
| 193 |
+
'name' => 'vbot_calls',
|
| 194 |
+
'user' => 'vbot_user',
|
| 195 |
+
'pass' => 'your_password'
|
| 196 |
+
],
|
| 197 |
+
'api_key' => 'your_api_key'
|
| 198 |
+
];
|
| 199 |
```
|
| 200 |
|
| 201 |
+
3. Set permissions:
|
| 202 |
```bash
|
| 203 |
+
sudo chown -R www-data:www-data /var/www/html/vbot-webhook
|
| 204 |
+
sudo chmod -R 755 /var/www/html/vbot-webhook
|
|
|
|
|
|
|
|
|
|
|
|
|
| 205 |
```
|
| 206 |
|
| 207 |
+
### 5. Testing Setup
|
| 208 |
|
| 209 |
+
1. Test webhook endpoint:
|
| 210 |
```bash
|
| 211 |
+
curl -X POST https://your-domain.com/vbot-webhook/webhook.php \
|
| 212 |
+
-H "Content-Type: application/json" \
|
| 213 |
+
-d '{"test": true}'
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 214 |
```
|
| 215 |
|
| 216 |
+
2. Test call recording:
|
| 217 |
```bash
|
| 218 |
+
# Make a test call
|
| 219 |
+
# Check /tmp/calls/ for recording
|
| 220 |
+
# Check webhook logs
|
| 221 |
+
tail -f /var/log/apache2/vbot-access.log
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 222 |
```
|
| 223 |
|
| 224 |
+
3. Test database:
|
|
|
|
|
|
|
| 225 |
```sql
|
| 226 |
+
SELECT * FROM call_records ORDER BY created_at DESC LIMIT 1;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 227 |
```
|
| 228 |
|
| 229 |
+
## Security Considerations
|
| 230 |
+
|
| 231 |
+
1. Firewall Configuration:
|
| 232 |
```bash
|
| 233 |
+
sudo ufw allow 80/tcp
|
| 234 |
+
sudo ufw allow 443/tcp
|
| 235 |
+
sudo ufw allow 5060/udp # SIP
|
| 236 |
+
sudo ufw allow 10000:20000/udp # RTP
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 237 |
```
|
| 238 |
|
| 239 |
+
2. SSL/TLS:
|
| 240 |
+
- Use Let's Encrypt for free SSL certificates
|
| 241 |
+
- Configure automatic renewal
|
| 242 |
+
- Use strong cipher suites
|
| 243 |
|
| 244 |
+
3. File Permissions:
|
| 245 |
+
- Secure webhook handler files
|
| 246 |
+
- Restrict access to call recordings
|
| 247 |
+
- Use appropriate ownership
|
| 248 |
|
| 249 |
+
4. Database Security:
|
| 250 |
+
- Use strong passwords
|
| 251 |
+
- Limit database access
|
| 252 |
+
- Regular backups
|
| 253 |
+
- Encryption at rest
|
| 254 |
|
| 255 |
+
## Monitoring Setup
|
|
|
|
|
|
|
|
|
|
| 256 |
|
| 257 |
+
1. Log Monitoring:
|
| 258 |
+
```bash
|
| 259 |
+
# Asterisk logs
|
| 260 |
+
tail -f /var/log/asterisk/messages
|
| 261 |
+
|
| 262 |
+
# Webhook logs
|
| 263 |
+
tail -f /var/log/apache2/vbot-access.log
|
| 264 |
+
|
| 265 |
+
# Database logs
|
| 266 |
+
tail -f /var/log/mysql/error.log
|
| 267 |
+
```
|
| 268 |
|
| 269 |
+
2. System Monitoring:
|
| 270 |
```bash
|
| 271 |
+
# Install monitoring tools
|
| 272 |
+
sudo apt install prometheus node-exporter
|
| 273 |
|
| 274 |
+
# Configure monitoring
|
| 275 |
+
sudo nano /etc/prometheus/prometheus.yml
|
|
|
|
| 276 |
```
|
| 277 |
|
| 278 |
+
3. Alerting:
|
| 279 |
+
- Set up email notifications
|
| 280 |
+
- Configure alert thresholds
|
| 281 |
+
- Monitor disk space
|
| 282 |
+
|
| 283 |
+
## Maintenance
|
| 284 |
+
|
| 285 |
+
1. Regular Tasks:
|
| 286 |
+
- Update system packages
|
| 287 |
+
- Rotate logs
|
| 288 |
+
- Backup database
|
| 289 |
+
- Clean old recordings
|
| 290 |
|
| 291 |
+
2. Backup Strategy:
|
| 292 |
```bash
|
| 293 |
+
# Database backup
|
| 294 |
+
mysqldump -u vbot_user -p vbot_calls > backup.sql
|
| 295 |
|
| 296 |
+
# Configuration backup
|
| 297 |
+
tar -czf config_backup.tar.gz /etc/asterisk/
|
| 298 |
+
```
|
| 299 |
+
|
| 300 |
+
3. Update Process:
|
| 301 |
+
```bash
|
| 302 |
+
# Update webhook handler
|
| 303 |
+
cd /var/www/html/vbot-webhook
|
| 304 |
+
git pull
|
| 305 |
|
| 306 |
+
# Update Asterisk
|
| 307 |
+
sudo apt update
|
| 308 |
+
sudo apt upgrade
|
| 309 |
```
|
| 310 |
|
| 311 |
+
## Troubleshooting
|
| 312 |
|
| 313 |
+
1. Common Issues:
|
| 314 |
+
- Webhook delivery failures
|
| 315 |
+
- Database connection errors
|
| 316 |
+
- Call recording problems
|
| 317 |
+
- SSL certificate issues
|
| 318 |
|
| 319 |
+
2. Debug Tools:
|
| 320 |
```bash
|
| 321 |
+
# Check webhook logs
|
| 322 |
+
tail -f /var/log/apache2/vbot-error.log
|
| 323 |
+
|
| 324 |
+
# Check Asterisk CLI
|
| 325 |
+
sudo asterisk -rx "core show version"
|
| 326 |
+
|
| 327 |
+
# Test database connection
|
| 328 |
+
mysql -u vbot_user -p vbot_calls
|
| 329 |
+
```
|
| 330 |
+
|
| 331 |
+
3. Support:
|
| 332 |
+
- Check documentation
|
| 333 |
+
- Review logs
|
| 334 |
+
- Contact support
|
| 335 |
+
- Submit issues
|
USER_MANUAL.md
CHANGED
|
@@ -1,237 +1,274 @@
|
|
| 1 |
# vBot User Manual
|
| 2 |
|
| 3 |
-
|
| 4 |
|
| 5 |
-
|
| 6 |
-
1. [Introduction](#introduction)
|
| 7 |
-
2. [Getting Started](#getting-started)
|
| 8 |
-
3. [Admin Interface](#admin-interface)
|
| 9 |
-
4. [Customer Management](#customer-management)
|
| 10 |
-
5. [API Usage](#api-usage)
|
| 11 |
-
6. [Troubleshooting](#troubleshooting)
|
| 12 |
|
| 13 |
-
##
|
| 14 |
|
| 15 |
-
|
| 16 |
|
| 17 |
-
|
| 18 |
-
-
|
| 19 |
-
-
|
| 20 |
-
-
|
| 21 |
-
-
|
| 22 |
-
- Secure API access
|
| 23 |
-
- Customer management
|
| 24 |
|
| 25 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 26 |
|
| 27 |
-
|
| 28 |
-
-
|
| 29 |
-
-
|
| 30 |
-
- Admin credentials
|
| 31 |
|
| 32 |
-
|
| 33 |
-
|
| 34 |
-
|
| 35 |
-
|
| 36 |
-
4. Test the integration
|
| 37 |
|
| 38 |
## Admin Interface
|
| 39 |
|
| 40 |
-
###
|
| 41 |
-
1. Navigate to the admin interface
|
| 42 |
-
2. Enter your admin credentials
|
| 43 |
-
3. Click "Login"
|
| 44 |
|
| 45 |
-
|
| 46 |
-
|
| 47 |
-
- Total customers
|
| 48 |
-
- Active customers
|
| 49 |
- Recent activity
|
| 50 |
-
- System
|
|
|
|
| 51 |
|
| 52 |
-
###
|
| 53 |
-
- **Customers**: Manage customer accounts
|
| 54 |
-
- **Settings**: Configure system settings
|
| 55 |
-
- **Logs**: View system logs
|
| 56 |
-
- **Help**: Access documentation
|
| 57 |
|
| 58 |
-
|
|
|
|
|
|
|
|
|
|
| 59 |
|
| 60 |
-
|
| 61 |
-
1. Click "Add
|
| 62 |
-
2. Fill in
|
| 63 |
- Name
|
| 64 |
- Company Name
|
| 65 |
- Email
|
| 66 |
-
3.
|
| 67 |
-
4. Copy
|
| 68 |
|
| 69 |
-
|
| 70 |
-
|
| 71 |
-
|
| 72 |
-
|
| 73 |
-
|
| 74 |
|
| 75 |
-
|
| 76 |
-
|
| 77 |
-
|
| 78 |
-
|
| 79 |
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
### Authentication
|
| 83 |
-
```bash
|
| 84 |
-
# Get JWT token
|
| 85 |
-
curl -X POST "https://your-space.huggingface.space/api/v1/token" \
|
| 86 |
-
-H "Content-Type: application/x-www-form-urlencoded" \
|
| 87 |
-
-d "username=admin&password=your-password"
|
| 88 |
-
```
|
| 89 |
|
| 90 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 91 |
|
| 92 |
-
####
|
| 93 |
-
|
| 94 |
-
|
| 95 |
-
|
| 96 |
-
-H "caller-number: +1234567890" \
|
| 97 |
-
-H "called-number: +0987654321" \
|
| 98 |
-
-F "file=@call.wav"
|
| 99 |
-
```
|
| 100 |
|
| 101 |
-
|
| 102 |
-
```bash
|
| 103 |
-
curl -X GET "https://your-space.huggingface.space/api/v1/calls" \
|
| 104 |
-
-H "api-key: YOUR_API_KEY"
|
| 105 |
-
```
|
| 106 |
|
| 107 |
-
|
| 108 |
-
```bash
|
| 109 |
-
curl -X GET "https://your-space.huggingface.space/api/v1/calls/{call_id}" \
|
| 110 |
-
-H "api-key: YOUR_API_KEY"
|
| 111 |
-
```
|
| 112 |
|
| 113 |
-
#### Search Calls
|
| 114 |
```bash
|
| 115 |
-
curl -X
|
| 116 |
-
|
| 117 |
-
|
| 118 |
-
|
| 119 |
-
|
| 120 |
-
|
| 121 |
-
"caller_number": "+1234567890"
|
| 122 |
-
}'
|
| 123 |
```
|
| 124 |
|
| 125 |
-
###
|
| 126 |
|
| 127 |
-
|
| 128 |
```json
|
| 129 |
{
|
| 130 |
-
|
| 131 |
-
|
| 132 |
-
|
| 133 |
-
|
| 134 |
-
|
| 135 |
-
|
| 136 |
-
|
|
|
|
|
|
|
| 137 |
}
|
| 138 |
```
|
| 139 |
|
| 140 |
-
|
| 141 |
-
|
| 142 |
-
|
| 143 |
-
|
| 144 |
-
|
| 145 |
-
"id": "123",
|
| 146 |
-
"caller_number": "+1234567890",
|
| 147 |
-
"called_number": "+0987654321",
|
| 148 |
-
"timestamp": "2024-01-01T12:00:00Z",
|
| 149 |
-
"duration": 300,
|
| 150 |
-
"status": "completed"
|
| 151 |
-
}
|
| 152 |
-
],
|
| 153 |
-
"total": 1,
|
| 154 |
-
"page": 1,
|
| 155 |
-
"per_page": 10
|
| 156 |
-
}
|
| 157 |
-
```
|
| 158 |
|
| 159 |
## Troubleshooting
|
| 160 |
|
| 161 |
-
### Common Issues
|
| 162 |
|
| 163 |
-
####
|
| 164 |
-
|
| 165 |
-
|
| 166 |
-
|
|
|
|
| 167 |
|
| 168 |
-
####
|
| 169 |
-
|
| 170 |
-
|
| 171 |
-
|
|
|
|
| 172 |
|
| 173 |
-
####
|
| 174 |
-
|
| 175 |
-
|
| 176 |
-
|
|
|
|
| 177 |
|
| 178 |
-
###
|
| 179 |
|
| 180 |
-
####
|
| 181 |
-
```
|
| 182 |
-
|
| 183 |
-
|
| 184 |
-
```
|
| 185 |
|
| 186 |
-
|
| 187 |
-
|
| 188 |
-
|
| 189 |
-
|
| 190 |
-
|
| 191 |
```
|
| 192 |
|
| 193 |
-
|
| 194 |
-
|
| 195 |
-
|
| 196 |
-
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 197 |
|
| 198 |
## Best Practices
|
| 199 |
|
| 200 |
-
### Security
|
|
|
|
|
|
|
| 201 |
- Keep API keys secure
|
| 202 |
-
-
|
| 203 |
-
-
|
| 204 |
- Monitor access logs
|
| 205 |
|
| 206 |
-
### Performance
|
| 207 |
-
|
| 208 |
-
-
|
| 209 |
-
-
|
| 210 |
-
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 211 |
|
| 212 |
-
### Reliability
|
| 213 |
-
- Implement retry logic
|
| 214 |
-
- Handle API errors gracefully
|
| 215 |
-
- Monitor system health
|
| 216 |
- Regular backups
|
|
|
|
|
|
|
|
|
|
|
|
|
| 217 |
|
| 218 |
## Updates and Maintenance
|
| 219 |
|
| 220 |
-
###
|
| 221 |
-
|
| 222 |
-
-
|
| 223 |
-
-
|
| 224 |
-
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 225 |
|
| 226 |
-
|
| 227 |
-
- Regular data backups
|
| 228 |
-
- Document recovery procedures
|
| 229 |
-
- Test backup restoration
|
| 230 |
-
- Monitor backup status
|
| 231 |
|
| 232 |
-
|
| 233 |
|
| 234 |
-
For additional support:
|
| 235 |
- Email: support@vbot.com
|
| 236 |
- Documentation: https://vbot.com/docs
|
| 237 |
-
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
# vBot User Manual
|
| 2 |
|
| 3 |
+
## Introduction
|
| 4 |
|
| 5 |
+
Welcome to the vBot User Manual. This guide will help you understand and use the vBot system effectively. vBot is a distributed call analysis system where the central server handles transcription and analysis, while you maintain your own infrastructure and receive results via webhooks.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6 |
|
| 7 |
+
## Getting Started
|
| 8 |
|
| 9 |
+
### 1. System Requirements
|
| 10 |
|
| 11 |
+
Your infrastructure needs:
|
| 12 |
+
- Asterisk PBX server
|
| 13 |
+
- Web server (Apache/Nginx)
|
| 14 |
+
- MySQL database
|
| 15 |
+
- SSL certificate for secure webhooks
|
|
|
|
|
|
|
| 16 |
|
| 17 |
+
### 2. Initial Setup
|
| 18 |
+
|
| 19 |
+
1. Contact vBot support to create your account
|
| 20 |
+
2. Receive your API key
|
| 21 |
+
3. Set up your infrastructure:
|
| 22 |
+
- Configure Asterisk
|
| 23 |
+
- Set up web server
|
| 24 |
+
- Create database
|
| 25 |
+
- Deploy webhook handler
|
| 26 |
+
|
| 27 |
+
### 3. Accessing Your Account
|
| 28 |
|
| 29 |
+
1. Log in to the vBot admin interface:
|
| 30 |
+
- URL: `https://vbot-server.com/admin`
|
| 31 |
+
- Use your credentials
|
|
|
|
| 32 |
|
| 33 |
+
2. View your account details:
|
| 34 |
+
- Company information
|
| 35 |
+
- API key
|
| 36 |
+
- Usage statistics
|
|
|
|
| 37 |
|
| 38 |
## Admin Interface
|
| 39 |
|
| 40 |
+
### 1. Dashboard
|
|
|
|
|
|
|
|
|
|
| 41 |
|
| 42 |
+
The dashboard shows:
|
| 43 |
+
- Total calls processed
|
|
|
|
|
|
|
| 44 |
- Recent activity
|
| 45 |
+
- System health
|
| 46 |
+
- Usage statistics
|
| 47 |
|
| 48 |
+
### 2. Customer Management
|
|
|
|
|
|
|
|
|
|
|
|
|
| 49 |
|
| 50 |
+
#### View Customers
|
| 51 |
+
- List all customers
|
| 52 |
+
- View customer details
|
| 53 |
+
- Check customer status
|
| 54 |
|
| 55 |
+
#### Add Customer
|
| 56 |
+
1. Click "Add Customer"
|
| 57 |
+
2. Fill in details:
|
| 58 |
- Name
|
| 59 |
- Company Name
|
| 60 |
- Email
|
| 61 |
+
3. Save customer
|
| 62 |
+
4. Copy API key
|
| 63 |
|
| 64 |
+
#### Edit Customer
|
| 65 |
+
1. Select customer
|
| 66 |
+
2. Click "Edit"
|
| 67 |
+
3. Update details
|
| 68 |
+
4. Save changes
|
| 69 |
|
| 70 |
+
#### Delete Customer
|
| 71 |
+
1. Select customer
|
| 72 |
+
2. Click "Delete"
|
| 73 |
+
3. Confirm deletion
|
| 74 |
|
| 75 |
+
### 3. System Settings
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 76 |
|
| 77 |
+
#### API Configuration
|
| 78 |
+
- View API key
|
| 79 |
+
- Regenerate API key
|
| 80 |
+
- Set webhook URL
|
| 81 |
+
- Configure webhook secret
|
| 82 |
|
| 83 |
+
#### Security Settings
|
| 84 |
+
- Change password
|
| 85 |
+
- Enable 2FA
|
| 86 |
+
- Set session timeout
|
|
|
|
|
|
|
|
|
|
|
|
|
| 87 |
|
| 88 |
+
## API Usage
|
|
|
|
|
|
|
|
|
|
|
|
|
| 89 |
|
| 90 |
+
### 1. Process a Call
|
|
|
|
|
|
|
|
|
|
|
|
|
| 91 |
|
|
|
|
| 92 |
```bash
|
| 93 |
+
curl -X POST https://vbot-server.com/api/process-call \
|
| 94 |
+
-H "X-API-Key: your_api_key" \
|
| 95 |
+
-H "Content-Type: multipart/form-data" \
|
| 96 |
+
-F "file=@/path/to/call.wav" \
|
| 97 |
+
-H "caller_number=${CALLER}" \
|
| 98 |
+
-H "called_number=${CALLED}"
|
|
|
|
|
|
|
| 99 |
```
|
| 100 |
|
| 101 |
+
### 2. Receive Webhook Data
|
| 102 |
|
| 103 |
+
Your webhook endpoint receives:
|
| 104 |
```json
|
| 105 |
{
|
| 106 |
+
"call_id": "uuid",
|
| 107 |
+
"caller_number": "+1234567890",
|
| 108 |
+
"called_number": "+0987654321",
|
| 109 |
+
"transcription": "Call transcript...",
|
| 110 |
+
"summary": "Call summary...",
|
| 111 |
+
"sentiment": "positive",
|
| 112 |
+
"keywords": "keyword1, keyword2",
|
| 113 |
+
"timestamp": "2024-03-14T12:00:00Z",
|
| 114 |
+
"customer_id": 123
|
| 115 |
}
|
| 116 |
```
|
| 117 |
|
| 118 |
+
### 3. Rate Limits
|
| 119 |
+
|
| 120 |
+
- 100 API requests per minute
|
| 121 |
+
- 3 webhook retry attempts
|
| 122 |
+
- 10 concurrent calls
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 123 |
|
| 124 |
## Troubleshooting
|
| 125 |
|
| 126 |
+
### 1. Common Issues
|
| 127 |
|
| 128 |
+
#### Webhook Failures
|
| 129 |
+
1. Check webhook URL
|
| 130 |
+
2. Verify SSL certificate
|
| 131 |
+
3. Check webhook logs
|
| 132 |
+
4. Test webhook endpoint
|
| 133 |
|
| 134 |
+
#### API Errors
|
| 135 |
+
1. Verify API key
|
| 136 |
+
2. Check request format
|
| 137 |
+
3. Review error messages
|
| 138 |
+
4. Check rate limits
|
| 139 |
|
| 140 |
+
#### Database Issues
|
| 141 |
+
1. Test database connection
|
| 142 |
+
2. Check database logs
|
| 143 |
+
3. Verify permissions
|
| 144 |
+
4. Monitor disk space
|
| 145 |
|
| 146 |
+
### 2. Debug Tools
|
| 147 |
|
| 148 |
+
#### Log Files
|
| 149 |
+
```bash
|
| 150 |
+
# Webhook logs
|
| 151 |
+
tail -f /var/log/apache2/vbot-access.log
|
|
|
|
| 152 |
|
| 153 |
+
# Database logs
|
| 154 |
+
tail -f /var/log/mysql/error.log
|
| 155 |
+
|
| 156 |
+
# Asterisk logs
|
| 157 |
+
tail -f /var/log/asterisk/messages
|
| 158 |
```
|
| 159 |
|
| 160 |
+
#### Health Checks
|
| 161 |
+
```bash
|
| 162 |
+
# Check webhook endpoint
|
| 163 |
+
curl -X POST https://your-domain.com/vbot-webhook/webhook.php \
|
| 164 |
+
-H "Content-Type: application/json" \
|
| 165 |
+
-d '{"test": true}'
|
| 166 |
+
|
| 167 |
+
# Check database
|
| 168 |
+
mysql -u vbot_user -p vbot_calls
|
| 169 |
+
|
| 170 |
+
# Check Asterisk
|
| 171 |
+
sudo asterisk -rx "core show version"
|
| 172 |
+
```
|
| 173 |
|
| 174 |
## Best Practices
|
| 175 |
|
| 176 |
+
### 1. Security
|
| 177 |
+
|
| 178 |
+
- Use strong passwords
|
| 179 |
- Keep API keys secure
|
| 180 |
+
- Enable HTTPS
|
| 181 |
+
- Regular security updates
|
| 182 |
- Monitor access logs
|
| 183 |
|
| 184 |
+
### 2. Performance
|
| 185 |
+
|
| 186 |
+
- Monitor system resources
|
| 187 |
+
- Regular maintenance
|
| 188 |
+
- Optimize database
|
| 189 |
+
- Clean old recordings
|
| 190 |
+
- Monitor disk space
|
| 191 |
+
|
| 192 |
+
### 3. Reliability
|
| 193 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 194 |
- Regular backups
|
| 195 |
+
- Monitor system health
|
| 196 |
+
- Test failover
|
| 197 |
+
- Keep systems updated
|
| 198 |
+
- Document procedures
|
| 199 |
|
| 200 |
## Updates and Maintenance
|
| 201 |
|
| 202 |
+
### 1. Regular Tasks
|
| 203 |
+
|
| 204 |
+
- Update system packages
|
| 205 |
+
- Rotate logs
|
| 206 |
+
- Backup database
|
| 207 |
+
- Clean old recordings
|
| 208 |
+
- Monitor disk space
|
| 209 |
+
|
| 210 |
+
### 2. Backup Strategy
|
| 211 |
+
|
| 212 |
+
```bash
|
| 213 |
+
# Database backup
|
| 214 |
+
mysqldump -u vbot_user -p vbot_calls > backup.sql
|
| 215 |
+
|
| 216 |
+
# Configuration backup
|
| 217 |
+
tar -czf config_backup.tar.gz /etc/asterisk/
|
| 218 |
+
```
|
| 219 |
+
|
| 220 |
+
### 3. Update Process
|
| 221 |
+
|
| 222 |
+
```bash
|
| 223 |
+
# Update webhook handler
|
| 224 |
+
cd /var/www/html/vbot-webhook
|
| 225 |
+
git pull
|
| 226 |
+
|
| 227 |
+
# Update Asterisk
|
| 228 |
+
sudo apt update
|
| 229 |
+
sudo apt upgrade
|
| 230 |
+
```
|
| 231 |
|
| 232 |
+
## Support
|
|
|
|
|
|
|
|
|
|
|
|
|
| 233 |
|
| 234 |
+
### 1. Getting Help
|
| 235 |
|
|
|
|
| 236 |
- Email: support@vbot.com
|
| 237 |
- Documentation: https://vbot.com/docs
|
| 238 |
+
- GitHub Issues: https://github.com/vbot/issues
|
| 239 |
+
|
| 240 |
+
### 2. Reporting Issues
|
| 241 |
+
|
| 242 |
+
When reporting issues:
|
| 243 |
+
1. Check documentation
|
| 244 |
+
2. Review logs
|
| 245 |
+
3. Gather error messages
|
| 246 |
+
4. Provide system info
|
| 247 |
+
5. Describe steps to reproduce
|
| 248 |
+
|
| 249 |
+
### 3. Feature Requests
|
| 250 |
+
|
| 251 |
+
To request features:
|
| 252 |
+
1. Check existing issues
|
| 253 |
+
2. Create detailed proposal
|
| 254 |
+
3. Provide use cases
|
| 255 |
+
4. Suggest implementation
|
| 256 |
+
5. Submit request
|
| 257 |
+
|
| 258 |
+
## Glossary
|
| 259 |
+
|
| 260 |
+
- **API Key**: Unique identifier for API access
|
| 261 |
+
- **Webhook**: URL endpoint for receiving data
|
| 262 |
+
- **Transcription**: Text version of call audio
|
| 263 |
+
- **Sentiment**: Emotional tone of call
|
| 264 |
+
- **Keywords**: Important terms from call
|
| 265 |
+
- **Asterisk**: Open-source PBX system
|
| 266 |
+
- **PBX**: Private Branch Exchange
|
| 267 |
+
- **SSL**: Secure Sockets Layer
|
| 268 |
+
- **HTTPS**: Secure HTTP protocol
|
| 269 |
+
- **MySQL**: Database system
|
| 270 |
+
- **Apache**: Web server
|
| 271 |
+
- **Nginx**: Web server
|
| 272 |
+
- **AGI**: Asterisk Gateway Interface
|
| 273 |
+
- **SIP**: Session Initiation Protocol
|
| 274 |
+
- **RTP**: Real-time Transport Protocol
|
app/models.py
CHANGED
|
@@ -1,6 +1,7 @@
|
|
| 1 |
from sqlalchemy import Column, Integer, String, DateTime, ForeignKey, Boolean, create_engine, Text
|
| 2 |
from sqlalchemy.ext.declarative import declarative_base
|
| 3 |
from sqlalchemy.orm import relationship, sessionmaker
|
|
|
|
| 4 |
from datetime import datetime
|
| 5 |
import requests
|
| 6 |
from typing import Optional, List, Dict
|
|
@@ -18,10 +19,14 @@ class Customer(Base):
|
|
| 18 |
name = Column(String(100), nullable=False)
|
| 19 |
company_name = Column(String(100), nullable=False)
|
| 20 |
email = Column(String(100), unique=True, nullable=False)
|
| 21 |
-
api_key = Column(String(
|
|
|
|
| 22 |
is_active = Column(Boolean, default=True)
|
| 23 |
-
created_at = Column(DateTime,
|
| 24 |
-
updated_at = Column(DateTime
|
|
|
|
|
|
|
|
|
|
| 25 |
|
| 26 |
def get_call_records(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> List[Dict]:
|
| 27 |
"""Get call records via API"""
|
|
|
|
| 1 |
from sqlalchemy import Column, Integer, String, DateTime, ForeignKey, Boolean, create_engine, Text
|
| 2 |
from sqlalchemy.ext.declarative import declarative_base
|
| 3 |
from sqlalchemy.orm import relationship, sessionmaker
|
| 4 |
+
from sqlalchemy.sql import func
|
| 5 |
from datetime import datetime
|
| 6 |
import requests
|
| 7 |
from typing import Optional, List, Dict
|
|
|
|
| 19 |
name = Column(String(100), nullable=False)
|
| 20 |
company_name = Column(String(100), nullable=False)
|
| 21 |
email = Column(String(100), unique=True, nullable=False)
|
| 22 |
+
api_key = Column(String(64), unique=True, nullable=False)
|
| 23 |
+
webhook_url = Column(String(255), nullable=True) # URL where call results will be sent
|
| 24 |
is_active = Column(Boolean, default=True)
|
| 25 |
+
created_at = Column(DateTime(timezone=True), server_default=func.now())
|
| 26 |
+
updated_at = Column(DateTime(timezone=True), onupdate=func.now())
|
| 27 |
+
|
| 28 |
+
def __repr__(self):
|
| 29 |
+
return f"<Customer {self.name}>"
|
| 30 |
|
| 31 |
def get_call_records(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> List[Dict]:
|
| 32 |
"""Get call records via API"""
|