Phones - Calls

Upload call recording file with metadata

Upload a call recording file along with linked metadata for storage and processing. The system will store the recording, generate transcriptions, and create AI analysis.

Required Fields:

  • recording: Audio file (multipart/form-data, supported formats: WAV, MP3, OGG)
  • callStart: Call start timestamp (ISO 8601 format)
  • companyPhoneNumber: Your company's phone number
  • contactPhoneNumber: Customer/contact phone number
  • callDirection: "inbound" or "outbound"

Optional Fields:

  • callId: Link to existing call record
  • agentId: Contact with specific agent
  • duration: Call duration in seconds
  • notes: Additional notes about the call
  • companyEmailAddress: Company email
  • contactEmailAddress: Contact email
  • companyTimezone: Timezone for timestamps

Processing:

  • Recording is stored securely in cloud storage
  • Automatic transcription is generated
  • AI analysis creates call summary and insights
  • Metadata is indexed for search and reporting

Use Cases:

  • Import recordings from external phone systems
  • Backup call recordings for compliance
  • Add historical calls to Voice Logica for analysis
  • Integrate third-party telephony systems
post/api/v1/phones/calls/upload-recording

Request

  • Base URL: https://api.voicelogica.ai
  • URL: https://api.voicelogica.ai/api/v1/phones/calls/upload-recording
  • Auth: API key in header x-api-key

Headers

x-api-keystring required

Your API key for authentication. Required for all endpoints.

x-company-idstring

Optional company ID for resellers. When provided, the API request will operate on behalf of the specified subsidiary company. The API key must have access to the specified company.

Response

Call recording uploaded successfully

idstring required

Unique identifier

createdAtstring date-time required

Creation timestamp

activeboolean required

Whether the entity is active

createdBystring required

Name of the user who created the entity

createdByIdstring required

ID of the user who created the entity

modifiedAtstring date-time

ISO 8601 date string

modifiedBystring

Name of the user who last modified the entity

modifiedByIdstring

ID of the user who last modified the entity

companyIdstring required

Company identifier

companyobject

Any valid JSON value

groupIdsstring[]

Linked group IDs

callIdstring required

Call identifier

callerIdstring required

Caller identifier

contactIdstring

Contact identifier

userIdstring

User identifier

userNamestring

Display name of userId — stamped on list responses so grids need no second lookup

voipPhoneIdstring

VoIP phone identifier

sipTrunkIdstring

SIP trunk identifier (for trunk-routed calls)

agentIdstring

Agent identifier

agentVersionIdstring

Agent version/staging snapshot used for this call

agentVersionNumbernumber

Version number dialed (0 = staging); omitted for prod

agentVersionKind'prod' | 'staging' | 'version'

prod, or a named version

agentVersionDescriptionstring

Version name shown on the call when not Prod

phoneNumberstring required

Phone number

status'failed' | 'cancelled' | 'answered_elsewhere' | 'transferring' | 'transferred' | 'failed_during_call' | 'to_be_processed' | 'trying' | 'ringing' | 'busy' | 'missed' | 'in_call' | 'answered' | 'voice_mail' | 'session_progress' | 'scheduled' required

Call status

recordingEnabledboolean

Whether recording was enabled by policy when the call ran. false → messages/aiDialogue/transcription files are withheld (summary and post-analysis remain); absent on older calls (treated as recorded).

recordingFileIdstring

Recording file identifier

humanRecordingFileIdstring

Human recording file identifier

originalRecordingFileIdstring

Original (untranslated) recording file identifier, present when live translation was active

transcriptionFileIdstring

Transcription file identifier

humanTranscriptionFileIdstring

Human transcription file identifier

