From b88e209c72b61960041aaad84b23f186ebc96a88 Mon Sep 17 00:00:00 2001 From: Margarita Gomez Date: Mon, 6 Oct 2025 19:39:25 -0700 Subject: [PATCH 1/3] Include recording logs and transcript pause in docs --- fern/assistants/call-recording.mdx | 472 ++++++++++++++++++++++++----- 1 file changed, 403 insertions(+), 69 deletions(-) diff --git a/fern/assistants/call-recording.mdx b/fern/assistants/call-recording.mdx index 16c215360..3187ee65b 100644 --- a/fern/assistants/call-recording.mdx +++ b/fern/assistants/call-recording.mdx @@ -1,31 +1,140 @@ --- -title: Call recording -subtitle: Record and store calls for analysis and training +title: Call recording, logging and transcribing +subtitle: Record, log, and transcribe calls using artifact plans slug: assistants/call-recording -description: Learn how to record calls and store them for quality assurance and analysis +description: Learn how to configure artifact plans to record calls, generate transcripts, and store logs for analysis --- + + **Deprecated**: The old `recordingEnabled`, `recordingPath`, and `recordingCredentials` properties are deprecated. Use the new `artifactPlan` configuration instead for recording, logging, and transcript generation. + + ## Overview -Vapi provides comprehensive call recording capabilities that allow you to capture, store, and analyze voice conversations for quality assurance, training, and compliance purposes. +Vapi's artifact plan system provides comprehensive call recording, logging, and transcription capabilities that allow you to capture, store, and analyze voice conversations for quality assurance, training, and compliance purposes. -**Call recording enables you to:** +**Artifact plans enable you to:** +- Record audio conversations for quality monitoring +- Generate detailed call logs for debugging and analysis +- Create transcripts for conversation analysis +- Store artifacts in custom storage or Vapi's secure cloud - Monitor conversation quality and assistant performance -- Train and improve your voice AI models - Ensure compliance with regulatory requirements -- Analyze customer interactions for insights -## Recording Configuration +## Use Cases + +### Payment Flows + +Protect sensitive payment information by using a middle assistant with all artifacts disabled: + +```json +{ + "squad": { + "members": [ + { + "assistant": { + "name": "Service Assistant", + "artifactPlan": { + "recordingEnabled": true, + "loggingEnabled": true, + "transcriptPlan": { "enabled": true } + } + } + }, + { + "assistant": { + "name": "Payment Assistant", + "artifactPlan": { + "recordingEnabled": false, + "loggingEnabled": false, + "transcriptPlan": { "enabled": false } + } + } + }, + { + "assistant": { + "name": "Confirmation Assistant", + "artifactPlan": { + "recordingEnabled": true, + "loggingEnabled": true, + "transcriptPlan": { "enabled": true } + } + } + } + ] + } +} +``` + +This flow ensures that: +- Service conversations are recorded for quality assurance +- Payment details (credit card numbers, CVV codes) are never recorded or logged +- Confirmation conversations are recorded for compliance + +### Consent Gathering + +For Enterprise customers, Vapi provides built-in [recording consent plans](/security-and-privacy/recording-consent-plan) that automatically create a consent assistant to request recording permission before transferring to your main assistant. + +The Enterprise consent feature supports both: +- **Verbal consent**: Requires explicit "yes" confirmation from users +- **Implicit consent**: Assumes consent if users stay on the line after hearing the consent message + +The system automatically tracks consent decisions and provides compliance data in the end-of-call report, including whether consent was granted and when it was obtained. + +Alternatively, you can implement custom consent flows using squads: + +```json +{ + "squad": { + "members": [ + { + "assistant": { + "name": "Consent Assistant", + "artifactPlan": { + "recordingEnabled": false, + "loggingEnabled": false, + "transcriptPlan": { "enabled": false } + } + } + }, + { + "assistant": { + "name": "Main Assistant", + "artifactPlan": { + "recordingEnabled": true, + "loggingEnabled": true, + "transcriptPlan": { "enabled": true } + } + } + } + ] + } +} +``` + +The consent assistant runs without generating artifacts, while the main assistant records the actual conversation after consent is obtained. + +## Artifact Plan Configuration -### Enable Recording +### Basic Configuration -You can enable call recording at the assistant level or per individual call: +Configure recording, logging, and transcript generation using the `artifactPlan`: ```json title="Assistant Configuration" { "name": "Customer Support Assistant", - "recordingEnabled": true, + "artifactPlan": { + "recordingEnabled": true, + "recordingFormat": "wav;l16", + "loggingEnabled": true, + "pcapEnabled": true, + "transcriptPlan": { + "enabled": true, + "assistantName": "Assistant", + "userName": "Customer" + } + }, "model": { "provider": "openai", "model": "gpt-4" @@ -40,82 +149,251 @@ You can enable call recording at the assistant level or per individual call: ```json title="Per-Call Configuration" { "assistant": { - "name": "Support Agent" + "name": "Support Agent", + "artifactPlan": { + "recordingEnabled": true, + "recordingFormat": "wav;l16", + "loggingEnabled": true, + "pcapEnabled": true, + "transcriptPlan": { + "enabled": true, + "assistantName": "Support Agent", + "userName": "Customer" + } + } }, - "recordingEnabled": true, "phoneNumberId": "your-phone-number-id" } ``` -### Recording Options +### Artifact Plan Options -Configure recording behavior with these options: +Configure different types of artifacts with these options: -- **`recordingEnabled`**: Enable or disable recording for this assistant/call -- **`recordingChannelCount`**: Number of audio channels to record (1 for mono, 2 for stereo) -- **`recordingFormat`**: Audio format for recordings (mp3, wav, etc.) +- **`recordingEnabled`**: Enable call recording (stored in `call.artifact.recording`) Default: `true` +- **`recordingFormat`**: Audio format for recordings (e.g., "wav;l16", "mp3") Default: "wav;l16" +- **`loggingEnabled`**: Enable detailed call logs (stored in `call.artifact.logUrl`) Default: `true` +- **`pcapEnabled`**: Enable SIP packet capture for phone calls (stored in `call.artifact.pcapUrl`) Default: `true` +- **`transcriptPlan`**: Configure transcript generation with speaker names -## Storage Options +## Storage Configuration ### Default Storage -By default, Vapi stores recordings securely in the cloud: +By default, Vapi stores artifacts securely in the cloud: -- Recordings are encrypted at rest and in transit +- Recordings, logs, and transcripts are encrypted at rest and in transit - Access is controlled through your API credentials -- Recordings are automatically cleaned up based on your retention policy +- Artifacts are automatically cleaned up based on your retention policy ### Custom Storage -For advanced use cases, you can configure custom storage: +Configure custom storage for different artifact types: ```json title="S3 Storage Configuration" { - "recordingEnabled": true, - "recordingPath": "https://your-bucket.s3.amazonaws.com/recordings/", - "recordingCredentials": { - "provider": "aws", - "region": "us-east-1", - "accessKeyId": "your-access-key", - "secretAccessKey": "your-secret-key" - } + "artifactPlan": { + "recordingEnabled": true, + "recordingFormat": "wav;l16", + "loggingEnabled": true, + "pcapEnabled": true, + "recordingUseCustomStorageEnabled": true, + "loggingUseCustomStorageEnabled": true, + "pcapUseCustomStorageEnabled": true, + "recordingPath": "https://your-bucket.s3.amazonaws.com/recordings/", + "loggingPath": "https://your-bucket.s3.amazonaws.com/logs/", + "pcapS3PathPrefix": "/pcaps", + "transcriptPlan": { + "enabled": true, + "assistantName": "Assistant", + "userName": "Customer" + } + }, + "credentials": [ + { + "provider": "aws", + "region": "us-east-1", + "accessKeyId": "your-access-key", + "secretAccessKey": "your-secret-key" + } + ] } ``` ```json title="Google Cloud Storage" { - "recordingEnabled": true, - "recordingPath": "gs://your-bucket/recordings/", - "recordingCredentials": { - "provider": "gcp", - "serviceAccountKey": "your-service-account-json" - } + "artifactPlan": { + "recordingEnabled": true, + "recordingFormat": "wav;l16", + "loggingEnabled": true, + "pcapEnabled": true, + "recordingUseCustomStorageEnabled": true, + "loggingUseCustomStorageEnabled": true, + "pcapUseCustomStorageEnabled": true, + "recordingPath": "gs://your-bucket/recordings/", + "loggingPath": "gs://your-bucket/logs/", + "transcriptPlan": { + "enabled": true, + "assistantName": "Assistant", + "userName": "Customer" + } + }, + "credentials": [ + { + "provider": "gcp", + "serviceAccountKey": "your-service-account-json" + } + ] } ``` -## Accessing Recordings +### Storage Control Options + +Control where each artifact type is stored: + +- **`recordingUseCustomStorageEnabled`**: Use custom storage for recordings (default: true) +- **`loggingUseCustomStorageEnabled`**: Use custom storage for logs (default: true) +- **`pcapUseCustomStorageEnabled`**: Use custom storage for SIP packet capture (default: true) +- **`recordingPath`**: Custom path for recording storage +- **`loggingPath`**: Custom path for log storage +- **`pcapS3PathPrefix`**: S3 path prefix for PCAP files + +## Squad and Transfer Behavior + +### Dynamic Artifact Control + +In squads with multiple assistants, artifact generation (recording, logging, transcripts) can be controlled per assistant. When assistants are swapped or transferred during a call: + +- **Recording**: Pauses when `recordingEnabled: false` assistant is active, resumes when `recordingEnabled: true` assistant takes over +- **Logging**: Pauses when `loggingEnabled: false` assistant is active, resumes when `loggingEnabled: true` assistant takes over +- **Transcripts**: Pauses when `transcriptPlan.enabled: false` assistant is active, resumes when `transcriptPlan.enabled: true` assistant takes over + +## Transcript Configuration + +### Automatic Transcription + +Configure transcript generation using the `transcriptPlan`: + +```json +{ + "artifactPlan": { + "transcriptPlan": { + "enabled": true, + "assistantName": "Assistant", + "userName": "Customer" + } + } +} +``` + +### Transcript Plan Options + +- **`enabled`**: Enable or disable transcript generation +- **`assistantName`**: Name to use for assistant messages in transcripts +- **`userName`**: Name to use for user messages in transcripts + +### Transcript Features + +- **Real-time transcription**: Transcripts are generated during the call +- **Speaker identification**: Distinguishes between assistant and user messages +- **Timestamps**: Each message includes timing information +- **OpenAI formatting**: Available in `call.artifact.messagesOpenAIFormatted` + +### Transcript Structure + +```json +{ + "callId": "call-123", + "artifact": { + "transcript": [ + { + "role": "assistant", + "message": "Hello! How can I help you today?", + "time": 0.5 + }, + { + "role": "user", + "message": "I need help with my account", + "time": 3.2 + } + ], + "messagesOpenAIFormatted": [ + { + "role": "assistant", + "content": "Hello! How can I help you today?" + }, + { + "role": "user", + "content": "I need help with my account" + } + ] + } +} +``` + +## Logging Configuration + +### Detailed Call Logs + +Enable comprehensive logging for debugging and analysis: + +```json +{ + "artifactPlan": { + "loggingEnabled": true, + "loggingUseCustomStorageEnabled": true, + "loggingPath": "https://your-bucket.s3.amazonaws.com/logs/" + } +} +``` + +### Log Features + +- **Debug information**: Detailed logs for troubleshooting +- **Performance metrics**: Call timing and performance data +- **Error tracking**: Comprehensive error logs and stack traces +- **Workflow execution**: Step-by-step workflow node execution + +### Accessing Logs + +Logs are available through: +- **Dashboard**: View logs in the call details page +- **API**: Access via `call.artifact.logUrl` +- **Custom storage**: Store logs in your S3/GCP bucket + +## Accessing Artifacts ### Via Dashboard 1. Navigate to **Calls** in your Vapi dashboard 2. Select a specific call from the list -3. Click on the **Recording** tab to play or download the audio +3. View artifacts in the **Artifacts** section: + - **Recording**: Play or download the audio recording + - **Transcript**: View the full conversation transcript + - **Logs**: Access detailed call logs for debugging + - **PCAP**: Download SIP packet capture (phone calls only) ### Via API -Retrieve recording URLs programmatically: +Retrieve artifact URLs programmatically: ```typescript import { VapiClient } from "@vapi-ai/server-sdk"; const client = new VapiClient({ token: "your-api-key" }); -// Get call details including recording URL +// Get call details including all artifacts const call = await client.calls.get("call-id"); -console.log("Recording URL:", call.recordingUrl); + +console.log("Recording URL:", call.artifact.recording); +console.log("Transcript:", call.artifact.transcript); +console.log("Log URL:", call.artifact.logUrl); +console.log("PCAP URL:", call.artifact.pcapUrl); +console.log("Messages:", call.artifact.messages); +console.log("Nodes:", call.artifact.nodes); ``` ## Privacy and Compliance @@ -128,6 +406,15 @@ console.log("Recording URL:", call.recordingUrl); - **Data protection** regulations (GDPR, CCPA, etc.) - **Industry standards** (PCI DSS, HIPAA, etc.) +### Built-in Consent Management + +For Enterprise customers, Vapi provides automated consent management through [recording consent plans](/security-and-privacy/recording-consent-plan). This feature automatically: + +- Creates a consent assistant that requests recording permission +- Handles both verbal and stay-on-line consent types +- Only begins recording after consent is granted +- Maintains audit trails of consent decisions + ### Best Practices - **Inform callers** about recording at the start of conversations @@ -141,60 +428,107 @@ console.log("Recording URL:", call.recordingUrl); ## Recording Analysis -### Transcription +### Call Artifacts -Recorded calls are automatically transcribed for analysis: +Use the comprehensive artifact data for analysis: ```json { "callId": "call-123", - "transcript": [ - { - "role": "assistant", - "message": "Hello! How can I help you today?", - "time": 0.5 - }, - { - "role": "user", - "message": "I need help with my account", - "time": 3.2 + "artifact": { + "recording": "https://api.vapi.ai/recordings/call-123.mp3", + "transcript": [ + { + "role": "assistant", + "message": "Hello! How can I help you today?", + "time": 0.5 + }, + { + "role": "user", + "message": "I need help with my account", + "time": 3.2 + } + ], + "logUrl": "https://api.vapi.ai/logs/call-123.json", + "messages": [ + { + "role": "assistant", + "message": "Hello! How can I help you today?" + }, + { + "role": "user", + "message": "I need help with my account" + } + ], + "nodes": [ + { + "name": "greeting", + "messages": ["Hello! How can I help you today?"], + "variables": {} + } + ], + "variableValues": { + "customerName": "John Doe", + "issueType": "account_access" } - ], - "recordingUrl": "https://api.vapi.ai/recordings/call-123.mp3" + } } ``` -### Call Analysis +### Analysis Use Cases -Use recorded data for insights: +Use artifact data for comprehensive insights: -- **Conversation flow** analysis -- **Response quality** evaluation -- **Customer satisfaction** metrics -- **Assistant performance** tracking +- **Conversation flow** analysis using `artifact.nodes` +- **Response quality** evaluation using `artifact.messages` +- **Customer satisfaction** metrics from transcript analysis +- **Assistant performance** tracking using logs and recordings +- **Workflow optimization** using node execution data +- **Variable tracking** using `artifact.variableValues` ## FAQ - - Yes, all recordings are automatically transcribed and available through the API and dashboard. + + Use the `artifactPlan` configuration in your assistant or call settings. Set `recordingEnabled`, `loggingEnabled`, and configure `transcriptPlan.enabled` to `true` to enable all three features. + + + + By default, artifacts are stored securely in Vapi's cloud storage. You can configure custom storage using S3 or Google Cloud Storage with the `recordingPath`, `loggingPath`, and storage control options. + + + + Artifacts are available through the API via `call.artifact.recording`, `call.artifact.transcript`, `call.artifact.logUrl`, and other properties. You can also view them in the Vapi dashboard. - - Default retention is 30 days. You can configure custom retention policies for your account. + + The `transcript` includes timing information and is optimized for conversation analysis. The `messages` property contains the same content but in a simpler format, while `messagesOpenAIFormatted` is structured for OpenAI API compatibility. + + + + Use the `transcriptPlan` configuration with `assistantName` and `userName` properties to customize how speakers are identified in the transcript output. - Yes, you can enable/disable recording at both the assistant level and per individual call. + Yes, you can configure artifact plans at both the assistant level and per individual call. This gives you granular control over what artifacts are generated for each conversation. + + + + PCAP (Packet Capture) is available for phone calls and contains SIP packet data for debugging telephony issues. It's stored in `call.artifact.pcapUrl` when `pcapEnabled` is set to `true`. + + + + Default retention is 30 days for all artifacts. You can configure custom retention policies and use custom storage for longer-term archival. - - Call recording is available in all supported Vapi regions with local data residency options. + + In squads, each assistant can have different artifact settings. Recording, logging, and transcripts pause when an assistant with disabled artifacts is active, and resume when an assistant with enabled artifacts takes over. This allows for privacy-conscious flows like consent collection. ## Next Steps - **[Call Analysis](/assistants/call-analysis)** - Analyze recorded conversations for insights +- **[Recording Consent Plans](/security-and-privacy/recording-consent-plan)** - Automated consent management for Enterprise customers - **[Privacy Compliance](/security-and-privacy/GDPR)** - Ensure GDPR and privacy compliance - **[API Reference](/api-reference/calls/create)** - Explore recording configuration options From 4af2d1c362ef6466c595b6a9bbd74cd43d81c8d9 Mon Sep 17 00:00:00 2001 From: Margarita Gomez Date: Mon, 6 Oct 2025 19:48:11 -0700 Subject: [PATCH 2/3] chore: add processing --- fern/assistants/call-recording.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/assistants/call-recording.mdx b/fern/assistants/call-recording.mdx index 3187ee65b..86a8dd1b8 100644 --- a/fern/assistants/call-recording.mdx +++ b/fern/assistants/call-recording.mdx @@ -23,7 +23,7 @@ Vapi's artifact plan system provides comprehensive call recording, logging, and ## Use Cases -### Payment Flows +### Payment Processing Flows Protect sensitive payment information by using a middle assistant with all artifacts disabled: From 0ee026def1ecbfb4831564d36a33c5cbc7858d31 Mon Sep 17 00:00:00 2001 From: Margarita Gomez Date: Mon, 6 Oct 2025 20:01:49 -0700 Subject: [PATCH 3/3] chore: complement pci docs --- fern/security-and-privacy/PCI.mdx | 169 ++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) diff --git a/fern/security-and-privacy/PCI.mdx b/fern/security-and-privacy/PCI.mdx index 34f4ee7ef..3a6ab8726 100644 --- a/fern/security-and-privacy/PCI.mdx +++ b/fern/security-and-privacy/PCI.mdx @@ -58,6 +58,175 @@ Example configuration for `PCI compliant` assistant is: ``` Note: The default value for `compliancePlan.pciEnabled` is false. Activating this setting aligns your assistant with PCI DSS standards by ensuring data is securely transmitted without being stored on Vapi’s systems. +## Selective Recording with Squads + +For businesses that need to collect payment information while maintaining compliance, you can use **squads** to selectively disable recording, logging, and transcription only during sensitive payment collection phases. This approach allows you to: + +- **Record the beginning and end** of calls for quality assurance +- **Disable all artifacts** during payment data collection +- **Stay compliant** while gathering credit card information +- **Use handoff tools** to seamlessly transfer between assistants +- **Leverage Vapi's logging and trace recording** for non-sensitive portions while staying compliant + +### Payment Collection Squad Example + +Here's a complete squad configuration that demonstrates this approach: + +```json +{ + "name": "Payment Squad Without Recording", + "members": [ + { + "assistant": { + "name": "Assistant 1", + "model": { + "model": "gpt-4o", + "provider": "openai", + "messages": [ + { + "content": "You are a helpful QuickSend assistant. Greet the caller, let them know you'll help them add a new payment method, and then smoothly transfer them to the payment setup assistant.", + "role": "system" + } + ] + }, + "voice": { + "voiceId": "Elliot", + "provider": "vapi" + }, + "transcriber": { + "model": "nova-2", + "provider": "deepgram", + "language": "en" + }, + "keypadInputPlan": { + "enabled": true, + "timeoutSeconds": 10, + "delimiters": [ + "#" + ] + }, + "firstMessage": "Welcome to QuickSend! I'll help you add a new payment method. Let's get started.", + "firstMessageMode": "assistant-speaks-first" + }, + "assistantDestinations": [ + { + "type": "assistant", + "assistantName": "Assistant 2", + "description": "Transfer the caller to the payment setup assistant." + } + ] + }, + { + "assistant": { + "name": "Assistant 2", + "model": { + "model": "gpt-4o", + "provider": "openai", + "messages": [ + { + "content": "You are a payment setup assistant. Ask the caller to enter their new card number followed by the pound (#) key. When you receive it, repeat it back clearly for confirmation. Once confirmed, transfer them to the payment confirmation assistant.", + "role": "system" + } + ] + }, + "artifactPlan": { + "recordingEnabled": false, + "loggingEnabled": false, + "transcriptPlan": { + "enabled": false + } + }, + "voice": { + "voiceId": "Elliot", + "provider": "vapi" + }, + "transcriber": { + "model": "nova-2", + "provider": "deepgram", + "language": "en" + }, + "firstMessage": "Please enter your new card number followed by the POUND key.", + "firstMessageMode": "assistant-speaks-first", + "keypadInputPlan": { + "enabled": true, + "timeoutSeconds": 10, + "delimiters": [ + "#" + ] + } + }, + "assistantDestinations": [ + { + "type": "assistant", + "assistantName": "Assistant 3", + "description": "Transfer the caller to the payment confirmation assistant.", + "contextEngineeringPlan": { + "type": "none" + }, + "variableExtractionPlan": { + "schema": { + "type": "object", + "properties": { + "lastFourDigits": { + "type": "string", + "description": "last four digits of the card the user gave as input" + } + } + } + } + } + ] + }, + { + "assistant": { + "name": "Assistant 3", + "model": { + "model": "gpt-4o", + "provider": "openai", + "messages": [ + { + "content": "You are a payment confirmation assistant. Thank the caller for providing their card number. Read out the last four digits to them and confirm that they are correct. Once confirmed, let the caller know the payment method has been added successfully and close the conversation politely. Last four digits are {{lastFourDigits}}", + "role": "system" + } + ] + }, + "voice": { + "voiceId": "Elliot", + "provider": "vapi" + }, + "transcriber": { + "model": "nova-2", + "provider": "deepgram", + "language": "en" + }, + "firstMessage": "Thanks for providing your card number. Do you want to proceed with your payment?", + "firstMessageMode": "assistant-speaks-first" + } + } + ] +} +``` + +### How This Squad Works + +1. **Assistant 1** (Greeting): Records and logs the initial conversation +2. **Assistant 2** (Payment Collection): **Disables all artifacts** using `artifactPlan` while collecting credit card data via keypad input +3. **Assistant 3** (Confirmation): Records and logs the final confirmation + +The key component is the `artifactPlan` in Assistant 2: + +```json +"artifactPlan": { + "recordingEnabled": false, + "loggingEnabled": false, + "transcriptPlan": { + "enabled": false + } +} +``` + +This ensures that sensitive payment information is never recorded, logged, or transcribed, while still allowing you to maintain call quality data for the non-sensitive portions of the conversation. + ## Can PCI be used alongside HIPAA? Yes, you can enable both HIPAA and PCI compliance for an assistant. In this case, the restrictions from both compliances will apply, meaning that no recordings or transcripts will be stored or transmitted, even if you have specified cloud storage endpoints or webhooks for storing transcripts.