Unanswered Outbound Call Events – Toku

The HeroCare x Toku Contact Centre widget is an embeddable that connects HeroCare with Toku. Agents log in to the Toku widget inside HeroCare to:

Receive inbound calls that automatically create or update HeroCare tickets
Make outbound calls using Click‑2‑Call from HeroCare tickets
See and update their call status in HeroCare while Toku manages the actual call handling and events

This article explains how outbound calls work between HeroCare and Toku Contact Centre, and why some outbound calls can cause errors when trying to retrieve call recordings.

Not every outbound call is actually answered. For calls that just ring and never connect (ring‑no‑answer, busy, cancelled), there is no useful audio to retrieve. If the system still tries to fetch a recording for these unanswered calls, it can run into API errors in HeroCare.

To prevent this, HeroCare can use a timestamp from the Toku outbound webhook (answer_timestamp) to tell if the call was really answered. When answer_timestamp is missing or empty, the call is treated as not answered, and the system skips the recording retrieval API call. When answer_timestamp is present, the call is treated as answered, and the recording can safely be fetched and attached to the HeroCare ticket.

1. Context: HeroCare x Toku Contact Centre

Outbound Call Flow

For outbound calls, Toku sends webhook events to HeroCare with call details at different stages of the call:

1. Call start event (ringing)

A webhook with the initial call details is sent:

from
to
status
callId
ticketId (existing HeroCare ticket ID)
direction (e.g. outbound)
timestamp (call event time)
ringing_timestamp
answer_timestamp (if the call is answered)
recording_id
agent_email

2. Call end (disconnect) event

When the call ends, another webhook is sent with the end time and final status.
At this point, if the call was answered, the system can use the recording_id to make an API request to retrieve the call recording and store it in HeroCare’s S3 bucket on AWS.

Sample Outbound Event Payload

Below is an example outbound call event payload from Toku:

{"from":"fach@outlook.com",
"to":"505222",
"status":"completed",
"callId":"7332731196",
"ticketId":"d69f6a72-00cd-4ad9-b386-a5aa6cc53f0d",
"direction":"outbound",
"timestamp":"2025-10-24T01:22:55.412Z",
"ringing_timestamp":"2025-10-24T01:22:53.000Z",
"answer_timestamp":"2025-10-24T01:22:53.000Z", 
"agent_email":"fach@outlook.com",
"recording_id":"7332731196"}

2. Recording Retrieval for Unanswered Outbound Calls

Problem

For outbound calls from HeroCare (via Toku Click‑2‑Call), Toku sends call events to HeroCare with a recording_id.
In the current behaviour, HeroCare (or the consuming service) attempts to retrieve a recording via API.

For unanswered outbound calls, this causes:

The dial attempt never connects to the end user (ring‑no‑answer, busy, cancelled).
There is no actual call audio recorded.
The integration still calls the recording retrieval API, which often returns errors.

Root Cause

Unanswered outbound calls do not have an recording file.
It tries to retrieve a non‑existent/invalid recording.

Workaround

Use the answer_timestamp field in the outbound webhook payload to decide whether to call the recording API.

Business Rule

If answer_timestamp is empty ("") → treat as unanswered call → do not send the recording retrieval API request, even if recording_id is present.
If answer_timestamp is present (valid datetime) → call was answered → safe to call the recording retrieval API using recording_id.

This prevents errors for outbound calls that were never connected and have no meaningful audio.

API Response Details

Unanswered outbound calls

{"from":"fach@outlook.com",
"to":"50522784442",
"status":"completed",
"callId":"7332731196",
"ticketId":"d69f6a72-00cd-4ad9-b386-a5aa6cc53f0d",
"direction":"outbound",
"timestamp":"2025-10-24T01:22:55.412Z",
"ringing_timestamp":"2025-10-24T01:22:53.000Z",
"answer_timestamp":"", --->  “Ignore recording Retrieval”
"agent_email":"fach.ext@outlook.com",
"recording_id":"7332731196"}