endCallReason'caller_hungup' | 'user_hungup' | 'caller_voice_mail' | 'caller_does_not_exist' | 'wrong_set_number' | 'call_maximum_time_reached' | 'caller_unresponsive_after_nudges' | 'call_transferred' | 'caller_busy' | 'caller_declined' | 'no_channels' | 'unavailable' | 'voip_phone_offline' | 'voip_phone_service_failed' | 'no_agent_id' | 'phone_number_not_found' | 'agent_not_found' | 'no_remote_rtp_address' | 'no_selected_codec' | 'no_remote_rtp_port' | 'voip_provider_issue' | 'inbound_calls_blocked' | 'no_rtp_stream' | 'no_pickup_after_ringing_max_seconds' | 'sdp_error' | 'not_acceptable_here' | 'voip_temporary_issue' | 'voip_phone_not_exist' | 'caller_does_not_speak' | 'message_left' | 'no_channels_available_in_plan' | 'forbidden' | 'failed_to_connect' | 'call_stuck' | 'no_seconds_available_in_plan' | 'maximum_time' | 'subscription_issue' | 'incorect_code' | 'transfer_request_true' | 'transfer_request_false' | 'no_voip_connection' | 'insufficient_balance_in_voip_provider' | 'caller_called_back' | 'campaign_not_active' | 'outside_campaign_schedule' | 'agent_handoff' | 'off_hours_welcome_message' | 'answered_elsewhere'

End call reason

durationnumber

Call duration in seconds

hertznumber required

Audio frequency in hertz

humanInCallboolean

Whether human is in call

summarystring

Call summary

shortSummarystring

One-line summary for call cards

callDirection'inbound' | 'outbound' required

Call direction

transcriptionCostnumber

Transcription cost

totalCostnumber

Total cost

consumerCostnumber

Total Cost of the Call for the Consumer

dynamicVariablesobject

Dynamic variables

source'app' | 'api' | 'web' | 'mcp' | 'phone' | 'mobile' | 'mobile-bridge' | 'scheduled' | 'waitlist' | 'campaign' | 'workflow' | 'recording' | 'transfer' | 'google-meet' | 'meeting' | 'whatsapp' | 'viber' | 'telegram' | 'instagram' | 'instagram_comment' | 'messenger' | 'messenger_comment' | 'email' | 'vicidial-seat' | 'campaign-seat' | 'vicidial' | 'phone-verification'

Source of the call

mobileTransferKind'pin_bridge' | 'busy_forward' | 'callback' | 'no_answer_forward'

Mobile transfer mode: pin_bridge or busy_forward

mobileUserIdstring

Mobile seat user id for PIN bridge / busy-forward

mobileTransferAiFallbackboolean

Busy-forward fell back to AI for the waiting caller

mobileTransferAiFallbackReasonstring

Why busy-forward fell back to AI

messageOnlyboolean

Personal assistant with no voice minutes: welcome message, then recorded the caller only (analysis minutes)

mobileBridgeNoDestLegboolean

Hidden bridge leg whose transfer never produced a destination leg — kept visible so the call is not lost from the grid

meetRecordingDriveFileIdstring

Google Drive file ID of the Meet recording (only for source=google-meet)

meetAlternateDriveFileIdsstring[]

Other teammates Drive copies of the same Meet recording

meetConferenceRecordIdstring

Google Meet conferenceRecord resource name (only for source=google-meet)

meetParticipantEmailsstring[]

Resolved participant email addresses (only for source=google-meet)

meetOrganizerEmailstring

Email of the meeting organizer (only for source=google-meet)

analysedByAi'pending' | 'failed' | 'created' | 'completed'

Whether the call was analysed by AI

metadataobject

Metadata - Common examples include: appointmentReminder (true/false), reminderMinutes (number as string), eventId, eventIds (JSON string), calendarId, contactId, agentId, callId, voipPhoneId, phoneNumber, totalAppointments (number as string), callBack (true/false), viewUrl, viewHumanRecordingUrl, priority (high/medium/low), category (support/sales/billing), source (inbound/outbound), campaign_type, lead_score

