Events

0. About​

Events are generated by

• commands
• changes in status or configuration
• the core and modules of FreeSWITCH
• external applications
• TODO What else?

and the event system is responsible of controlling the distribution of events among (internal and external) subscribers.

For a comprehensive list of events, see Custom events.

1. Event structure​

An event message has two parts:

• Header section
• Body (optional)

1.1 Header section​

Headers are key/value pairs, and contain almost all of the information regarding an event. Most events only have a header section.

The Event headers page shows the list of available headers.

Some header values may contain multiple line breaks, but because FreeSWITCH URL-encodes all of them, these multi-line header values will still appear as 1 line.

Example of multi-line header values

# header BEFORE URL-encoding
variable_switch_r_sdp: v=0
o=UAC 6407 6867 IN IP4 192.168.27.72
s=SIP Media Capabilities
c=IN IP4 61.231.8.102
t=0 0
m=audio 12916 RTP/AVP 0 18 101
a=rtpmap:0 PCMU/8000
a=rtpmap:18 G729/8000
a=fmtp:18 annexb=no
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=maxptime:20

# header AFTER URL-encoding
variable_switch_r_sdp: v%3D0%0D%0Ao%3DUAC%206407%206867%20IN%20IP4%20192.168.27.72%0D%0As%3DSIP%20Media%20Capabilities%0D%0Ac%3DIN%20IP4%2061.231.8.102%0D%0At%3D0%200%0D%0Am%3Daudio%2012916%20RTP/AVP%200%2018%20101%0D%0Aa%3Drtpmap%3A0%20PCMU/8000%0D%0Aa%3Drtpmap%3A18%20G729/8000%0D%0Aa%3Dfmtp%3A18%20annexb%3Dno%0D%0Aa%3Drtpmap%3A101%20telephone-event/8000%0D%0Aa%3Dfmtp%3A101%200-15%0D%0Aa%3Dmaxptime%3A20%0D%0A

1.1.1 Common event headers​

Common headers

There is a minimum amount of information sent for every event (no matter what the type they are). See list below.

Headers common to all events:

TODO Would it be more prudent to call these «mandatory» fields?

The example below is in the format of mod_event_socket's event plain command.

Example

Event-Name: RE_SCHEDULE
Core-UUID: 6d2375b0-5183-11e1-b24c-f527b57af954
FreeSWITCH-Hostname: freeswitch.local
FreeSWITCH-Switchname: freeswitch.local
FreeSWITCH-IPv4: 127.0.0.1
FreeSWITCH-IPv6: ::1
Event-Date-Local: 2012-02-07 19:36:31
Event-Date-GMT: Tue, 07 Feb 2012 18:36:31 GMT
Event-Date-Timestamp: 1328639791116026
Event-Calling-File: switch_scheduler.c
Event-Calling-Function: switch_scheduler_execute
Event-Calling-Line-Number: 65
Event-Sequence: 3349

1.2 Event body​

Events may have a body, carrying additional content generated with the event. It is usually not in the key/value form of headers, and may contain its own native formatting.

If the event does have a body, then

• Content-Length header will be included in the header section, and
• it will contain the size of the payload in bytes (analogous to the HTTP header of the same name).

Events with bodies include MESSAGE, MESSAGE_WAITING, DETECTED_SPEECH, BACKGROUND_JOB, and so on (see Event List). For parsing instructions, see How to parse events section.

The example below is in the format of mod_event_socket's event plain command.

