Call Us Today! 877.742.2583




Page tree
Skip to end of metadata
Go to start of metadata

 Table of Contents (click to expand)


0. About

Events are generated by

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

For a comprehensive list of events, see Event List.

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? 


Field/HeaderTypeDescriptionExample value
1Core-UUIDcommon

Unique ID of FreeSWITCH instance, changes on every reboot [1].

11f751fa-47a7-11e2-9f24-bf76d9fc9ea3
2Event-Calling-File

common

Source file that triggered this event.mod_voicemail.c
3Event-Calling-Functioncommon

Source function that triggered this event.

sofia_reg_parse_auth
4Event-Calling-Line-Numbercommon

Source file line that triggered this event.

710
5Event-Date-GMTcommon

Date/time including timezone from FreeSWITCH instance at the point the event was triggered.

Fri, 28 Dec 2012 19:08:39 GMT
6Event-Date-Localcommon

Local date/time from FreeSWITCH instance at the point the event was triggered.

2012-12-28 19:08:39
7Event-Date-Timestampcommon

Unix epoch time from FreeSWITCH instance at the point the event was triggered. (in microseconds, divide by 1000 to get milliseconds).

1356721719352143
8Event-Namecommon

Name of the event. See Classes section.

RE_SCHEDULE
9Event-Sequencecommon

Sequential ID of event on the FreeSWITCH instance.

This resets to zero after every reboot, and is not unique to each instance. [1]

9274
10FreeSWITCH-IPv4common

IPv4 address of FreeSWITCH instance.

192.168.0.2
11FreeSWITCH-IPv6commonIPv6 address of FreeSWITCH instance.::1
12FreeSWITCH-Hostnamecommon

Host name of machine that FreeSWITCH instance is running on.

server123.example.com
server123
13FreeSWITCH-Switchnamecommon

Switch name of FreeSWITCH instance. This is normally the same as FreeSWITCH-Hostname unless you have a complex configuration (for example, fail over, multi-homing etc).

server123.example.com
server123

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 MESSAGEMESSAGE_WAITINGDETECTED_SPEECHBACKGROUND_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

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

Modules with CUSTOM events

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?

  • No labels