superVariablesobject

Super variables - Typed key-value pairs with placeholders for advanced call data

contextForAistring

Context for AI

llmConversationIdstring

LLM conversation ID for maintaining stateful context across provider APIs (Gemini Interactions, OpenAI Responses, etc.)

postAnalysisResultsobject

Post analysis results - AI-generated analysis data from call processing (includes scalars and arrays such as email_recipients / email_cc_recipients / sms_recipients)

encryptedIdstring

Encrypted identifier - Encrypted call identifier for security

campaignIdstring

Campaign identifier

campaignLeadIdstring

Campaign lead identifier

rtpPortnumber

RTP port

rtpIpstring

RTP IP address

startAtstring date-time

ISO 8601 date string

endAtstring date-time

ISO 8601 date string

contactobject

Any valid JSON value

userobject

Any valid JSON value

voipPhoneobject

Any valid JSON value

callInformationobject

Call information

agentobject

Any valid JSON value

recordingFileobject

Any valid JSON value

humanRecordingFileobject

Any valid JSON value

originalRecordingFileobject

Any valid JSON value

transcriptionFileobject

Any valid JSON value

humanTranscriptionFileobject

Any valid JSON value

campaignobject

Any valid JSON value

campaignLeadobject

Any valid JSON value

scheduledAtstring date-time

ISO 8601 date string

retriesnumber

Number of retries

maxRetriesnumber

Maximum number of retries

retryDelayMinutesnumber

Retry delay in minutes

originalCallIdstring

Original call identifier

scheduledReason'retry' | 'customer_callback' | 'dropped_call'

Why this call was scheduled: retry, customer_callback (the person asked to be called back) or dropped_call

previousCallIdstring

For agent-handoff legs: the _id of the previous Call doc that was finalized when the agent identity was swapped. Walking the chain backwards reconstructs the full per-agent timeline.

useAntiHarassmentProtectionboolean

Whether to use anti-harassment protections (daily limits, cooldown, etc.)

overrideTimeRestrictionboolean

Whether to override time restrictions

overrideDayRestrictionboolean

Whether to override day restrictions

isWelcomeMessageAIGeneratedboolean

Whether the welcome message is AI generated

welcomeMessageOverridestring

Per-call welcome message spoken verbatim by the answering agent, overriding its configured first message.

hostedOutboundboolean

Whether this outbound call used the company/distributor trunk with a verified caller ID.

fallbackForUserIdstring

When the AI answered as a direct-to-extension fallback, the user the call was originally routed to. Scopes AI-created callbacks to that user.

useOwnApiKeyboolean

Whether the clients is using their own API key

rescheduledboolean

Whether the call is scheduled

rescheduledAtstring date-time

ISO 8601 date string

funnelStatus'resolved' | 'escalated' | 'dropped' | 'early_abandon' | 'human_handled' | 'technical_issue' | 'frustrated_hung_up'

High-level funnel status for analytics (resolved, escalated, dropped, pending)

resolutionStatus'converted' | 'appointment_scheduled' | 'lead_qualified' | 'information_provided' | 'issue_resolved' | 'partially_resolved' | 'callback_requested' | 'contact_unavailable' | 'not_interested' | 'do_not_call' | 'wrong_contact'

Detailed resolution outcome of the call

escalationReason'complex_query' | 'user_requested' | 'user_frustration' | 'knowledge_gap' | 'sensitive_data_required' | 'verification_failed' | 'language_barrier' | 'audio_quality_issues' | 'vip_customer'

Reason why call was escalated to human (only applicable if escalated)

conversionStatus'converted' | 'not_converted'

Whether business goal was achieved (converted, not_converted)

callCategoryIdsstring[]

Array of call category identifiers for this call

callCategoriesobject[]

Call categories information (populated from CallCategory)

postCallAnalysis'not_started' | 'in_progress' | 'failed' | 'completed'

