Event Triggers

Event Triggers let you set up Switchvox to interact with external web-based applications. When certain events occur in Switchvox, it can do an HTTP POST that includes information about the event, and then respond to XML that is returned. Click Save Event Triggers when finished.

System Default URL

You can enter a Default URL so that you do not have to enter a full URL for each event. But, you can choose to use the default URL or not, so you still have flexibility on each event.

Event Specific URLs

There are some Switchvox events that trigger an HTTP POST. You can choose to Append URL variables and to use the Default URL (YES/NO).

• On Incoming Call Event URL. Triggered at the beginning of an incoming call. This event applies to calls received from VOIP providers, any channel groups, as well as calls between extensions. It is common for requests of this type to return XML for routing the call or altering the Caller ID.
• On Route to Extension Event URL. Triggered when a call hits an extension. This event can occur multiple times for each call. For example, a call may hit an IVR, a queue, and then a phone extension. XML can be returned to route calls differently.

WARNING: Do not create routing loops. For example, if a call to extension 333 results in a request that sets transfer_extension to 333, then Switchvox loops endlessly. Do not set transfer_extension in the response to this event unless it is absolutely necessary.

• On Call Answered Event URL. Triggered when a call is answered. This event applies to calls from external numbers, and from all Switchvox extensions.
• On New Voicemail Event URL. Triggered when a voicemail message is left for an extension (including a message forwarded from another extension). This event requests the voicemail URL.

NOTE: Setting XML values in the response to this request results in undefined behavior. Return empty XML for this request.

• On Checked Voicemail Event URL. Triggered when an extension checks its voicemail. This event could be used in conjunction with the On New Voicemail Event to track new voicemail messages and implement an escalation policy.

NOTE: Setting XML values in the response to this request results in undefined behavior. Return empty XML for this request.

• On Agent Logged In Event URL. Triggered when a queue member logs into a queue.

• On Agent Logged Out Event URL. Triggered when a queue member logs out of a queue.

• On Call Hangup Event URL. Triggered when a call is hung up. This event can be used in conjunction with the JOB_ID variable to record the completion of calls that invoked previous URL events. Note: Setting XML values in the response to this request results in undefined behavior. Return empty XML for this request.
• On Outgoing Call Event URL. Triggered when a call is created. This event applies to calls to external numbers and all Switchvox extensions.

URL Variables

Switchvox events can submit various information about calls. To do this, you use variables in the URL. Not every variable is available in every event (check the Acceptable Variables dropdown on each event), so be prepared to handle an empty variable. Here is the complete list of all of the variables for all event types:

CALLER_ID_NUMBER. Phone number from caller ID, including area code.

CALLER_ID_NAME. Name from caller ID.

EXTENSION. Internal extension associated with the event.

EXTENSION_TYPE. The type of the extension associated with the event. For the list of extension types, see Extension Types.

FEATURE_DATA. The data entered after a feature code. For example, in *62204, you have an EXTENSION of 62, an EXTENSION_TYPE of feature_monitor, and a FEATURE_DATA of 204.

INCOMING_DID. Phone number dialed by an external caller. May be empty for internal calls, or calls over certain analog lines that do not provide the DID.

VM_DUR. The duration of the voicemail message, in seconds.

VM_MSGNUM. The unique message number for this voicemail message.

VM_MAILBOX. Extension associated with the event’s voicemail box.

VM_DATE. The date and time of the voicemail message.

QUEUES. A comma separated list of the queue account_ids being logged in to or logged out of. In the case where the user is being logged out of all queues, the list will only contain the list of queues the user is a member of.

EVENT_TYPE. Event type that has been triggered. This is useful for the Default URL, which receives POSTs from any of the event types.

JOB_ID. Unique ID of the call. Note: This string of digits is not a numerical value: 99.100 is not equal to 99.1. This variable is useful for correlating multiple events (and also certain IVR requests).

XML Response

For some events, the remote web application can return XML that instructs Switchvox to perform operations on the call. Here is a sample of an XML response:

<response>
<result>
<call_info>
<caller_id_number>8585551212</caller_id_number>
<caller_id_name>John Doe</caller_id_name>
<transfer_extension>850</transfer_extension>
<display_url>http://intranet.example.com/crm.cgi?custid=2</
display_url>
<continue_outgoing_reporting>1</continue_outgoing_reporting>
</call_info>
</result>
</response>

All of the tags inside the call_info block are optional. The following XML tags can be used:

callerid_num. Set Caller ID Number to this value.

callerid_name. Set Caller ID Name to this value.

transfer_extension. Transfer call to the extension of this value. If this XML is a response to the event On Outgoing Call, this can be an external number. Make sure to enter this number as you would dial it from your phone. For example, if you must dial 9 for an external number, an external number here must begin with a 9.

WARNING: It is possible to break Switchvox by creating routing loops with transfer_extension.

display_url. Display this URL in the Switchboard as a clickable icon. For example: the remote web application might lookup the caller’s phone number in your company’s user database, then return the URL of the caller’s user record.

continue_outgoing_reporting. Continue reporting any subsequent outgoing calls for this JOB_ID. For example, if a call is made to a queue, the event will continue when a queue-member's extension is dialed. The value of this tag must be 1 or 0.

Rel6.0