mod_dptools: sched hangup
Table of Contents (click to expand)
0. About
The sched_hangup application allows you to schedule a hangup action for a call, basically to limit call duration.
TODO How to cancel?
sched_cancel only seems to work for sched_transfer and sched_broadcast. (sched_cancel needs a task or group ID, and only the latter two set the ID in the session, I tested.)
0.1 Abort sched_cancel workaround
Couldn't find a solution, but this workaround effectively solved the problem:
Set up sched_transfer to a non-existent extension, which will result in a hangup with
No route, Aborting, unless aborted with sched_cancel.
Below is a Lua example, but this strategy would work in the dialplan just the same because the sched_* commands are all dialplan applications (i.e., part of mod_dptools).
session:execute("sched_transfer", "+600 9999 XML default")
-- ...
local lsi = session:getVariable("last_sched_id")
session:execute("sched_cancel", tostring(lsi))
1. Syntax
In the dialplan
<action application="sched_hangup" data="[+]<time>[ <hangup_cause>]"/>
As an API call
sched_hangup [+]<time> <uuid>[ <hangup_cause>]"
| Parameter | Description | Examples |
|---|---|---|
| [+]<time> | Time in seconds.If used with + then the call will be hung up after that number of seconds.If used without + then the given value is considered the number of seconds since the epoch, 1970-01-01 00:00:00 UTC | +60 (hang up after 1 minute)2003336820 (hang up at Jun 25 2033 11:27 AM) |
| <cause> | The hangup cause with which the call should be terminated. | ALLOTTED_TIMEOUT (the default) |
| <uuid> | The unique identifier (UUID) of the call leg. See Channel Variables. | f2120667-3cd6-42bc-8be6-8cf4207cf6bc |
To get the absolute time in seconds since the Epoch, see this Stackoverflow thread.
2. Examples
2.1 Dialplan example 1 - 60 seconds for the entire call
Before you call bridge, add another action that executes the sched_hangup application.
<!-- Make the call last 1 minute, and end with SWITCH_CAUSE_ALLOTTED_TIMEOUT -->
<action application="sched_hangup" data="+60 allotted_timeout"/>
<action application="bridge" data="sofia/external/1234567@10.10.10.10"/>
SWITCH_CAUSE_ALLOTTED_TIMEOUT is the default hangup cause so it could have been omitted as well.
This setup will hang up the call exactly 60 seconds after calling sched_hangup, including call setup time. For example, if remote side answers the call 15 seconds after phone starts ringing there will be 45 seconds left for the actual conversation.
2.2 Dialplan example 2 - Ensure 60 seconds of "talk" time
If you want to ensure 60 seconds of "talk" time, start sched_hangup at the moment of answering using the execute_on_answer channel variable:
<action application="set" data="execute_on_answer=sched_hangup +60 alloted_timeout" />
<action application="bridge" data="sofia/external/1234567@10.10.10.10" />
If your A-leg call has already been answered (e.g., with an IVR), and you want to limit on the B-leg, then use api_on_answer channel variable:
<action application="export" data="nolocal:api_on_answer=sched_hangup +60 ${uuid} alloted_timeout" />
<action application="bridge" data="sofia/external/1234567@10.10.10.10" />
2.3 Using the FreeSWITCH API outside the dialplan
Once a call is already up you can do it from the sched_hangup API command from XML-RPC or the CLI.
Do a show channels to get the uuid of the call then enter.
sched_hangup +60 <uuid> alotted_timeout
All the params besides uuid have the same meaning as the dialplan app.