TODO Update example because (1) not sure how old this example is (and thus whether it's still relevant), (2) does not contain all common fields, and (3) there are 3 line feeds before the event body, instead of 2 (is this valid?).

Example taken from «Event List» page

Speech-Type: detected-speech
Event-Name: DETECTED_SPEECH
Core-UUID: aac0f73e-b822-e54c-a02a-06a839ca3e5a
FreeSWITCH-Hostname: AMONROY
FreeSWITCH-IPv4: 192.168.1.220
FreeSWITCH-IPv6: ::1
Event-Date-Local: 2009-01-26 16:07:24
Event-Date-GMT: Mon, 26 Jan 2009 22:07:24 GMT
Event-Date-Timestamp: 1233007644906250
Event-Calling-File: switch_ivr_async.c
Event-Calling-Function: speech_thread
Event-Calling-Line-Number: 1758
Content-Length: 435


<result grammar="<request1@form-level.store>#nombres">
    <interpretation grammar="<request1@form-level.store>#nombres" confidence="0.494643">
        <instance confidence="0.494643">
            arturo monroy
        </instance>
        <input mode="speech" confidence="0.494643">
            <input confidence="0.313102">
                arturo
            </input>
            <input confidence="0.618854">
                monroy
            </input>
        </input>
    </interpretation>
</result>

2. Event hierarchy​

2.1 Classes​

The below events (i.e., Event-Name header values) ar defined by the core of FreeSWITCH, and thus they are the main class of events.

See Event List for their descriptions with examples.

• ADD_SCHEDULE
• API
• BACKGROUND_JOB
• CALL_DETAIL
• CALL_SECURE
• CALL_SETUP_REQ
• CALL_UPDATE
• CDR
• CHANNEL_ANSWER
• CHANNEL_APPLICATION
• CHANNEL_BRIDGE
• CHANNEL_CALLSTATE
• CHANNEL_CREATE
• CHANNEL_DATA
• CHANNEL_DESTROY
• CHANNEL_EXECUTE
• CHANNEL_EXECUTE_COMPLETE
• CHANNEL_GLOBAL
• CHANNEL_HANGUP
• CHANNEL_HANGUP_COMPLETE
• CHANNEL_HOLD
• CHANNEL_ORIGINATE
• CHANNEL_OUTGOING
• CHANNEL_PARK
• CHANNEL_PROGRESS
• CHANNEL_PROGRESS_MEDIA
• CHANNEL_STATE
• CHANNEL_UNBRIDGE
• CHANNEL_UNHOLD
• CHANNEL_UNPARK
• CHANNEL_UUID
• CLONE
• CODEC
• COMMAND
• CONFERENCE_DATA
• CONFERENCE_DATA_QUERY
• CUSTOM
• DEL_SCHEDULE
• DETECTED_SPEECH
• DETECTED_TONE
• DEVICE_STATE
• DTMF
• EXE_SCHEDULE
• FAILURE
• GENERAL
• HEARTBEAT
• LOG
• MEDIA_BUG_START
• MEDIA_BUG_STOP
• MESSAGE
• MESSAGE_QUERY
• MESSAGE_WAITING
• MODULE_LOAD
• MODULE_UNLOAD
• NAT
• NOTALK
• NOTIFY
• NOTIFY_IN
• PHONE_FEATURE
• PHONE_FEATURE_SUBSCRIBE
• PLAYBACK_START
• PLAYBACK_STOP
• PRESENCE_IN
• PRESENCE_OUT
• PRESENCE_PROBE
• PRIVATE_COMMAND
• PUBLISH
• QUEUE_LEN
• RECORD_START
• RECORD_STOP
• RECV_INFO
• RECV_MESSAGE
• RECV_RTCP_MESSAGE
• RECYCLE
• RELOADXML
• REQUEST_PARAMS
• RE_SCHEDULE
• ROSTER
• SEND_INFO
• SEND_MESSAGE
• SESSION_HEARTBEAT
• SHUTDOWN
• STARTUP
• SUBCLASS_ANY
• TALK
• TRAP
• UNPUBLISH

2.2 Subclasses (or CUSTOM events)​

A CUSTOM event (i.e., where the **Event-Name** header's value is CUSTOM) is a generic class to define events that is specific to a module, a feature, or to a service.

CUSTOM events are used with the Event-Subclass header denoting the event's role and meaning.

CUSTOM events are employed by

• most endpoint modules (see Creating a New Endpoint: Lifecycle of a Session),
  

for example, when a user logs into Verto, or a SIP phone tries to register

• many dialplan applications,
  

such as the conference, voicemail, and call center applications, the fax management in mod_spandsp, and so on. The ivr application also generates CUSTOM events, and subclasses describe entering and exiting of menus (see «Events» section in mod_dptools: IVR Menu).

See List of CUSTOM Events for a complete list of subclasses.

Modules with CUSTOM events

• mod_sofia - Sofia-SIP module.
• mod_dingaling - Jabber/GoogleTalk Talk integration module.
• mod_portaudio - Host machine sound card.
• mod_conference - Conference module.
• mod_event_multicast
• mod_skinny - Skinny (aka SCCP) module.
• mod_callcenter - Call queuing application for call center needs.
• mod_spandsp - SpanDSP module including T.38 fax support.
• IVR Menu - Built IVR Engine events since FreeSWITCH 1.6

3. How to process events​

The steps depend on what method is used to tap into the event system.

For example, in case of using

• mod_erlang_event or mod_kazoo,
  

the values are returned as Erlang terms.

• the Event Socket Library,
  

the event building blocks are parsed by the programming language used, and the ESLevent object has a getBody() method.

• mod_event_socket,
  

one has to parse TCP packets. (See parsing instructions there under 3.5 event.)

• TODO What else?

Edit this page

Event-headers_32178341 Previous

Event headers

List-of-CUSTOM-Events_15139388 Next

List of CUSTOM Events

• 0. About
• 1. Event structure
  • 1.1 Header section
  • 1.2 Event body
• 2. Event hierarchy
  • 2.1 Classes
  • 2.2 Subclasses (or ''%%CUSTOM%%'' events)
• 3. How to process events