{ "info": { "_postman_id": "echo-api-collection", "name": "Echo API", "description": "Communication Analysis API - Call Recordings & Text Conversations\n\nThis collection provides endpoints for:\n- Submitting call recordings for transcription and sentiment analysis\n- Submitting text conversations for sentiment analysis\n- Checking processing status\n- Retrieving transcripts and sentiment analysis\n\nAuthentication: API Key via X-API-Key header", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "Submit Recording", "event": [ { "listen": "test", "script": { "exec": [ "// Store recording UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('recording_uuid', jsonData.uuid);", " pm.test('Recording UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData.status).to.equal('pending');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"recording_url\": \"https://example.com/recordings/sample-call.mp3\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\",\n \"vehlo_account_id\": \"vehlo_acct_12345\",\n \"vehlo_location_id\": \"vehlo_loc_67890\",\n \"account_name\": \"Example Auto Shop\",\n \"location_name\": \"Downtown Location\",\n \"location_street\": \"123 Main St\",\n \"location_city\": \"City\",\n \"location_state\": \"State\",\n \"location_zip\": \"12345\",\n \"location_country\": \"USA\",\n \"tracking_number\": \"15555551234\",\n \"external_tracking_number_id\": \"tn_98765\",\n \"duration\": 180\n}" }, "url": { "raw": "{{app_url}}/api/v1/recordings", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings" ] }, "description": "Submit a call recording for transcription and sentiment analysis.\n\n**Required fields:**\n- `recording_url` - URL to MP3 file (can be local path or remote URL)\n- `external_account_id` - Your integrator's account identifier\n- `external_location_id` - Your integrator's location identifier\n\n**Optional Vehlo linking fields:**\n- `vehlo_account_id` - Vehlo centralized account ID (creates/links master account)\n- `vehlo_location_id` - Vehlo centralized location ID (creates/links master location)\n- `account_name` - Display name for account (used if creating new)\n- `location_name` - Display name for location (used if creating new)\n\n**Optional location address fields (parsed):**\n- `location_street` - Street address (e.g., \"123 Main St\")\n- `location_city` - City name\n- `location_state` - State/Province\n- `location_zip` - ZIP/Postal code\n- `location_country` - Country (defaults to \"USA\")\n\n**Other optional fields:**\n- `tracking_number` - Phone number (10 digits + country code)\n- `external_tracking_number_id` - Your tracking number ID\n- `duration` - Call duration in seconds\n\n**Response:**\n- `uuid` - Use this to check status\n- `status` - Will be 'pending'\n- `message` - Confirmation message\n- `vehlo_linking` - Present if master accounts/locations were linked (includes backfill status)" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"recording_url\": \"https://example.com/recordings/sample-call.mp3\",\n \"external_account_id\": \"account_12345\",\n \"tracking_number\": \"15555551234\",\n \"duration\": 180\n}" }, "url": { "raw": "{{app_url}}/api/v1/recordings", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Recording submitted successfully. Processing started.\",\n \"created_at\": \"2026-01-29T12:00:00Z\",\n \"vehlo_linking\": {\n \"account_linked\": true,\n \"location_linked\": true,\n \"backfill_status\": \"Historical recordings are being updated in the background\"\n }\n}" } ] }, { "name": "Submit Recording (Minimal)", "event": [ { "listen": "test", "script": { "exec": [ "// Store recording UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('recording_uuid', jsonData.uuid);", " pm.test('Recording UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData.status).to.equal('pending');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"recording_url\": \"https://example.com/recordings/sample-call.mp3\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/recordings", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings" ] }, "description": "**BARE MINIMUM REQUEST** - Submit a call recording with only the essentials.\n\n**Required fields:**\n- `recording_url` - URL to MP3 file (can be local path or remote URL)\n\n**What happens:**\n- Account and location are automatically set to \"Unassigned\"\n- Recording is processed and analyzed\n- Returns UUID for checking status and retrieving results\n\n**Use this when:**\n- You want to quickly test transcription\n- You don't need to track account/location\n- You just want a transcript and sentiment analysis\n\n**Next steps:**\n1. Use the returned UUID with \"Get Recording Status\" to check progress\n2. Once completed, use \"Get Transcript\" or \"Get Full Analysis\" to retrieve results" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"recording_url\": \"https://example.com/recordings/sample-call.mp3\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/recordings", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Recording submitted successfully. Processing started.\",\n \"created_at\": \"2026-01-29T12:00:00Z\"\n}" } ] }, { "name": "Get Recording Status", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status code is 200', function() {", " pm.response.to.have.status(200);", "});", "", "pm.test('Response has required fields', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", "});", "", "pm.test('Status is valid', function() {", " var jsonData = pm.response.json();", " var validStatuses = ['pending', 'processing', 'transcribed', 'completed', 'failed'];", " pm.expect(validStatuses).to.include(jsonData.status);", "});" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/recordings/{{recording_uuid}}", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings", "{{recording_uuid}}" ] }, "description": "Get the current status and results of a recording.\n\n**Statuses:**\n- `pending` - Waiting to be processed\n- `processing` - Downloading and transcribing\n- `transcribed` - Transcript complete, analyzing sentiment\n- `completed` - Fully processed with results\n- `failed` - Processing failed (check error_message)\n\n**Response includes:**\n- Basic recording info\n- Transcription details (if available)\n- Sentiment analysis (if completed)\n- Error message (if failed)" }, "response": [ { "name": "Completed Response", "originalRequest": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/recordings/{{recording_uuid}}", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings", "{{recording_uuid}}" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"completed\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\",\n \"tracking_number\": \"15555551234\",\n \"external_tracking_number_id\": \"tn_98765\",\n \"duration\": 180,\n \"created_at\": \"2026-01-29T12:00:00Z\",\n \"processing_started_at\": \"2026-01-29T12:00:05Z\",\n \"completed_at\": \"2026-01-29T12:02:30Z\",\n \"transcription\": {\n \"uuid\": \"trans-uuid-here\",\n \"status\": \"completed\",\n \"ai_model_used\": \"openai/whisper-large-v3\",\n \"processing_time_seconds\": 45\n },\n \"sentiment_analysis\": {\n \"uuid\": \"sentiment-uuid-here\",\n \"sentiment_score\": 75,\n \"sentiment_label\": \"positive\",\n \"keywords\": [\"appointment\", \"service\", \"satisfaction\"],\n \"summary\": \"Customer called to schedule a service appointment. They were satisfied with the scheduling process and confirmed their preferred time slot.\",\n \"metadata\": {\n \"call_purpose\": \"Schedule service appointment\",\n \"customer_emotion\": \"Satisfied and friendly\",\n \"resolution_status\": \"resolved\",\n \"action_items\": [\"Schedule appointment for next Tuesday at 2pm\"]\n },\n \"ai_model_used\": \"anthropic/claude-3.5-sonnet\"\n }\n}" }, { "name": "Processing Response", "originalRequest": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/recordings/{{recording_uuid}}", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings", "{{recording_uuid}}" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"processing\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\",\n \"tracking_number\": \"15555551234\",\n \"duration\": 180,\n \"created_at\": \"2026-01-29T12:00:00Z\",\n \"processing_started_at\": \"2026-01-29T12:00:05Z\",\n \"completed_at\": null\n}" } ] }, { "name": "Get Transcript", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status code is 200', function() {", " pm.response.to.have.status(200);", "});", "", "pm.test('Response has transcript', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('full_text');", " pm.expect(jsonData).to.have.property('ai_model_used');", "});" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/recordings/{{recording_uuid}}/transcript", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings", "{{recording_uuid}}", "transcript" ] }, "description": "Get the full transcript text.\n\n**Requirements:**\n- Recording must be in 'transcribed' or 'completed' status\n\n**Returns:**\n- `full_text` - Complete transcript\n- `ai_model_used` - Model that generated transcript\n- `processing_time_seconds` - Time taken to transcribe" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/recordings/{{recording_uuid}}/transcript", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings", "{{recording_uuid}}", "transcript" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"transcription_uuid\": \"trans-uuid-here\",\n \"full_text\": \"Hello, this is John calling about scheduling a service appointment. I'd like to bring my vehicle in next week if possible. Yes, Tuesday at 2pm works perfectly for me. Thank you so much for your help!\",\n \"ai_model_used\": \"openai/whisper-large-v3\",\n \"processing_time_seconds\": 45\n}" } ] }, { "name": "Get Sentiment Analysis", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status code is 200', function() {", " pm.response.to.have.status(200);", "});", "", "pm.test('Response has sentiment data', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('sentiment_score');", " pm.expect(jsonData).to.have.property('sentiment_label');", " pm.expect(jsonData).to.have.property('keywords');", "});", "", "pm.test('Sentiment score is valid', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData.sentiment_score).to.be.within(0, 100);", "});" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/recordings/{{recording_uuid}}/sentiment", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings", "{{recording_uuid}}", "sentiment" ] }, "description": "Get sentiment analysis results.\n\n**Requirements:**\n- Recording must be in 'completed' status\n\n**Returns:**\n- `sentiment_score` - 0-100 (0=negative, 50=neutral, 100=positive)\n- `sentiment_label` - 'positive', 'neutral', or 'negative'\n- `keywords` - Array of key topics\n- `summary` - 2-3 sentence call summary\n- `metadata` - Additional context (call purpose, emotion, resolution, actions)" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/recordings/{{recording_uuid}}/sentiment", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings", "{{recording_uuid}}", "sentiment" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"sentiment_uuid\": \"sentiment-uuid-here\",\n \"sentiment_score\": 75,\n \"sentiment_label\": \"positive\",\n \"keywords\": [\n \"appointment\",\n \"service\",\n \"scheduling\",\n \"Tuesday\",\n \"satisfaction\"\n ],\n \"summary\": \"Customer called to schedule a service appointment. They were satisfied with the scheduling process and confirmed their preferred time slot.\",\n \"metadata\": {\n \"call_purpose\": \"Schedule service appointment\",\n \"customer_emotion\": \"Satisfied and friendly\",\n \"resolution_status\": \"resolved\",\n \"action_items\": [\n \"Schedule appointment for next Tuesday at 2pm\",\n \"Send confirmation email to customer\"\n ]\n },\n \"ai_model_used\": \"anthropic/claude-3.5-sonnet\"\n}" } ] }, { "name": "Get Full Analysis", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status code is 200', function() {", " pm.response.to.have.status(200);", "});", "", "pm.test('Response has complete data', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData).to.have.property('transcript');", " pm.expect(jsonData).to.have.property('sentiment_analysis');", "});" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/recordings/{{recording_uuid}}/full", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings", "{{recording_uuid}}", "full" ] }, "description": "Get complete analysis in a single response.\n\n**Requirements:**\n- Recording must be in 'completed' status\n\n**Returns:**\n- Recording metadata\n- Full transcript text\n- Complete sentiment analysis\n- All in one convenient response" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/recordings/{{recording_uuid}}/full", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "recordings", "{{recording_uuid}}", "full" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"completed\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\",\n \"tracking_number\": \"15555551234\",\n \"external_tracking_number_id\": \"tn_98765\",\n \"duration\": 180,\n \"created_at\": \"2026-01-29T12:00:00Z\",\n \"completed_at\": \"2026-01-29T12:02:30Z\",\n \"transcript\": \"Hello, this is John calling about scheduling a service appointment. I'd like to bring my vehicle in next week if possible. Yes, Tuesday at 2pm works perfectly for me. Thank you so much for your help!\",\n \"sentiment_analysis\": {\n \"sentiment_score\": 75,\n \"sentiment_label\": \"positive\",\n \"keywords\": [\n \"appointment\",\n \"service\",\n \"scheduling\",\n \"Tuesday\",\n \"satisfaction\"\n ],\n \"summary\": \"Customer called to schedule a service appointment. They were satisfied with the scheduling process and confirmed their preferred time slot.\",\n \"metadata\": {\n \"call_purpose\": \"Schedule service appointment\",\n \"customer_emotion\": \"Satisfied and friendly\",\n \"resolution_status\": \"resolved\",\n \"action_items\": [\n \"Schedule appointment for next Tuesday at 2pm\",\n \"Send confirmation email to customer\"\n ]\n }\n }\n}" } ] }, { "name": "Submit Text Conversation", "event": [ { "listen": "test", "script": { "exec": [ "// Store conversation UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('conversation_uuid', jsonData.uuid);", " pm.test('Conversation UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData.status).to.equal('pending');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": \"Customer: Hi, I need to schedule a service appointment\\nAgent: Sure! I'd be happy to help you with that. When would work best for you?\\nCustomer: How about next Tuesday around 2pm?\\nAgent: Perfect! I have you scheduled for Tuesday at 2pm. You'll receive a confirmation email shortly.\\nCustomer: Great, thank you so much!\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\",\n \"vehlo_account_id\": \"vehlo_acct_12345\",\n \"vehlo_location_id\": \"vehlo_loc_67890\",\n \"account_name\": \"Example Auto Shop\",\n \"location_name\": \"Downtown Location\",\n \"location_street\": \"123 Main St\",\n \"location_city\": \"City\",\n \"location_state\": \"State\",\n \"location_zip\": \"12345\",\n \"location_country\": \"USA\",\n \"conversation_metadata\": {\n \"platform\": \"sms\",\n \"participants\": [\"Customer\", \"Agent\"],\n \"started_at\": \"2026-01-29T14:00:00Z\",\n \"message_count\": 5\n }\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] }, "description": "Submit a text conversation (SMS, chat, etc.) for sentiment analysis.\n\n**Required fields:**\n- `conversation_text` - Full text of the conversation (10-100,000 characters)\n- `external_account_id` - Your integrator's account identifier\n- `external_location_id` - Your integrator's location identifier\n\n**Optional Vehlo linking fields:**\n- `vehlo_account_id` - Vehlo centralized account ID\n- `vehlo_location_id` - Vehlo centralized location ID\n- `account_name` - Display name for account\n- `location_name` - Display name for location\n\n**Optional location address fields (parsed):**\n- `location_street` - Street address (e.g., \"123 Main St\")\n- `location_city` - City name\n- `location_state` - State/Province\n- `location_zip` - ZIP/Postal code\n- `location_country` - Country (defaults to \"USA\")\n\n**Optional metadata:**\n- `conversation_metadata` - JSON object with platform, participants, timestamps, etc.\n\n**Security:**\nText is automatically sanitized to remove null bytes, control characters, and validate UTF-8 encoding.\n\n**Response:**\n- `uuid` - Use this to check status\n- `status` - Will be 'pending'\n- `message` - Confirmation message" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": \"Customer: Hi, I need help\\nAgent: Sure! How can I assist you?\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"conv-550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Text conversation submitted successfully. Processing started.\",\n \"created_at\": \"2026-01-29T12:00:00Z\"\n}" } ] }, { "name": "Submit Text Conversation (Minimal)", "event": [ { "listen": "test", "script": { "exec": [ "// Store conversation UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('conversation_uuid', jsonData.uuid);", " pm.test('Conversation UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData.status).to.equal('pending');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": \"Customer: Hi, I need to schedule a service appointment\\nAgent: Sure! I'd be happy to help you with that. When would work best for you?\\nCustomer: How about next Tuesday around 2pm?\\nAgent: Perfect! I have you scheduled for Tuesday at 2pm. You'll receive a confirmation email shortly.\\nCustomer: Great, thank you so much!\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] }, "description": "**BARE MINIMUM REQUEST** - Submit a text conversation with only the essentials.\n\n**Required fields:**\n- `conversation_text` - Full text of the conversation (10-100,000 characters)\n\n**What happens:**\n- Account and location are automatically set to \"Unassigned\"\n- Conversation is analyzed for sentiment\n- Returns UUID for checking status and retrieving results\n\n**Use this when:**\n- You want to quickly test sentiment analysis\n- You don't need to track account/location\n- You just want sentiment analysis and summary\n\n**Text formats supported:**\n- Plain text with speaker labels: \"Customer: Hello\\nAgent: Hi there\"\n- JSON array: '[{\"speaker\":\"customer\",\"text\":\"Hello\"},{\"speaker\":\"agent\",\"text\":\"Hi\"}]'\n\n**Next steps:**\n1. Use the returned UUID with \"Get Text Conversation Status\" to check progress\n2. Once completed, use \"Get Text Conversation Sentiment\" or \"Get Text Conversation Full Analysis\" to retrieve results" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": \"Customer: Hi, I need help\\nAgent: Sure! How can I assist you?\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"conv-550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Text conversation submitted successfully. Processing started.\",\n \"created_at\": \"2026-01-29T12:00:00Z\"\n}" } ] }, { "name": "Submit Text Conversation (JSON String - speaker/text)", "event": [ { "listen": "test", "script": { "exec": [ "// Store conversation UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('conversation_uuid', jsonData.uuid);", " pm.test('Conversation UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData.status).to.equal('pending');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": \"[{\\\"speaker\\\":\\\"customer\\\",\\\"text\\\":\\\"Hi, my brakes have been squeaking badly.\\\",\\\"timestamp\\\":\\\"2025-03-18T09:15:00Z\\\"},{\\\"speaker\\\":\\\"agent\\\",\\\"text\\\":\\\"I can help with that. Let me check our schedule.\\\",\\\"timestamp\\\":\\\"2025-03-18T09:15:45Z\\\"},{\\\"speaker\\\":\\\"customer\\\",\\\"text\\\":\\\"Great, thank you!\\\",\\\"timestamp\\\":\\\"2025-03-18T09:16:20Z\\\"}]\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] }, "description": "**FORMAT OPTION 2: JSON String with speaker/text fields**\n\nThis example shows how to submit conversation_text as a JSON-encoded string using speaker/text format.\n\n**Format:**\n- `conversation_text` is a **string** containing JSON (with escaped quotes)\n- Each message has: `speaker`, `text`, `timestamp` (optional)\n- Speaker values: \"customer\", \"agent\", \"caller\", \"shop_employee\"\n\n**When to use:**\n- Your system already generates JSON strings\n- You need backwards compatibility with older code\n- You're working with systems that don't support nested JSON objects\n\n**Note:** The JSON array format (direct object, not string) is now recommended for better readability." }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": \"[{\\\"speaker\\\":\\\"customer\\\",\\\"text\\\":\\\"Hi, my brakes have been squeaking badly.\\\",\\\"timestamp\\\":\\\"2025-03-18T09:15:00Z\\\"},{\\\"speaker\\\":\\\"agent\\\",\\\"text\\\":\\\"I can help with that. Let me check our schedule.\\\",\\\"timestamp\\\":\\\"2025-03-18T09:15:45Z\\\"},{\\\"speaker\\\":\\\"customer\\\",\\\"text\\\":\\\"Great, thank you!\\\",\\\"timestamp\\\":\\\"2025-03-18T09:16:20Z\\\"}]\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"conv-550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Text conversation submitted successfully. Processing started.\",\n \"created_at\": \"2026-01-29T12:00:00Z\"\n}" } ] }, { "name": "Submit Text Conversation (JSON String - direction/message)", "event": [ { "listen": "test", "script": { "exec": [ "// Store conversation UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('conversation_uuid', jsonData.uuid);", " pm.test('Conversation UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData.status).to.equal('pending');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": \"[{\\\"direction\\\":\\\"in\\\",\\\"message\\\":\\\"Hi, my brakes have been squeaking badly.\\\",\\\"timestamp\\\":\\\"2025-03-18T09:15:00Z\\\"},{\\\"direction\\\":\\\"out\\\",\\\"message\\\":\\\"I can help with that. Let me check our schedule.\\\",\\\"timestamp\\\":\\\"2025-03-18T09:15:45Z\\\"},{\\\"direction\\\":\\\"in\\\",\\\"message\\\":\\\"Great, thank you!\\\",\\\"timestamp\\\":\\\"2025-03-18T09:16:20Z\\\"}]\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] }, "description": "**FORMAT OPTION 3: JSON String with direction/message fields**\n\nThis example shows how to submit conversation_text as a JSON-encoded string using direction/message format.\n\n**Format:**\n- `conversation_text` is a **string** containing JSON (with escaped quotes)\n- Each message has: `direction`, `message`, `timestamp` (optional)\n- Direction values: \"in\" (customer), \"out\" (shop)\n\n**Direction mapping:**\n- `in` / `inbound` / `incoming` = Message TO shop (from customer)\n- `out` / `outbound` / `outgoing` = Message FROM shop (to customer)\n\n**When to use:**\n- You're working with telecom/messaging systems that use \"in/out\" terminology\n- Your data already has direction fields\n- You prefer the \"direction\" semantic over \"speaker\"\n\n**Note:** The JSON array format (direct object, not string) is now recommended for better readability." }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": \"[{\\\"direction\\\":\\\"in\\\",\\\"message\\\":\\\"Hi, my brakes have been squeaking badly.\\\",\\\"timestamp\\\":\\\"2025-03-18T09:15:00Z\\\"},{\\\"direction\\\":\\\"out\\\",\\\"message\\\":\\\"I can help with that. Let me check our schedule.\\\",\\\"timestamp\\\":\\\"2025-03-18T09:15:45Z\\\"},{\\\"direction\\\":\\\"in\\\",\\\"message\\\":\\\"Great, thank you!\\\",\\\"timestamp\\\":\\\"2025-03-18T09:16:20Z\\\"}]\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"conv-550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Text conversation submitted successfully. Processing started.\",\n \"created_at\": \"2026-01-29T12:00:00Z\"\n}" } ] }, { "name": "Good Conversation Example (Positive Sentiment)", "event": [ { "listen": "test", "script": { "exec": [ "// Store conversation UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('conversation_uuid', jsonData.uuid);", " pm.test('Conversation UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData.status).to.equal('pending');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": [\n {\n \"direction\": \"out\",\n \"message\": \"Hi! This is Sarah from AutoCare Service Center. Just following up on your brake service today. How did everything go?\",\n \"timestamp\": \"2025-03-18T16:30:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Hi Sarah! Everything went great. The brakes feel so much better now.\",\n \"timestamp\": \"2025-03-18T16:32:15Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"That's wonderful to hear! Did you notice the vibration is gone when braking at highway speeds?\",\n \"timestamp\": \"2025-03-18T16:32:45Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Yes! It's completely smooth now. You guys were right about the warped rotors.\",\n \"timestamp\": \"2025-03-18T16:33:20Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"Perfect! I'm so glad we could get that fixed for you. Is there anything else you need help with?\",\n \"timestamp\": \"2025-03-18T16:33:50Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Nope, all good! Thank you so much for the great service. I really appreciate how quickly you got me in and the thorough explanation of what was wrong.\",\n \"timestamp\": \"2025-03-18T16:34:30Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"You're very welcome! We're always here if you need anything. Drive safe!\",\n \"timestamp\": \"2025-03-18T16:35:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Will do. I'll definitely be back and recommend you guys to my friends!\",\n \"timestamp\": \"2025-03-18T16:35:30Z\"\n }\n ],\n \"external_account_id\": \"12345\",\n \"external_location_id\": \"67890\",\n \"vehlo_account_id\": \"a1b2c3d4-e5f6-4789-a012-3456789abcde\",\n \"vehlo_location_id\": \"b2c3d4e5-f6a7-4890-b123-456789abcdef\",\n \"account_name\": \"AutoCare Service Centers\",\n \"location_name\": \"Downtown Location\",\n \"location_street\": \"456 Main Street\",\n \"location_city\": \"Springfield\",\n \"location_state\": \"IL\",\n \"location_zip\": \"62701\",\n \"location_country\": \"USA\",\n \"conversation_metadata\": \"{\\\"platform\\\":\\\"sms\\\",\\\"customer_phone\\\":\\\"+15551234567\\\",\\\"shop_phone\\\":\\\"+15559876543\\\",\\\"service_type\\\":\\\"brake_repair\\\",\\\"vehicle\\\":\\\"2019 Honda Civic\\\",\\\"message_count\\\":8}\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] }, "description": "**EXAMPLE: Positive Sentiment Conversation**\n\nThis is a real-world example of a positive customer service interaction.\n\n**Scenario:**\n- Service: Brake repair (warped rotors)\n- Customer satisfaction: High\n- Expected sentiment: Positive (75-90 score)\n\n**Format:**\n- Uses **JSON array with direction/message** (RECOMMENDED)\n- Includes all optional fields (account, location, metadata)\n- Shows realistic multi-message conversation\n\n**Expected Analysis:**\n- Sentiment Score: ~85-92 (positive)\n- Keywords: brake, service, great, smooth, appreciate, recommend\n- Summary: Customer satisfied with brake repair service, plans to return and recommend\n\n**Use this example to:**\n- Test positive sentiment detection\n- See complete parameter usage\n- Understand expected response format" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": [\n {\n \"direction\": \"out\",\n \"message\": \"Hi! This is Sarah from AutoCare Service Center. Just following up on your brake service today. How did everything go?\",\n \"timestamp\": \"2025-03-18T16:30:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Hi Sarah! Everything went great. The brakes feel so much better now.\",\n \"timestamp\": \"2025-03-18T16:32:15Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"That's wonderful to hear! Did you notice the vibration is gone when braking at highway speeds?\",\n \"timestamp\": \"2025-03-18T16:32:45Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Yes! It's completely smooth now. You guys were right about the warped rotors.\",\n \"timestamp\": \"2025-03-18T16:33:20Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"Perfect! I'm so glad we could get that fixed for you. Is there anything else you need help with?\",\n \"timestamp\": \"2025-03-18T16:33:50Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Nope, all good! Thank you so much for the great service. I really appreciate how quickly you got me in and the thorough explanation of what was wrong.\",\n \"timestamp\": \"2025-03-18T16:34:30Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"You're very welcome! We're always here if you need anything. Drive safe!\",\n \"timestamp\": \"2025-03-18T16:35:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Will do. I'll definitely be back and recommend you guys to my friends!\",\n \"timestamp\": \"2025-03-18T16:35:30Z\"\n }\n ],\n \"external_account_id\": \"12345\",\n \"external_location_id\": \"67890\",\n \"vehlo_account_id\": \"a1b2c3d4-e5f6-4789-a012-3456789abcde\",\n \"vehlo_location_id\": \"b2c3d4e5-f6a7-4890-b123-456789abcdef\",\n \"account_name\": \"AutoCare Service Centers\",\n \"location_name\": \"Downtown Location\",\n \"location_street\": \"456 Main Street\",\n \"location_city\": \"Springfield\",\n \"location_state\": \"IL\",\n \"location_zip\": \"62701\",\n \"location_country\": \"USA\",\n \"conversation_metadata\": \"{\\\"platform\\\":\\\"sms\\\",\\\"customer_phone\\\":\\\"+15551234567\\\",\\\"shop_phone\\\":\\\"+15559876543\\\",\\\"service_type\\\":\\\"brake_repair\\\",\\\"vehicle\\\":\\\"2019 Honda Civic\\\",\\\"message_count\\\":8}\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"conv-550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Text conversation submitted successfully. Processing started.\",\n \"created_at\": \"2026-01-29T12:00:00Z\"\n}" } ] }, { "name": "Bad Conversation Example (Negative Sentiment)", "event": [ { "listen": "test", "script": { "exec": [ "// Store conversation UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('conversation_uuid', jsonData.uuid);", " pm.test('Conversation UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData.status).to.equal('pending');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": [\n {\n \"direction\": \"out\",\n \"message\": \"Hi, this is Mike from AutoCare. Following up on your oil change from yesterday. How's everything running?\",\n \"timestamp\": \"2025-03-18T14:00:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Not good. I'm pretty upset actually. After I left your shop, I noticed oil spots in my driveway.\",\n \"timestamp\": \"2025-03-18T14:02:30Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"Oh no, I'm very sorry to hear that. Can you bring it back so we can take a look?\",\n \"timestamp\": \"2025-03-18T14:03:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"I already had to take time off work yesterday. This is the second time I've had issues with your service. Last month the tire pressure light came on the same day.\",\n \"timestamp\": \"2025-03-18T14:04:15Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"I completely understand your frustration. Let me see what I can do to make this right. Can you come in today?\",\n \"timestamp\": \"2025-03-18T14:05:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"I can't. I have to work. And honestly, I'm not sure I trust you guys anymore. The oil filter wasn't even tightened properly.\",\n \"timestamp\": \"2025-03-18T14:06:45Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"I sincerely apologize. That's not acceptable. We can send a mobile tech to your location if that helps?\",\n \"timestamp\": \"2025-03-18T14:07:30Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"I'll think about it. But I'm probably going to find another shop. This has been really disappointing.\",\n \"timestamp\": \"2025-03-18T14:08:45Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"I completely understand. If you do decide to give us another chance, we'll make it right. Again, I'm very sorry for the experience.\",\n \"timestamp\": \"2025-03-18T14:09:30Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Ok.\",\n \"timestamp\": \"2025-03-18T14:10:00Z\"\n }\n ],\n \"external_account_id\": \"54321\",\n \"external_location_id\": \"98765\",\n \"vehlo_account_id\": \"c3d4e5f6-a7b8-4901-c234-56789abcdef0\",\n \"vehlo_location_id\": \"d4e5f6a7-b8c9-4012-d345-6789abcdef01\",\n \"account_name\": \"AutoCare Service Centers\",\n \"location_name\": \"Westside Location\",\n \"location_street\": \"789 Oak Avenue\",\n \"location_city\": \"Springfield\",\n \"location_state\": \"IL\",\n \"location_zip\": \"62704\",\n \"location_country\": \"USA\",\n \"conversation_metadata\": \"{\\\"platform\\\":\\\"sms\\\",\\\"customer_phone\\\":\\\"+15559876543\\\",\\\"shop_phone\\\":\\\"+15551234567\\\",\\\"service_type\\\":\\\"oil_change\\\",\\\"vehicle\\\":\\\"2021 Toyota Camry\\\",\\\"message_count\\\":10,\\\"previous_issues\\\":true}\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] }, "description": "**EXAMPLE: Negative Sentiment Conversation**\n\nThis is a real-world example of a frustrated customer interaction.\n\n**Scenario:**\n- Service: Oil change (quality issues)\n- Customer satisfaction: Low\n- Expected sentiment: Negative (15-35 score)\n\n**Format:**\n- Uses **JSON array with direction/message** (RECOMMENDED)\n- Includes all optional fields\n- Shows realistic complaint scenario\n\n**Expected Analysis:**\n- Sentiment Score: ~20-30 (negative)\n- Keywords: upset, oil leak, disappointed, trust, second time\n- Summary: Customer frustrated with service quality issues, considering switching shops\n\n**Metadata includes:**\n- `previous_issues: true` - Flags repeat problems\n\n**Use this example to:**\n- Test negative sentiment detection\n- Understand complaint handling analysis\n- See how repeated issues affect sentiment" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": [\n {\n \"direction\": \"out\",\n \"message\": \"Hi, this is Mike from AutoCare. Following up on your oil change from yesterday. How's everything running?\",\n \"timestamp\": \"2025-03-18T14:00:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Not good. I'm pretty upset actually. After I left your shop, I noticed oil spots in my driveway.\",\n \"timestamp\": \"2025-03-18T14:02:30Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"Oh no, I'm very sorry to hear that. Can you bring it back so we can take a look?\",\n \"timestamp\": \"2025-03-18T14:03:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"I already had to take time off work yesterday. This is the second time I've had issues with your service. Last month the tire pressure light came on the same day.\",\n \"timestamp\": \"2025-03-18T14:04:15Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"I completely understand your frustration. Let me see what I can do to make this right. Can you come in today?\",\n \"timestamp\": \"2025-03-18T14:05:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"I can't. I have to work. And honestly, I'm not sure I trust you guys anymore. The oil filter wasn't even tightened properly.\",\n \"timestamp\": \"2025-03-18T14:06:45Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"I sincerely apologize. That's not acceptable. We can send a mobile tech to your location if that helps?\",\n \"timestamp\": \"2025-03-18T14:07:30Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"I'll think about it. But I'm probably going to find another shop. This has been really disappointing.\",\n \"timestamp\": \"2025-03-18T14:08:45Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"I completely understand. If you do decide to give us another chance, we'll make it right. Again, I'm very sorry for the experience.\",\n \"timestamp\": \"2025-03-18T14:09:30Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Ok.\",\n \"timestamp\": \"2025-03-18T14:10:00Z\"\n }\n ],\n \"external_account_id\": \"54321\",\n \"external_location_id\": \"98765\",\n \"vehlo_account_id\": \"c3d4e5f6-a7b8-4901-c234-56789abcdef0\",\n \"vehlo_location_id\": \"d4e5f6a7-b8c9-4012-d345-6789abcdef01\",\n \"account_name\": \"AutoCare Service Centers\",\n \"location_name\": \"Westside Location\",\n \"location_street\": \"789 Oak Avenue\",\n \"location_city\": \"Springfield\",\n \"location_state\": \"IL\",\n \"location_zip\": \"62704\",\n \"location_country\": \"USA\",\n \"conversation_metadata\": \"{\\\"platform\\\":\\\"sms\\\",\\\"customer_phone\\\":\\\"+15559876543\\\",\\\"shop_phone\\\":\\\"+15551234567\\\",\\\"service_type\\\":\\\"oil_change\\\",\\\"vehicle\\\":\\\"2021 Toyota Camry\\\",\\\"message_count\\\":10,\\\"previous_issues\\\":true}\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"conv-550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Text conversation submitted successfully. Processing started.\",\n \"created_at\": \"2026-01-29T12:00:00Z\"\n}" } ] }, { "name": "Neutral Conversation Example (Mixed Sentiment)", "event": [ { "listen": "test", "script": { "exec": [ "// Store conversation UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('conversation_uuid', jsonData.uuid);", " pm.test('Conversation UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('status');", " pm.expect(jsonData.status).to.equal('pending');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": [\n {\n \"direction\": \"out\",\n \"message\": \"Hi! This is David from AutoCare Service. Just checking in about your transmission service this morning. Everything ok?\",\n \"timestamp\": \"2025-03-18T15:00:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Yeah, it's fine. The car seems to be shifting normally.\",\n \"timestamp\": \"2025-03-18T15:05:30Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"Great! Did you have any questions about the service we performed or the invoice?\",\n \"timestamp\": \"2025-03-18T15:06:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Actually yes. The price was higher than I expected. The quote was $299 but the final bill was $385.\",\n \"timestamp\": \"2025-03-18T15:07:15Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"I apologize for the confusion. The quote was for the basic service, but we also needed to replace the transmission filter which added $86. I should have called you before doing that work.\",\n \"timestamp\": \"2025-03-18T15:08:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Oh, ok. I guess that makes sense. I just wish I had known beforehand.\",\n \"timestamp\": \"2025-03-18T15:09:20Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"You're absolutely right. I'll make a note in your file to always call before adding any services. Is there anything else I can help clarify?\",\n \"timestamp\": \"2025-03-18T15:10:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"No, that's it. Thanks for explaining.\",\n \"timestamp\": \"2025-03-18T15:11:00Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"Of course. We appreciate your business. Have a great day!\",\n \"timestamp\": \"2025-03-18T15:11:30Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"You too.\",\n \"timestamp\": \"2025-03-18T15:12:00Z\"\n }\n ],\n \"external_account_id\": \"24680\",\n \"external_location_id\": \"13579\",\n \"vehlo_account_id\": \"e5f6a7b8-c9d0-4123-e456-789abcdef012\",\n \"vehlo_location_id\": \"f6a7b8c9-d0e1-4234-f567-89abcdef0123\",\n \"account_name\": \"AutoCare Service Centers\",\n \"location_name\": \"North Side Location\",\n \"location_street\": \"321 Elm Boulevard\",\n \"location_city\": \"Springfield\",\n \"location_state\": \"IL\",\n \"location_zip\": \"62702\",\n \"location_country\": \"USA\",\n \"conversation_metadata\": \"{\\\"platform\\\":\\\"sms\\\",\\\"customer_phone\\\":\\\"+15557891234\\\",\\\"shop_phone\\\":\\\"+15554567890\\\",\\\"service_type\\\":\\\"transmission_service\\\",\\\"vehicle\\\":\\\"2020 Ford F-150\\\",\\\"message_count\\\":10,\\\"invoice_amount\\\":385}\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] }, "description": "**EXAMPLE: Neutral/Mixed Sentiment Conversation**\n\nThis is a real-world example of a service interaction with mixed feelings.\n\n**Scenario:**\n- Service: Transmission service (pricing confusion)\n- Customer satisfaction: Neutral/Mixed\n- Expected sentiment: Neutral (45-60 score)\n\n**Format:**\n- Uses **JSON array with direction/message** (RECOMMENDED)\n- Includes all optional fields\n- Shows realistic pricing discussion\n\n**Expected Analysis:**\n- Sentiment Score: ~50-58 (neutral)\n- Keywords: transmission, price, confusion, explain, clarify\n- Summary: Service acceptable but communication could improve. Customer satisfied with explanation but wished for upfront notification\n\n**Metadata includes:**\n- `invoice_amount: 385` - Tracks pricing context\n\n**Use this example to:**\n- Test neutral/mixed sentiment detection\n- Understand how issues + resolution affect sentiment\n- See communication improvement opportunities" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"conversation_text\": [\n {\n \"direction\": \"out\",\n \"message\": \"Hi! This is David from AutoCare Service. Just checking in about your transmission service this morning. Everything ok?\",\n \"timestamp\": \"2025-03-18T15:00:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Yeah, it's fine. The car seems to be shifting normally.\",\n \"timestamp\": \"2025-03-18T15:05:30Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"Great! Did you have any questions about the service we performed or the invoice?\",\n \"timestamp\": \"2025-03-18T15:06:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Actually yes. The price was higher than I expected. The quote was $299 but the final bill was $385.\",\n \"timestamp\": \"2025-03-18T15:07:15Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"I apologize for the confusion. The quote was for the basic service, but we also needed to replace the transmission filter which added $86. I should have called you before doing that work.\",\n \"timestamp\": \"2025-03-18T15:08:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"Oh, ok. I guess that makes sense. I just wish I had known beforehand.\",\n \"timestamp\": \"2025-03-18T15:09:20Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"You're absolutely right. I'll make a note in your file to always call before adding any services. Is there anything else I can help clarify?\",\n \"timestamp\": \"2025-03-18T15:10:00Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"No, that's it. Thanks for explaining.\",\n \"timestamp\": \"2025-03-18T15:11:00Z\"\n },\n {\n \"direction\": \"out\",\n \"message\": \"Of course. We appreciate your business. Have a great day!\",\n \"timestamp\": \"2025-03-18T15:11:30Z\"\n },\n {\n \"direction\": \"in\",\n \"message\": \"You too.\",\n \"timestamp\": \"2025-03-18T15:12:00Z\"\n }\n ],\n \"external_account_id\": \"24680\",\n \"external_location_id\": \"13579\",\n \"vehlo_account_id\": \"e5f6a7b8-c9d0-4123-e456-789abcdef012\",\n \"vehlo_location_id\": \"f6a7b8c9-d0e1-4234-f567-89abcdef0123\",\n \"account_name\": \"AutoCare Service Centers\",\n \"location_name\": \"North Side Location\",\n \"location_street\": \"321 Elm Boulevard\",\n \"location_city\": \"Springfield\",\n \"location_state\": \"IL\",\n \"location_zip\": \"62702\",\n \"location_country\": \"USA\",\n \"conversation_metadata\": \"{\\\"platform\\\":\\\"sms\\\",\\\"customer_phone\\\":\\\"+15557891234\\\",\\\"shop_phone\\\":\\\"+15554567890\\\",\\\"service_type\\\":\\\"transmission_service\\\",\\\"vehicle\\\":\\\"2020 Ford F-150\\\",\\\"message_count\\\":10,\\\"invoice_amount\\\":385}\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"conv-550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Text conversation submitted successfully. Processing started.\",\n \"created_at\": \"2026-01-29T12:00:00Z\"\n}" } ] }, { "name": "Start Incremental Conversation", "event": [ { "listen": "test", "script": { "exec": [ "// Store conversation UUID for subsequent requests", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('incremental_conversation_uuid', jsonData.uuid);", " pm.test('Incremental conversation UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "// Validate response", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID and is_incremental flag', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('is_incremental');", " pm.expect(jsonData.is_incremental).to.equal(true);", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"direction\": \"in\",\n \"message\": \"Hi, I need to schedule an oil change\",\n \"timestamp\": \"2024-01-30T14:00:00Z\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\",\n \"account_name\": \"Example Auto Shop\",\n \"location_name\": \"Downtown Location\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations/start", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "start" ] }, "description": "**Start an incremental conversation** - Build conversations message-by-message in real-time\n\n**Use this when:**\n- Conversations happen in real-time (SMS, live chat)\n- You want to add messages as they arrive\n- You need to track ongoing conversations\n\n**Required fields:**\n- `direction` - \"in\" (customer) or \"out\" (agent/shop)\n- `message` - The first message text\n\n**Optional fields:**\n- `timestamp` - Message timestamp (defaults to current time)\n- `external_account_id` - Your account identifier\n- `external_location_id` - Your location identifier\n- `vehlo_account_id` - Vehlo centralized account ID\n- `vehlo_location_id` - Vehlo centralized location ID\n- `account_name` - Display name for account\n- `location_name` - Display name for location\n\n**Next steps:**\n1. Save the returned UUID\n2. Use \"Add Message to Incremental Conversation\" to add more messages\n3. Use \"Close Incremental Conversation\" when done to trigger analysis" }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"direction\": \"in\",\n \"message\": \"Hi, I need to schedule an oil change\",\n \"timestamp\": \"2024-01-30T14:00:00Z\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations/start", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "start" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"is_incremental\": true,\n \"message\": \"Incremental conversation started. Add messages using the UUID.\",\n \"created_at\": \"2026-01-29T12:00:00Z\"\n}" } ] }, { "name": "Add Message to Incremental Conversation", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"direction\": \"out\",\n \"message\": \"Great! We have availability tomorrow at 2pm\",\n \"timestamp\": \"2024-01-30T14:05:00Z\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations/{{incremental_conversation_uuid}}/messages", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "{{incremental_conversation_uuid}}", "messages" ] }, "description": "**Add a message** to an existing incremental conversation\n\n**Required fields:**\n- `direction` - \"in\" (customer) or \"out\" (agent/shop)\n- `message` - The message text\n\n**Optional fields:**\n- `timestamp` - Message timestamp (defaults to current time)\n\n**Use the UUID from:**\n- The \"Start Incremental Conversation\" response\n- Or use the environment variable `{{incremental_conversation_uuid}}`\n\n**Response includes:**\n- `message_count` - Total messages in conversation\n- `last_message_at` - Timestamp of most recent message\n\n**Call this endpoint** for each new message as it arrives in real-time." }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"direction\": \"out\",\n \"message\": \"Great! We have availability tomorrow at 2pm\",\n \"timestamp\": \"2024-01-30T14:05:00Z\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations/{{incremental_conversation_uuid}}/messages", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "{{incremental_conversation_uuid}}", "messages" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message_count\": 3,\n \"last_message_at\": \"2024-01-30T14:05:00Z\",\n \"message\": \"Message added successfully\"\n}" } ] }, { "name": "Close Incremental Conversation", "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations/{{incremental_conversation_uuid}}/close", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "{{incremental_conversation_uuid}}", "close" ] }, "description": "**Close an incremental conversation** and trigger sentiment analysis\n\n**Requirements:**\n- Conversation must have at least 2 messages\n- Conversation must not already be closed/processing\n\n**What happens:**\n- Conversation is marked as complete\n- Sentiment analysis job is queued\n- No more messages can be added\n\n**Next steps:**\n- Use \"Get Text Conversation Status\" to poll for completion\n- Once completed, use \"Get Text Conversation Sentiment\" or \"Get Text Conversation Full Analysis\" to retrieve results\n\n**Important:**\nClosing is final - you cannot add more messages after closing. Make sure the conversation is complete before calling this endpoint." }, "response": [ { "name": "Success Response", "originalRequest": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations/{{incremental_conversation_uuid}}/close", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "{{incremental_conversation_uuid}}", "close" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"pending\",\n \"message\": \"Conversation closed and processing started\"\n}" } ] }, { "name": "Get Text Conversation Status", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/text-conversations/{{conversation_uuid}}", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "{{conversation_uuid}}" ] }, "description": "Get the current status and results of a text conversation.\n\n**Statuses:**\n- `pending` - Waiting to be processed\n- `processing` - Running sentiment analysis\n- `completed` - Fully processed with results\n- `failed` - Processing failed (check error_message)\n\n**Response includes:**\n- Basic conversation info\n- Sentiment analysis (if completed)\n- Error message (if failed)" }, "response": [] }, { "name": "Get Text Conversation Sentiment", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/text-conversations/{{conversation_uuid}}/sentiment", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "{{conversation_uuid}}", "sentiment" ] }, "description": "Get sentiment analysis results for text conversation.\n\n**Requirements:**\n- Conversation must be in 'completed' status\n\n**Returns:**\n- `sentiment_score` - 0-100 (0=negative, 50=neutral, 100=positive)\n- `sentiment_label` - 'positive', 'neutral', or 'negative'\n- `keywords` - Array of key topics\n- `summary` - 2-3 sentence conversation summary\n- `metadata` - Additional context" }, "response": [] }, { "name": "Get Text Conversation Full Analysis", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/text-conversations/{{conversation_uuid}}/full", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "{{conversation_uuid}}", "full" ] }, "description": "Get complete analysis including conversation text and sentiment in a single response.\n\n**Requirements:**\n- Conversation must be in 'completed' status\n\n**Returns:**\n- Conversation metadata\n- Full conversation text\n- Complete sentiment analysis" }, "response": [] }, { "name": "Start Incremental Conversation", "event": [ { "listen": "test", "script": { "exec": [ "// Store conversation UUID for adding messages", "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.environment.set('incremental_conversation_uuid', jsonData.uuid);", " pm.test('Incremental Conversation UUID saved: ' + jsonData.uuid, function() {", " pm.expect(jsonData.uuid).to.be.a('string');", " });", "}", "", "pm.test('Status code is 201 Created', function() {", " pm.response.to.have.status(201);", "});", "", "pm.test('Response has UUID and is_incremental', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('uuid');", " pm.expect(jsonData).to.have.property('is_incremental');", " pm.expect(jsonData.is_incremental).to.equal(true);", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"direction\": \"in\",\n \"message\": \"Hi, I need to schedule an oil change\",\n \"timestamp\": \"2024-01-30T14:00:00Z\",\n \"external_account_id\": \"account_12345\",\n \"external_location_id\": \"location_67890\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations/start", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "start" ] }, "description": "Start a new incremental text conversation with the first message.\n\n**Required fields:**\n- `direction` - 'in' for customer messages, 'out' for shop/agent messages\n- `message` - The message text\n\n**Optional fields:**\n- `timestamp` - ISO 8601 timestamp (defaults to current time)\n- `external_account_id` - Your account identifier\n- `external_location_id` - Your location identifier\n\n**Response:**\n- `uuid` - Use this to add more messages or close the conversation\n- `is_incremental` - Always true for incremental conversations\n- `status` - Will be 'pending' until closed" }, "response": [] }, { "name": "Add Message to Incremental Conversation", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status code is 200 OK', function() {", " pm.response.to.have.status(200);", "});", "", "pm.test('Message count incremented', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('message_count');", " pm.expect(jsonData.message_count).to.be.above(1);", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" }, { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"direction\": \"out\",\n \"message\": \"Great! We have availability tomorrow at 2pm. Does that work for you?\",\n \"timestamp\": \"2024-01-30T14:05:00Z\"\n}" }, "url": { "raw": "{{app_url}}/api/v1/text-conversations/{{incremental_conversation_uuid}}/messages", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "{{incremental_conversation_uuid}}", "messages" ] }, "description": "Add a message to an existing incremental conversation.\n\n**Required fields:**\n- `direction` - 'in' for customer, 'out' for shop/agent\n- `message` - The message text\n\n**Optional fields:**\n- `timestamp` - ISO 8601 timestamp (defaults to current time)\n\n**Note:**\n- Updates `last_message_at` to reset the inactivity timer\n- Conversation remains in 'pending' status" }, "response": [] }, { "name": "Close Incremental Conversation", "event": [ { "listen": "test", "script": { "exec": [ "pm.test('Status code is 200 OK', function() {", " pm.response.to.have.status(200);", "});", "", "pm.test('Conversation closed message', function() {", " var jsonData = pm.response.json();", " pm.expect(jsonData).to.have.property('message');", " pm.expect(jsonData.message).to.include('closed');", "});" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/text-conversations/{{incremental_conversation_uuid}}/close", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "text-conversations", "{{incremental_conversation_uuid}}", "close" ] }, "description": "Close an incremental conversation and trigger sentiment analysis.\n\n**Requirements:**\n- Conversation must have at least 2 messages\n- Conversation must be in 'pending' status\n\n**What happens:**\n- Triggers transcription and sentiment analysis jobs\n- Status transitions from 'pending' to 'processing' to 'completed'\n\n**Alternative:**\nConversations also auto-close after the configured inactivity timeout (default: 1 hour)" }, "response": [] }, { "name": "List Accounts", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/accounts?linked=yes&per_page=50&page=1", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "accounts" ], "query": [ { "key": "linked", "value": "yes", "description": "Filter by Vehlo linkage: 'yes' or 'no' (optional)" }, { "key": "per_page", "value": "50", "description": "Results per page (max 100, default 50)" }, { "key": "page", "value": "1", "description": "Page number" } ] }, "description": "**List all accounts for your integration**\n\nReturns a paginated list of all integrator accounts with linkage information.\n\n**Query Parameters:**\n- `linked` - Filter by Vehlo linkage status ('yes', 'no')\n- `per_page` - Results per page (max 100, default 50)\n- `page` - Page number\n\n**Response includes:**\n- Account ID and external account ID\n- Account name\n- Vehlo account linkage (if linked)\n- Creation timestamp\n- Pagination metadata" }, "response": [] }, { "name": "Get Account Details", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/accounts/{{external_account_id}}", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "accounts", "{{external_account_id}}" ] }, "description": "**Get detailed information for a specific account**\n\nReturns comprehensive account details including statistics and recent recordings.\n\n**Path Parameter:**\n- `external_account_id` - Your platform's account identifier\n\n**Response includes:**\n- Account metadata and Vehlo linkage\n- Recording statistics (total, completed, pending, failed)\n- 10 most recent recordings with basic info" }, "response": [] }, { "name": "List Locations", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/locations?linked=yes&per_page=50&page=1", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "locations" ], "query": [ { "key": "linked", "value": "yes", "description": "Filter by Vehlo linkage: 'yes' or 'no' (optional)" }, { "key": "per_page", "value": "50", "description": "Results per page (max 100, default 50)" }, { "key": "page", "value": "1", "description": "Page number" } ] }, "description": "**List all locations for your integration**\n\nReturns a paginated list of all integrator locations with linkage information.\n\n**Query Parameters:**\n- `linked` - Filter by Vehlo linkage status ('yes', 'no')\n- `per_page` - Results per page (max 100, default 50)\n- `page` - Page number\n\n**Response includes:**\n- Location ID and external location ID\n- Location name and address\n- Parent account identifier\n- Vehlo location linkage (if linked)\n- Creation timestamp\n- Pagination metadata" }, "response": [] }, { "name": "Get Location Details", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/locations/{{external_location_id}}", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "locations", "{{external_location_id}}" ] }, "description": "**Get detailed information for a specific location**\n\nReturns comprehensive location details including statistics and recent recordings.\n\n**Path Parameter:**\n- `external_location_id` - Your platform's location identifier\n\n**Response includes:**\n- Location metadata, address, and Vehlo linkage\n- Parent account information\n- Recording statistics (total, completed, pending, failed)\n- 10 most recent recordings with basic info" }, "response": [] }, { "name": "Get Platform Statistics", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/stats?date_from=2024-01-01&date_to=2024-12-31", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "stats" ], "query": [ { "key": "date_from", "value": "2024-01-01", "description": "Start date (YYYY-MM-DD) - optional" }, { "key": "date_to", "value": "2024-12-31", "description": "End date (YYYY-MM-DD) - optional" } ] }, "description": "**Get comprehensive platform statistics**\n\nReturns high-level metrics including:\n- Total communications processed\n- Processing breakdown by type and status\n- AI analysis statistics\n- Account and location counts\n- Success rates and sentiment distribution\n\n**Query Parameters:**\n- `date_from` - Start date (YYYY-MM-DD), optional\n- `date_to` - End date (YYYY-MM-DD), optional, defaults to today\n\n**Response includes:**\n- Overview: total communications, accounts, locations\n- Call recordings: status breakdown, success rates\n- Text conversations: status breakdown, success rates\n- AI processing: transcription and sentiment counts\n- Sentiment distribution: positive, neutral, negative breakdown" }, "response": [] }, { "name": "Get Trending Keywords", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/stats/keywords?limit=25&date_from=2024-01-01", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "stats", "keywords" ], "query": [ { "key": "limit", "value": "25", "description": "Number of keywords (default 50, max 200)" }, { "key": "date_from", "value": "2024-01-01", "description": "Start date (YYYY-MM-DD) - optional" }, { "key": "date_to", "value": "", "description": "End date (YYYY-MM-DD) - optional", "disabled": true } ] }, "description": "**Get most frequently occurring keywords**\n\nReturns top keywords extracted from sentiment analyses with occurrence counts.\n\n**Use Cases:**\n- Identify common topics and themes\n- Monitor trending issues or questions\n- Build word clouds\n- Track customer concerns\n\n**Query Parameters:**\n- `limit` - Number of keywords (default 50, max 200)\n- `date_from` - Start date, optional\n- `date_to` - End date, optional\n\n**Response:**\n- Array of keywords with counts\n- Total keywords returned\n- Date range applied" }, "response": [] }, { "name": "Get Sentiment Trends", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/stats/sentiment-trends?group_by=day&date_from=2024-01-01", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "stats", "sentiment-trends" ], "query": [ { "key": "group_by", "value": "day", "description": "Aggregation: day, week, or month (default: day)" }, { "key": "date_from", "value": "2024-01-01", "description": "Start date (YYYY-MM-DD) - defaults to 30 days ago" }, { "key": "date_to", "value": "", "description": "End date (YYYY-MM-DD) - optional", "disabled": true } ] }, "description": "**Get sentiment trends over time**\n\nReturns time-series data showing average sentiment scores over time.\n\n**Use Cases:**\n- Visualize sentiment trends in charts\n- Monitor customer satisfaction over time\n- Identify patterns and seasonal changes\n- Track improvement or decline\n\n**Aggregation:**\n- `day` - Daily averages (good for 1-3 months)\n- `week` - Weekly averages (good for 3-12 months)\n- `month` - Monthly averages (good for 1+ years)\n\n**Response:**\n- Time-series data with periods\n- Average sentiment scores per period\n- Counts of positive/neutral/negative per period\n- Total analyses per period" }, "response": [] }, { "name": "Get Token Usage Summary", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/stats/token-usage?date_from=2024-01-01", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "stats", "token-usage" ], "query": [ { "key": "date_from", "value": "2024-01-01", "description": "Start date (YYYY-MM-DD) - optional" }, { "key": "date_to", "value": "", "description": "End date (YYYY-MM-DD) - optional", "disabled": true } ] }, "description": "**Get AI token usage summary**\n\nReturns token usage and cost metrics for AI processing.\n\n**Response includes:**\n- Total tokens consumed\n- Total cost in USD\n- Breakdown by transcription vs sentiment analysis\n- Processing count\n- Average cost per processing" }, "response": [] }, { "name": "Get Token Usage Details", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/token-usage?date_from=2024-01-01&group_by=daily", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "token-usage" ], "query": [ { "key": "date_from", "value": "2024-01-01", "description": "Start date (YYYY-MM-DD) - defaults to first day of current month" }, { "key": "date_to", "value": "", "description": "End date (YYYY-MM-DD) - optional", "disabled": true }, { "key": "group_by", "value": "daily", "description": "Grouping: daily or monthly" } ] }, "description": "**Get detailed token usage with daily/monthly breakdown**\n\n**Response includes:**\n- Summary totals\n- Daily breakdown of usage\n- Cost metrics\n- Transcription vs sentiment analysis breakdown" }, "response": [] }, { "name": "Get Account Token Usage", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/token-usage/accounts/{{external_account_id}}?date_from=2024-01-01", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "token-usage", "accounts", "{{external_account_id}}" ], "query": [ { "key": "date_from", "value": "2024-01-01", "description": "Start date (YYYY-MM-DD) - optional" }, { "key": "date_to", "value": "", "description": "End date (YYYY-MM-DD) - optional", "disabled": true } ] }, "description": "**Get token usage for a specific account**\n\n**Path Parameter:**\n- `account_id` - Your external account ID\n\n**Response includes:**\n- Account details\n- Token usage summary\n- Daily breakdown\n- Cost metrics" }, "response": [] }, { "name": "Export Token Usage (Summary)", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}", "type": "text" } ], "url": { "raw": "{{app_url}}/api/v1/token-usage/export?format=summary&date_from=2024-01-01", "host": [ "{{app_url}}" ], "path": [ "api", "v1", "token-usage", "export" ], "query": [ { "key": "format", "value": "summary", "description": "Export format: summary or detailed" }, { "key": "date_from", "value": "2024-01-01", "description": "Start date (YYYY-MM-DD) - optional" }, { "key": "date_to", "value": "", "description": "End date (YYYY-MM-DD) - optional", "disabled": true } ] }, "description": "**Export token usage as CSV**\n\n**Formats:**\n- `summary` - Daily aggregated data\n- `detailed` - Per-recording/conversation data\n\n**CSV Columns (Summary):**\n- Date, Total Tokens, Total Cost (USD), Transcription Tokens, Transcription Cost (USD), Sentiment Tokens, Sentiment Cost (USD), Processing Count\n\n**CSV Columns (Detailed):**\n- Date, Type, UUID, AI Model, Input Tokens, Output Tokens, Total Tokens, Cost (USD), Processing Time (s)" }, "response": [] } ], "auth": { "type": "apikey", "apikey": [ { "key": "value", "value": "{{api_key}}", "type": "string" }, { "key": "key", "value": "X-API-Key", "type": "string" } ] }, "variable": [ { "key": "app_url", "value": "http://localhost:8000", "type": "string" }, { "key": "api_key", "value": "your_api_key_here", "type": "string" }, { "key": "recording_uuid", "value": "", "type": "string" }, { "key": "conversation_uuid", "value": "", "type": "string" }, { "key": "incremental_conversation_uuid", "value": "", "type": "string" }, { "key": "external_account_id", "value": "acct_12345", "type": "string" }, { "key": "external_location_id", "value": "loc_67890", "type": "string" } ] }