# Voice Transcription — System Workflow & Documentation

## Overview

This system receives audio files from external CRM/PBX sources, sends them to the Callmetrik API for speech analysis, and forwards the analysis results to the appropriate internal server based on the audio source.

---

## Components

| File | Role |
|---|---|
| `api.php` | Entry point — receives audio file info, downloads, converts if needed, uploads to Callmetrik |
| `voiceTranscriptionWebhook.php` | Webhook — receives Callmetrik analysis results and forwards to internal servers |
| `db_connect.php` | MySQL connection to `voiceTranscriptionDB` |
| `WAV/` | Stores all WAV audio files (converted or original) |
| `json_logs/` | Stores raw JSON responses from Callmetrik |

---

## Database

**Database:** `voiceTranscriptionDB`
**Table:** `voice_records`

| Column | Type | Description |
|---|---|---|
| `id` | INT AUTO_INCREMENT | Primary key |
| `audioID` | VARCHAR(100) | ID of the audio file from the source system |
| `audioSource` | ENUM | `PBXdemo`, `CCDdemo`, `OmniCoredemo` |
| `voicefileURL` | TEXT | Original download URL of the audio file |
| `wavFile` | VARCHAR(255) | Filename of the saved WAV file in `WAV/` |
| `json_log` | VARCHAR(255) | Filename of the Callmetrik result JSON in `json_logs/` |
| `json_url` | TEXT | Full HTTPS URL to the saved JSON log |
| `forward_response` | TEXT | Raw response from the internal `analysis_json.php` |
| `status` | ENUM | `pending` → `completed` / `failed` |
| `created_at` | DATETIME | Record creation timestamp |
| `updated_at` | DATETIME | Auto-updated on any change |

---

## Workflow

### Phase 1 — Audio Submission (`api.php`)

```
External Source (CRM/PBX)
        │
        │  POST https://projects.astcrm.com/voiceTranscription/api.php
        │  Body: audioID, voicefileURL, audioSource
        ▼
[1] Validate input
        │
        ▼
[2] Download audio file from voicefileURL
        │
        ├── .gsm file?
        │       └── Convert GSM → WAV using sox (8kHz, mono)
        │               └── Save to WAV/{audioID}_{timestamp}.wav
        │
        └── .wav file?
                └── Save directly to WAV/{audioID}_{timestamp}.wav
        │
        ▼
[3] Insert record into voice_records
        │  status = 'pending'
        ▼
[4] POST WAV file to Callmetrik API
        │  URL: https://api.callmetrik.com/v1.3/crm-callmetrik/upload-process/13
        │  Params: audioID, audioSource (mapped below)
        │  Auth: PDAI-API-Token header
        ▼
[5] Return Callmetrik response to caller
```

**audioSource mapping:**

| Incoming | Sent to Callmetrik |
|---|---|
| `PBXdemo` | `pbx` |
| `CCDdemo` | `ccd` |
| `OmniCoredemo` | `omnichannel` |

---

### Phase 2 — Result Webhook (`voiceTranscriptionWebhook.php`)

```
Callmetrik API
        │
        │  POST https://projects.astcrm.com/voiceTranscription/voiceTranscriptionWebhook.php
        │  Body: raw JSON (success or failure, e.g. NO_SPEECH_DETECTED)
        ▼
[1] Parse raw JSON body
        │  Extract audioID from results[] (regardless of success/failure)
        ▼
[2] Save JSON to json_logs/voice_{datetime}_{uniqid}.json
        │  Build full HTTPS URL: json_url
        ▼
[3] Look up voice_records by audioID
        │  Get: id, audioSource
        ▼
[4] Update voice_records
        │  json_log = filename
        │  json_url = full URL
        │  status   = 'completed'
        ▼
[5] Forward to internal server based on audioSource
        │
        ├── CCDdemo      → POST http://10.0.6.250/astVlogger/analysis_json.php
        ├── PBXdemo      → POST http://10.0.10.162/astVlogger/analysis_json.php
        └── OmniCoredemo → POST https://demo.astcrm.com/staging/omnicore/voiceTranscriptionWebhook.php
        │
        │  POST body: id={audioID}&json_url={json_url}
        ▼
[6] Save forward_response to voice_records
        ▼
[7] Return JSON response to Callmetrik
```

---

## Internal Forwarding Endpoints

Each internal `analysis_json.php` receives:

| POST Field | Value |
|---|---|
| `id` | `audioID` from the original submission |
| `json_url` | HTTPS URL to the full Callmetrik JSON result |

The internal script uses these to update its own database (e.g. `UPDATE voicefiles SET json_url=... WHERE id=...`).

---

## Error Scenarios

| Scenario | Behaviour |
|---|---|
| Missing POST params | `400 Bad Request` |
| Invalid audioSource | `400 Bad Request` |
| Audio download fails | `502`, temp file cleaned up |
| GSM conversion fails | `500`, sox output returned |
| Callmetrik unreachable | `502` |
| Callmetrik returns `success: false` (e.g. NO_SPEECH_DETECTED) | Still forwarded to internal server |
| No DB record found for audioID | JSON saved, forwarding skipped |

---

## Quick Reference — Test API

```bash
curl -X POST https://projects.astcrm.com/voiceTranscription/api.php \
  -d "audioID=123456" \
  -d "voicefileURL=https://example.com/call.wav" \
  -d "audioSource=PBXdemo"
```

## Quick Reference — Check DB

```sql
SELECT audioID, audioSource, wavFile, status, json_url, forward_response, created_at
FROM voiceTranscriptionDB.voice_records
ORDER BY created_at DESC
LIMIT 20;
```