Status of post call analysis (not-started, in_progress, failed, completed)

evaluatedAtstring date-time

ISO 8601 date string

planIdstring

The subscription plan ID active at the time of the call

resellerIdstring

The reseller company ID linked with the customer at the time of the call

callHandler'voip_phone' | 'pbx_softphone' | 'pbx_trunk' | 'extension'

Which system processed the call (voip_phone, pbx_softphone, pbx_trunk)

appClientParticipantIdstring

Rust participant sub-call ID for the app client (used to remove it on transfer)

isPrivateboolean

Private call — visible only to its own user and super-admins

legalHoldboolean

Legal hold — retention and deletion skip this call until released

analysisOnDemandboolean

Analysis on demand: the call was recorded but not transcribed or analysed; POST /phones/call/:id/analyze runs it

analysisRequestedAtstring date-time

ISO 8601 date string

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "active": true,
  "createdBy": "John Doe",
  "createdById": "123",
  "modifiedAt": "2024-01-15T10:30:00.000Z",
  "modifiedBy": "Jane Doe",
  "modifiedById": "456",
  "companyId": "507f1f77bcf86cd799439012",
  "callId": "call_123456789",
  "callerId": "caller_987654321",
  "contactId": "contact_456789",
  "userId": "user_101112",
  "voipPhoneId": "voip_131415",
  "agentId": "agent_161718",
  "phoneNumber": "+1234567890",
  "status": "in_call",
  "messages": [],
  "recordingFileId": "recording_192021",
  "humanRecordingFileId": "human_recording_232425",
  "transcriptionFileId": "transcription_222324",
  "humanTranscriptionFileId": "human_transcription_262728",
  "endCallReason": "caller_hungup",
  "duration": 180,
  "hertz": 8000,
  "humanInCall": true,
  "summary": "Customer called about billing issue",
  "callDirection": "inbound",
  "transcriptionCost": 0.03,
  "totalCost": 0.2,
  "consumerCost": 0.1,
  "dynamicVariables": {
    "customer_name": "John Doe",
    "order_id": "ORD123"
  },
  "metadata": {
    "priority": "high",
    "category": "support",
    "appointmentReminder": "true",
    "reminderMinutes": "30",
    "eventId": "event_123",
    "calendarId": "calendar_456",
    "callBack": "false",
    "viewUrl": "https://example.com/call/123",
    "viewHumanRecordingUrl": "https://example.com/call/123/human",
    "source": "inbound",
    "campaign_type": "follow_up"
  },
  "superVariables": {
    "customer_name": {
      "placeholder": "{{customer_name}}",
      "value": "John Doe",
      "type": "text"
    },
    "appointment_date": {
      "placeholder": "{{appointment_date}}",
      "value": "2024-01-15",
      "type": "date"
    },
    "is_vip": {
      "placeholder": "{{is_vip}}",
      "value": "true",
      "type": "boolean"
    }
  },
  "contextForAi": "Customer is calling about a billing issue from last month",
  "postAnalysisResults": {
    "sentiment": "positive",
    "intent": "support"
  },
  "campaignId": "campaign_252627",
  "campaignLeadId": "lead_282930",
  "rtpPort": 10000,
  "rtpIp": "192.168.1.100",
  "startAt": "2024-01-15T10:30:00.000Z",
  "endAt": "2024-01-15T10:33:00.000Z",
  "scheduledAt": "2024-01-15T10:30:00.000Z",
  "retries": 0,
  "maxRetries": 3,
  "retryDelayMinutes": 10,
  "callInformation": {
    "priority": "high",
    "category": "support"
  },
  "transferringStatus": "transferring",
  "postCallAnalysis": "completed",
  "postCallAnalysisStages": [
    {
      "action": "summary",
      "status": "completed",
      "retryCount": 0,
      "lastAttemptAt": "2026-10-20T12:52:40.161Z"
    }
  ]
}

Changes