Ajit Panday commited on
Commit
36a486d
·
1 Parent(s): 3a6a328

Update documentation to reflect distributed architecture and API-based approach

Browse files
Files changed (5) hide show
  1. API_DOCS.md +256 -0
  2. README.md +172 -144
  3. SETUP_GUIDE.md +244 -350
  4. USER_MANUAL.md +210 -173
  5. 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 an intelligent call analysis system that processes, transcribes, and analyzes phone calls using AI. It provides real-time insights, sentiment analysis, and call summaries through a modern API-based architecture.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
15
 
16
  ## Features
17
 
18
- - Real-time call processing and analysis
19
- - AI-powered transcription and summarization
 
 
20
  - Sentiment analysis and keyword extraction
21
  - Modern admin interface for customer management
22
- - Secure API-based architecture
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
- - Customer's web server (for webhook handling)
 
 
 
 
 
 
 
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 your first customer:
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
- - Provide webhook URL where call results will be sent
80
  - Optional: Set webhook secret for additional security
81
 
82
- ## Asterisk Configuration
83
-
84
- 1. Configure Asterisk dialplan:
85
- ```ini
86
- [from-internal]
87
- exten => _X.,1,Answer()
88
- same => n,Record(/tmp/calls/${UNIQUEID}.wav,0,0)
89
- same => n,Set(CALL_ID=${UNIQUEID})
90
- same => n,Set(CALLER=${CALLERID(num)})
91
- same => n,Set(CALLED=${EXTEN})
92
- same => n,AGI(agi://localhost:4573/process_call)
93
- same => n,Hangup()
94
- ```
95
-
96
- 2. Configure AGI settings:
97
- ```ini
98
- [agi]
99
- enabled=yes
100
- port=4573
101
- bindaddr=0.0.0.0
102
- ```
103
-
104
- 3. Test the configuration:
105
- ```bash
106
- asterisk -rx "dialplan show from-internal"
107
- ```
108
-
109
- ## Customer Integration
110
-
111
- ### Webhook Setup
112
-
113
- 1. Download the webhook handler package:
114
- ```bash
115
- git clone https://huggingface.co/spaces/iajitpanday/vBot/customer_webhook
116
- ```
117
-
118
- 2. Deploy to your web server:
119
- ```bash
120
- cp -r customer_webhook/* /var/www/html/vbot-webhook/
121
- ```
122
-
123
- 3. Create database:
124
- ```sql
125
- CREATE DATABASE vbot_calls;
126
- USE vbot_calls;
127
-
128
- CREATE TABLE call_records (
129
- id VARCHAR(36) PRIMARY KEY,
130
- customer_id INT NOT NULL,
131
- caller_number VARCHAR(20) NOT NULL,
132
- called_number VARCHAR(20) NOT NULL,
133
- transcription TEXT,
134
- summary TEXT,
135
- sentiment VARCHAR(50),
136
- keywords TEXT,
137
- created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
138
- updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
139
- );
140
- ```
141
-
142
- 4. Configure webhook handler:
143
- - Copy `config/config.example.php` to `config/config.php`
144
- - Update database credentials and API key
145
-
146
- ### API Usage
147
-
148
- 1. Process a call:
149
- ```bash
150
- curl -X POST https://your-domain.com/api/process-call \
151
- -H "X-API-Key: your_api_key" \
152
- -H "Content-Type: multipart/form-data" \
153
- -F "file=@/path/to/call.wav" \
154
- -H "caller_number=+1234567890" \
155
- -H "called_number=+0987654321"
156
- ```
157
-
158
- 2. Response format:
159
- ```json
160
- {
161
- "success": true,
162
- "message": "Call processed successfully",
163
- "call_id": "uuid",
164
- "transcription": "Call transcript...",
165
- "summary": "Call summary...",
166
- "sentiment": "positive",
167
- "keywords": "keyword1, keyword2"
168
- }
169
- ```
170
-
171
- 3. Webhook payload:
172
- ```json
173
- {
174
- "call_id": "uuid",
175
- "caller_number": "+1234567890",
176
- "called_number": "+0987654321",
177
- "transcription": "Call transcript...",
178
- "summary": "Call summary...",
179
- "sentiment": "positive",
180
- "keywords": "keyword1, keyword2",
181
- "timestamp": "2024-03-14T12:00:00Z",
182
- "customer_id": 123
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 stored securely
201
- - Customer data isolation
202
-
203
- ## Monitoring and Maintenance
204
-
205
- 1. Logs:
206
- - Application logs: `logs/app.log`
207
- - Error logs: `logs/error.log`
208
- - Access logs: `logs/access.log`
209
-
210
- 2. Health Checks:
211
- - API endpoint: `/health`
212
- - Database status
213
- - Service status
214
-
215
- 3. Backup:
216
- - Regular database backups
217
- - Configuration backups
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 database credentials
229
  - Verify API key
230
- - Test webhook endpoint
231
- - Review error logs
 
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
- This guide provides detailed instructions for setting up and deploying the vBot system.
4
 
5
- ## Step 1: Deploy to Hugging Face Spaces
6
 
7
- 1. **Create a Hugging Face Account**
8
- - Go to [Hugging Face](https://huggingface.co)
9
- - Sign up for a free account
10
- - Create a new Space
11
 
12
- 2. **Deploy the Space**
13
- - Click "Use this Space"
14
- - Choose "Docker" as the SDK
15
- - Select "FastAPI" as the framework
16
- - Deploy the space
17
 
18
- 3. **Configure Environment Variables**
 
 
 
 
 
 
 
 
19
  ```bash
