Skip to main content

How to send AI call events to Volie

How AI platforms POST hangup, warm-transfer, ai-handled, and ai-abandon events to the Volie AI Listener API

S
Written by Sadie Timmons

How to send AI call events to Volie

You will send real-time call events from your AI voice assistant to Volie so missed calls, warm transfers, AI-handled outcomes, and abandoned interactions appear in the correct dealership’s call history and agent workflows.

Before you start

Before you send AI call events to Volie:

  • Complete How to set up Volie AI Assistant integration (credentials and organization VIDs)

  • Send requests as Content-Type: application/json with HTTP Basic Authentication

  • Use caller phone numbers in E.164 format (for example +15551234567)

Definitions

These terms appear when you send AI call events to Volie:

Term

Meaning

Event type

The event_info.event_type value that tells Volie how to process the call (hangup, warm-transfer, ai-handled, or ai-abandon).

call_id

Your platform’s unique identifier for the call session. Send the same value on retries for the same logical call.

Warm transfer

A live handoff where your AI sends a warm-transfer event and transfers the active call to the Volie phone number Volie provided for that organization.

Supported event types

Volie AI Assistant integration supports these primary event types:

Event type

When to send

What Volie does

hangup

The caller disconnects before a live agent answers (including connection failures during greeting)

Creates a missed call record and links call details for dealership follow-up

warm-transfer

Your AI determines the caller needs a live agent

Pushes call context to the answering agent and links the transferred call

ai-handled

Your AI fully resolves the caller’s request without a human

Logs the completed AI interaction with disposition and summary data

ai-abandon

The caller hangs up after requesting human help but before the transfer completes

Logs the abandoned interaction for visibility alongside agent-handled calls

Steps

Follow these steps to send AI call events to Volie:

  1. Build a JSON payload with three sections: event_info (required), event_summary (recommended), and transcript (optional).

  2. In event_info, set event_type to hangup, warm-transfer, ai-handled, or ai-abandon.

  3. In event_info, set vid to the organization VID from the Organization Discovery API. Volie also accepts subscription_key as an alias for vid.

  4. In event_info, set call_id to your unique call or session ID and caller_origin_phone to the customer phone in E.164 format.

  5. Add recommended caller fields when available: event_time (ISO 8601 UTC), caller_first_name, caller_last_name, and customer_timezone (IANA timezone such as America/Chicago).

  6. In event_summary, include context that helps agents and reporting: caller_request, call_outcome, summary, optional vehicle (year, make, model), tags, campaign_vid, and recording_url when you have a reachable recording link.

  7. Optionally add a transcript array with objects containing line_type (ai or customer) and text for each spoken line.

  8. POST the payload to POST https://api.volie.com/ai_listener/events. Alternate endpoint with the same handler: POST https://api.volie.com/auto_assistant_ai_listener/.

  9. Include HTTP Basic Authentication on every request. Set Content-Type: application/json. Optionally send X-Request-Id (unique per logical delivery), X-AI-Partner, and User-Agent for auditing.

  10. For warm-transfer events, transfer the live call to the Volie phone number Volie provided for that organization immediately before or when you send the event so Volie can match the active call.

  11. Treat HTTP 200 OK with response body {"Data":"ok"} as acceptance. Volie may continue processing asynchronously after the response.

Response codes

Volie AI Assistant integration returns these HTTP status codes:

Code

Meaning

Typical cause

200 OK

Event accepted

Payload validated for your AI assistant and organization

400 Bad Request

Event rejected

Malformed JSON, invalid event_type, or missing required fields

401 Unauthorized

Authentication failed

Missing or incorrect Basic Auth credentials

403 Forbidden

Organization not allowed

vid is not linked to your authenticated AI assistant

409 Conflict

Duplicate delivery

Same X-Request-Id already used for your AI assistant (not reprocessed)

500 Internal Server Error

Server error

Contact [email protected] with X-Request-Id and timestamp

Error responses use JSON with a Data string describing the issue (for example {"Data":"vid or subscription_key is required"}).

Optional: Receive webhooks from Volie

If Volie registered outbound webhook URLs on your AI assistant record, Volie can POST updates back to your platform:

New Call — Sent when a call transferred to Volie completes, or when Volie places a return call for a previously missed AI-handled call and that call completes. The payload includes call timing, disposition fields, customer and organization details, appointment fields when applicable, and partner_call_id / partner_orginating_call_id to correlate with your call_id.

New Pulse — Sent when a transferred or returned call is processed by Pulse. The payload includes AI disposition, customer sentiment, assessment items, call transcription, and flags when present.

Design your webhook handler to respond successfully even when processing continues asynchronously, and contact [email protected] to register or update webhook URLs.

What success looks like

When you send AI call events to Volie successfully, Volie returns HTTP 200 OK with {"Data":"ok"} and the interaction appears in the dealership’s Volie call workflow (missed call queue, live agent context on warm transfer, or completed AI call log for ai-handled). If warm-transfer context does not appear for an agent, confirm the live call reached the Volie transfer number and that the caller_origin_phone in the event matches the active inbound call.

Limitations

Volie AI Assistant integration has these verified limits when sending events:

  • Volie ignores unknown keys in the JSON body (including legacy fields such as transport_type and transfer_type inside event_summary).

  • Duplicate X-Request-Id values for the same AI assistant return 409 Conflict and are not processed twice, though Volie still logs the attempt.

  • recording_url must be reachable by Volie if you include it; broken links do not block event acceptance but recordings may be unavailable in Volie.

Common questions

Which endpoint should my AI platform use?

Send AI call events to POST https://api.volie.com/ai_listener/events. The POST https://api.volie.com/auto_assistant_ai_listener/ endpoint uses the same authentication, payload format, and processing.

What is the difference between hangup and ai-abandon?

Send hangup when the caller disconnects before your AI completes the interaction or before a transfer (for example they drop during the greeting). Send ai-abandon when the caller requested human assistance but hung up before the warm transfer to Volie finished.

How do I safely retry a failed event POST?

Reuse the same X-Request-Id header value only when retrying the same logical event. Use a new X-Request-Id for each new call or new event type. A duplicate id returns 409 Conflict without double-processing.

Related articles

  • How to set up Volie AI Assistant integration

Did this answer your question?

Related Articles