Skip to main content

Disconnect & transfer

These are the voice-only tools that let your phone assistant end a call cleanly, forward it to another number, or bridge it to a different channel (web form, WhatsApp, chat widget) to capture data the voice agent can't collect by speaking. They only work during active voice calls — they have no effect on chat, SMS, or webhook conversations.

What you can do with these tools​

  • End the call when the conversation is done.
  • Forward the call to a pre-configured destination number — for after-hours routing, department transfers, or human escalation.
  • Bridge the caller to a sub-conversation on another channel — useful for collecting structured data (long intake forms, secure inputs) that voice can't handle.

Business use cases​

After-hours forwarding to a mobile number​

A roofing contractor's voice assistant answers calls from 6pm onwards. Routine inquiries (rates, service area, scheduling availability) get answered by the agent. Anything urgent — water actively coming through the ceiling — the assistant says "Let me get the owner on the line" and calls forward_call. The configured forwarding destination is the owner's mobile. The caller is bridged through; the owner picks up; conversation continues human-to-human.

Department routing during a customer-service call​

A SaaS company has separate phone trees for billing, technical support, and account management. They create three Insighto tool connections — one for each — each pre-configured with the destination phone for that department. All three are attached to the inbound assistant. The system prompt tells the agent: "For billing questions, call forward_to_billing. For technical issues, call forward_to_tech_support." The agent picks the right tool based on the caller's question; the call is forwarded to the right team.

Clean call-end after a completed booking​

A dental practice's voice agent has just finished booking a new patient appointment. The caller says "Thanks, that's all." The assistant says "Thanks for calling ABC Dental — have a great day." Then calls disconnect_call. The line drops cleanly; the call recording stops; the post-call workflow kicks in.

Smart intake handoff mid-call​

A medical practice's voice agent answers a new-patient call. The caller wants to book — but the agent needs a 30-field intake form (insurance, allergies, medications, history). Reading all 30 fields aloud would be brutal. Instead the agent collects the basics by voice (name, DOB, phone, reason for visit), then says "I'm texting you our intake form — fill it out and I'll see it on my end." It calls initiate_handoff, which texts the caller a secure web-form link. The caller stays on the call while filling the form on their phone. The agent calls check_handoff periodically; once the form is submitted, the values come back to the voice agent and the conversation continues with the captured data.

Voice-only​

All four functions require an active phone call. They have no effect on chat, SMS, or webhook conversations — invoking them outside a voice context returns an error.

How a transfer works​

disconnect_call​

Ends the active call cleanly.

  • Arguments — none.
  • Returns — confirmation from the telephony provider.

Important: disconnect_call has no "goodbye message" argument. The assistant has to say its sign-off in its normal spoken turn first, then call disconnect_call on the very next turn. Pattern:

Before ending the call, always say "Thanks for calling ABC Dental — have a great day". Then call disconnect_call. Only end the call if the customer has explicitly indicated they're done.

Hanging up too eagerly is the most common voice-agent complaint. The disconnect tool is fast — once invoked, the line drops in under a second.

forward_call​

Forwards the active call to a pre-configured destination number.

  • Arguments — none. The destination number is set on the tool connection itself, not passed by the model.
  • Returns — confirmation from the telephony provider.

The destination is configured at setup time on the connection. The model can't pick an arbitrary number to forward to — by design. If you want department-based routing, create one connection per destination, name them descriptively ("Forward — Billing", "Forward — Tech Support"), attach all of them to the assistant, and let the model pick between the named functions in the prompt:

For billing questions, call forward_to_billing. For technical questions, call forward_to_tech_support. For anything else, try to handle it yourself.

Cold vs warm transfer​

The current implementation does a cold transfer — the assistant says its pre-transfer line, then the call is bridged to the destination and the assistant drops off. The receiver picks up cold; they didn't hear the original conversation.

If you need warm-transfer behavior (caller stays on hold while the destination is briefed first), that depends on the underlying telephony provider's capabilities and isn't a flag on this tool today. For a warm-transfer experience, the receiver has to read the conversation summary in your post-call notification (e.g. in the HubSpot ticket the agent opened beforehand).

initiate_handoff and check_handoff — smart handoff to another channel​

These let a voice agent bridge to a non-voice channel mid-call so the customer can fill in something the voice agent can't ask for verbally (long forms, file uploads, secure inputs).

initiate_handoff​

Sends the caller a link (via SMS or WhatsApp template) to a pre-configured sub-conversation on another channel.

  • Arguments
    • phone_number (string, optional) — recipient phone for the link. If omitted, the contact already known to the assistant is used.
  • Returns — "Handoff completed successfully." on send.

check_handoff​

Checks whether the customer has finished the bridged-channel interaction (typically: form submitted, file uploaded).

  • Arguments — none.
  • Returns — the captured field values if submission is complete; "Form submission not yet received." otherwise.

The flow: the voice agent calls initiate_handoff, says "I've texted you a link — open it and complete the form, I'll wait." It then politely chats while periodically calling check_handoff. Once the form comes back submitted, the field values are returned to the agent and it continues the conversation with the captured data.

This requires configuring the smart handoff settings on the tool connection (target channel, form ID, message body template). Without that configuration, initiate_handoff returns "Handoff not configured for this call."

Use case combinations​

After-hours mode + forwarding​

Combine forward_call with a Workflow that toggles the assistant on/off by time-of-day. The assistant runs only after business hours. The system prompt's escalation path is forward_call to the on-call mobile. Inside business hours, the workflow disables the assistant entirely; calls go to the human team.

Smart intake during a single call​

A clinic uses initiate_handoff to collect new-patient intake mid-call. The voice agent does the warm part (greeting, basic ID, reason for visit). It hands off via SMS to a web form for the long intake. Once the form's submitted, the agent resumes the voice call with all the structured data in hand and finishes the booking.

Department escalation with a ticket​

The assistant opens a HubSpot ticket with a summary of the conversation before calling forward_call. The receiver in the destination department can pull up the ticket while the call is ringing through.

Billing during a transfer​

Once forward_call runs, your telephony provider's per-minute cost continues for the bridged call's duration. The LLM, STT, and TTS costs stop the moment the assistant disconnects from the audio path — there's nothing for them to do once it's a human-to-human call.

What the caller hears during a transfer​

  1. The assistant's pre-transfer line in its usual voice ("One moment, connecting you to billing").
  2. A brief silence (typically half a second to two seconds depending on provider).
  3. Ringing on the destination line.
  4. The destination party picks up; the assistant is gone.

Test the end-to-end experience before launching. The silence between the assistant's last words and the ringing can feel awkward if the pre-transfer line is too short — give the caller something to chew on for that half-second.

Failure modes​

  • No call provider context — disconnect_call and forward_call return errors when invoked from a non-voice conversation. Means the tool was wrongly attached to a chat-only assistant.
  • Forwarding number not configured — forward_call errors at the provider. Set the destination number on the connection.
  • Smart handoff not configured — initiate_handoff returns "Handoff not configured for this call." Open the connection settings and configure the target channel and message body.
  • Bridged form never submitted — check_handoff keeps returning "Form submission not yet received." The agent should give up after a few polls and offer to take the info by voice instead.

Provider differences​

The underlying telephony provider (Twilio, Plivo, Telnyx) affects how transfers behave at the carrier level — SIP REFER vs PSTN bridging, custom SIP headers, etc. Retest forwarding flows whenever you switch providers.

Where to next​

  • Pair with SMS to text a callback number before transferring.
  • Use Workflows to enable/disable the assistant on a schedule (after-hours mode).
  • Open a HubSpot ticket before forwarding so the receiver has context.