20
- # Generate a secure JWT secret
21
- python3 -c "import secrets; print(secrets.token_urlsafe(32))"
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
- ## Step 2: Set Up Main Database
31
-
32
- 1. **Choose a Database Provider**
33
- - [PlanetScale](https://planetscale.com/) (Recommended)
34
- - [Railway](https://railway.app/)
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
- ## Step 4: Customer Setup
 
 
 
 
 
64
 
65
- 1. **Configure Asterisk**
66
- - Install Asterisk if not already installed
67
- - Configure your dialplan
68
- - Set up call recording
69
 
70
- 2. **Update Asterisk Configuration**
71
- - Add the vBot dialplan configuration
72
- - Configure the API endpoint
73
- - Set up the API key
74
 
75
- 3. **Test Integration**
76
- - Make a test call
77
- - Verify call recording
78
- - Check API responses
79
 
80
- ## Step 5: Testing
81
 
82
- 1. **Test API Connection**
83
  ```bash
84
- curl -X POST "https://your-space.huggingface.space/api/v1/token" \
85
- -H "Content-Type: application/x-www-form-urlencoded" \
86
- -d "username=admin&password=your-password"
87
  ```
88
 
89
- 2. **Test Call Processing**
90
- - Make a test call
91
- - Check the logs for processing status
92
- - Verify transcription and analysis
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
- 2. **Solutions**
145
- - Check environment variables
146
- - Verify database credentials
147
- - Monitor system logs
148
- - Test API endpoints
149
 
150
- 3. **Support**
151
- - Check documentation
152
- - Review logs
153
- - Contact support if needed
154
 
155
- ## Best Practices
 
 
 
 
156
 
157
- 1. **Security**
158
- - Use strong passwords
159
- - Rotate API keys regularly
160
- - Monitor access logs
161
- - Keep systems updated
 
 
 
 
 
 
162
 
163
- 2. **Performance**
164
- - Monitor resource usage
165
- - Optimize database queries
166
- - Cache frequently accessed data
167
- - Scale resources as needed
 
 
 
 
 
 
 
 
 
 
 
 
168
 
169
- 3. **Reliability**
170
- - Regular backups
171
- - Monitor system health
172
- - Test failover procedures
173
- - Document procedures
174
 
175
- ## Database Schema Setup
 
 
 
176
 
177
- ### 1. Main Database (vbot_main)
178
 
179
- 1. **Create Database**
180
- ```sql
181
- CREATE DATABASE vbot_main;
182
- USE vbot_main;
183
  ```
184
 
185
- 2. **Create Customers Table**
186
- ```sql
187
- CREATE TABLE customers (
188
- id INT AUTO_INCREMENT PRIMARY KEY,
189
- name VARCHAR(100) NOT NULL,
190
- company_name VARCHAR(100) NOT NULL,
191
- email VARCHAR(100) UNIQUE NOT NULL,
192
- api_key VARCHAR(64) UNIQUE NOT NULL,
193
- is_active BOOLEAN DEFAULT TRUE,
194
- created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
195
- updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
196
- -- Database credentials for customer's own database
197
- db_host VARCHAR(255),
198
- db_port INT,
199
- db_name VARCHAR(100),
200
- db_user VARCHAR(100),
201
- db_password VARCHAR(255)
202
- );
203
  ```
204
 
205
- 3. **Create Indexes**
206
- ```sql
207
- CREATE INDEX idx_api_key ON customers(api_key);
208
- CREATE INDEX idx_email ON customers(email);
209
- CREATE INDEX idx_is_active ON customers(is_active);
210
  ```
211
 
212
- ### 2. Customer Database
213
 
214
- 1. **Create Database**
215
- ```sql
216
- CREATE DATABASE customer_db_name;
217
- USE customer_db_name;
218
  ```
219
 
220
- 2. **Create Call Records Table**
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(20),
231
  keywords TEXT,
232
- created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
233
- updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
234
- FOREIGN KEY (customer_id) REFERENCES customers(id)
235
  );
236
  ```
237
 
238
- 3. **Create Indexes**
239
  ```sql
240
- CREATE INDEX idx_customer_id ON call_records(customer_id);
241
- CREATE INDEX idx_created_at ON call_records(created_at);
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
- 2. **Customer Database User**
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
- ### 4. Database Connection Testing
 
 
 
 
265
 
266
- 1. **Test Main Database Connection**
267
  ```bash
268
- # Test connection
269
- mysql -h your-main-db-host -u vbot_admin -p vbot_main
270
-
271
- # Test queries
272
- USE vbot_main;
273
- SELECT * FROM customers;
 
 
 
 
 
 
 
 
274
  ```
275
 
276
- 2. **Test Customer Database Connection**
277
  ```bash
278
- # Test connection
279
- mysql -h customer-db-host -u customer_user -p customer_db_name
280
-
281
- # Test queries
282
- USE customer_db_name;
283
- SELECT * FROM call_records;
284
  ```
285
 
286
- ### 5. Database Backup Setup
287
 
288
- 1. **Main Database Backup**
289
  ```bash
290
- # Create backup script
291
- cat > backup_main.sh << 'EOF'
292
- #!/bin/bash
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. **Customer Database Backup**
312
  ```bash
313
- # Create backup script
314
- cat > backup_customer.sh << 'EOF'
315
- #!/bin/bash
316
- BACKUP_DIR="/path/to/backups"
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
- ### 6. Database Monitoring
335
-
336
- 1. **Set Up Monitoring Queries**
337
  ```sql
338
- -- Check database size
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
- 2. **Set Up Alerts**
 
 
356
  ```bash
357
- # Create monitoring script
358
- cat > monitor_db.sh << 'EOF'
359
- #!/bin/bash
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
- ## Network Requirements
 
 
 
380
 
381
- ### Required Ports
 
 
 
382
 
383
- 1. **Customer Server to Hugging Face Space**
384
- - Port 443 (HTTPS) - For API communication only
385
- - No direct database connection needed
 
 
386
 
387
- 2. **Asterisk Server Requirements**
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
- ### Network Configuration
 
 
 
 
 
 
 
 
 
 
393
 
394
- 1. **Firewall Rules**
395
  ```bash
396
- # Allow outbound HTTPS to Hugging Face
397
- sudo ufw allow out 443/tcp
398
 
399
- # Allow SIP and RTP ports
400
- sudo ufw allow 5060/udp
401
- sudo ufw allow 10000:20000/udp
402
  ```
403
 
404
- 2. **Security Groups (if using cloud providers)**
405
- - Allow inbound HTTPS (443) from Hugging Face IPs
406
- - Allow inbound SIP (5060) and RTP (10000-20000) from VoIP providers
 
 
 
 
 
 
 
 
 
407
 
408
- 3. **Network Testing**
409
  ```bash
410
- # Test HTTPS connection to Hugging Face
411
- curl -v https://your-huggingface-space-url
412
 
413
- # Test API endpoints
414
- curl -X GET "https://your-huggingface-space-url/api/v1/health" \
415
- -H "api-key: YOUR_API_KEY"
 
 
 
 
 
 
416
 
417
- # Test SIP connectivity
418
- sipshowpeers
 
419
  ```
420
 
421
- ### VPN Requirements (Optional)
422
 
423
- 1. **Site-to-Site VPN**
424
- - Recommended for secure database access
425
- - Configure VPN between customer network and database network
426
- - Use VPN for all database traffic
 
427
 
428
- 2. **VPN Configuration**
429
  ```bash
430
- # Example OpenVPN configuration
431
- client
432
- dev tun
433
- proto udp
434
- remote your-vpn-server 1194
435
- resolv-retry infinite
436
- nobind
437
- persist-key
438
- persist-tun
439
- remote-cert-tls server
440
- auth-user-pass auth.txt
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
- This manual provides comprehensive documentation for using the vBot system.
4
 
5
- ## Table of Contents
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
- ## Introduction
14
 
15
- vBot is an intelligent call analysis system that provides real-time transcription, sentiment analysis, and call summaries. The system is designed to be easy to use while providing powerful features for call center management and analysis.
16
 
17
- ### Key Features
18
- - Real-time call transcription
19
- - Sentiment analysis
20
- - Call summaries
21
- - Modern admin interface
22
- - Secure API access
23
- - Customer management
24
 
25
- ## Getting Started
 
 
 
 
 
 
 
 
 
 
26
 
27
- ### Prerequisites
28
- - A Hugging Face account
29
- - Access to the vBot system
30
- - Admin credentials
31
 
32
- ### Initial Setup
33
- 1. Log in to the admin interface
34
- 2. Create your first customer
35
- 3. Configure your Asterisk system
36
- 4. Test the integration
37
 
38
  ## Admin Interface
39
 
40
- ### Login
41
- 1. Navigate to the admin interface
42
- 2. Enter your admin credentials
43
- 3. Click "Login"
44
 
45
- ### Dashboard
46
- The dashboard provides an overview of:
47
- - Total customers
48
- - Active customers
49
  - Recent activity
50
- - System status
 
51
 
52
- ### Navigation
53
- - **Customers**: Manage customer accounts
54
- - **Settings**: Configure system settings
55
- - **Logs**: View system logs
56
- - **Help**: Access documentation
57
 
58
- ## Customer Management
 
 
 
59
 
60
- ### Adding Customers
61
- 1. Click "Add New Customer"
62
- 2. Fill in customer details:
63
  - Name
64
  - Company Name
65
  - Email
66
- 3. Click "Save"
67
- 4. Copy the generated API key
68
 
69
- ### Managing Customers
70
- - View customer list
71
- - Edit customer details
72
- - Enable/disable customers
73
- - View customer usage
74
 
75
- ### Customer Settings
76
- - API key management
77
- - Usage limits
78
- - Feature access
79
 
80
- ## API Usage
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
- ### Customer API Endpoints
 
 
 
 
91
 
92
- #### Process Call
93
- ```bash
94
- curl -X POST "https://your-space.huggingface.space/api/v1/process-call" \
95
- -H "api-key: YOUR_API_KEY" \
96
- -H "caller-number: +1234567890" \
97
- -H "called-number: +0987654321" \
98
- -F "file=@call.wav"
99
- ```
100
 
101
- #### Get Call Records
102
- ```bash
103
- curl -X GET "https://your-space.huggingface.space/api/v1/calls" \
104
- -H "api-key: YOUR_API_KEY"
105
- ```
106
 
107
- #### Get Call Details
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 GET "https://your-space.huggingface.space/api/v1/calls/search" \
116
- -H "api-key: YOUR_API_KEY" \
117
- -H "Content-Type: application/json" \
118
- -d '{
119
- "start_date": "2024-01-01",
120
- "end_date": "2024-01-31",
121
- "caller_number": "+1234567890"
122
- }'
123
  ```
124
 
125
- ### Response Formats
126
 
127
- #### Call Processing Response
128
  ```json
129
  {
130
- "id": "123",
131
- "caller_number": "+1234567890",
132
- "called_number": "+0987654321",
133
- "transcription": "Call transcript...",
134
- "summary": "Call summary...",
135
- "sentiment": "positive",
136
- "timestamp": "2024-01-01T12:00:00Z"
 
 
137
  }
138
  ```
139
 
140
- #### Call Records Response
141
- ```json
142
- {
143
- "calls": [
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
- #### API Authentication
164
- - Verify API key is correct
165
- - Check API key permissions
166
- - Ensure HTTPS is used
 
167
 
168
- #### Call Processing
169
- - Verify audio file format
170
- - Check file size limits
171
- - Monitor processing status
 
172
 
173
- #### System Status
174
- - Check system logs
175
- - Monitor resource usage
176
- - Verify database connection
 
177
 
178
- ### Error Messages
179
 
180
- #### Authentication Errors
181
- ```
182
- 401 Unauthorized: Invalid API key
183
- 403 Forbidden: Insufficient permissions
184
- ```
185
 
186
- #### Processing Errors
187
- ```
188
- 400 Bad Request: Invalid file format
189
- 413 Payload Too Large: File size exceeds limit
190
- 500 Internal Server Error: Processing failed
191
  ```
192
 
193
- ### Support
194
- - Check documentation
195
- - Review error logs
196
- - Contact system administrator
 
 
 
 
 
 
 
 
 
197
 
198
  ## Best Practices
199
 
200
- ### Security
 
 
201
  - Keep API keys secure
202
- - Use HTTPS for all requests
203
- - Rotate API keys regularly
204
  - Monitor access logs
205
 
206
- ### Performance
207
- - Optimize audio file size
208
- - Use appropriate sampling rates
209
- - Monitor API usage limits
210
- - Cache frequently accessed data
 
 
 
 
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
- ### System Updates
221
- - Monitor for new features
222
- - Review changelog
223
- - Test updates in staging
224
- - Plan maintenance windows
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
225
 
226
- ### Backup and Recovery
227
- - Regular data backups
228
- - Document recovery procedures
229
- - Test backup restoration
230
- - Monitor backup status
231
 
232
- ## Contact Support
233
 
234
- For additional support:
235
  - Email: support@vbot.com
236
  - Documentation: https://vbot.com/docs
237
- - Community: https://vbot.com/community
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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(100), unique=True, nullable=False)
 
22
  is_active = Column(Boolean, default=True)
23
- created_at = Column(DateTime, default=datetime.utcnow)
24
- updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
 
 
 
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"""