Skip to main content

​
Hold / Resume

The Hold / Resume tool lets your voice agent put the caller on hold while it processes a request, looks up information, or waits for an external API response. The agent plays a configurable hold message, then resumes with a return message.

​
How It Works

Caller: "Can you check if my order has shipped?"
Agent: "Let me look that up for you. I'll put you on a brief hold."
-> Agent calls put_caller_on_hold
-> Hold message plays: "Please hold while I check your order status."
-> Agent queries the order system
-> Agent calls resume_from_hold
-> Resume message plays: "Thanks for holding!"
Agent: "Great news - your order shipped yesterday and is arriving tomorrow."

​
Configuration

{
  "holdEnabled": true,
  "holdMessage": "Please hold while I look into that for you.",
  "holdResumeMessage": "Thank you for holding. I have your information now.",
  "holdMusicUrl": ""
}
SettingTypeDefaultDescription
holdEnabledbooleanfalseEnable hold/resume capability
holdMessagestring"Please hold..."Message spoken when putting caller on hold
holdResumeMessagestring"Thanks for holding."Message spoken when resuming
holdMusicUrlstring—Optional hold music URL (audio file)

​
LLM Tools

​
put_caller_on_hold

Put the caller on hold. The configured hold message is spoken automatically. 
Parameters:
  reason: string (why the caller is being placed on hold)

Returns: "Caller is now on hold. Reason: {reason}. Call resume_from_hold when ready."

​
resume_from_hold

Take the caller off hold. The configured resume message is spoken automatically. 
Parameters: none

Returns: "Call resumed. Continue helping the caller."

​
Example — Create Agent with Hold / Resume

curl -X POST https://api.thinnest.ai/v1/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Lookup Agent",
    "model": "gpt-4o-mini",
    "instructions": "You help customers check order status. When you need to look up information, put the caller on hold first. Always explain why. Resume as soon as you have the answer.",
    "voiceEnabled": true,
    "transcriber": { "provider": "deepgram", "model": "nova-2-conversationalai" },
    "voice": { "provider": "deepgram", "voiceId": "aura-2-thalia-en" },
    "holdEnabled": true,
    "holdMessage": "Please hold while I check your order status.",
    "holdResumeMessage": "Thank you for holding. I have your information now."
  }'