Skip to main content

Events System

FreeSWITCH is an open-source telephony platform designed for building and managing communication systems. The Event System is a powerful feature of FreeSWITCH that allows you to monitor and respond to various system events. This guide will provide a detailed overview of the Event System, including its concepts, components, and practical examples.

What is the Event System?​

The Event System in FreeSWITCH is a mechanism for tracking and responding to events that occur within the system. Events can be anything from changes in call status to system errors. The Event System provides a way to get real-time updates about these occurrences, enabling you to build dynamic and interactive applications.

This means that external programs can:

  • Send events to FreeSWITCH to trigger actions, such as starting a call or playing a sound.
  • Receive events from FreeSWITCH to monitor what is happening, such as when a call is answered or disconnected.

This makes FreeSWITCH very versatile and can be used in a wide variety of applications.

Key Concepts​

Event​

An event is a notification about a specific occurrence in FreeSWITCH. Events are generated when something significant happens, such as a call starting or a user logging in. Each event contains relevant data about the occurrence.

Event Type​

Different types of events are categorized to help you identify and handle them appropriately. Some common event types include:

  • Channel Events: Events related to channels and call activity

    • CHANNEL_CREATE: A new call has been initiated.
    • CHANNEL_HANGUP: A call has ended.
    • CHANNEL_STATE: The state of a call has changed (e.g., ringing, answered).

  • System Events: Events related to system status, like errors or warnings.

    • SYSTEM_ERROR: An error has occurred in the system.
    • SYSTEM_WARNING: A warning about a potential issue.

  • Presence Events: Events related to user presence, such as when a user logs in or out.

    • PRESENCE_IN: A user has logged in.
    • PRESENCE_OUT: A user has logged out.

Event Subsystems​

FreeSWITCH uses different subsystems to manage and dispatch events. Some of the key subsystems include:

  • Event API: Allows programmatic interaction with events. You can use this API to subscribe to and receive events in your applications.
  • Event Socket: A network socket interface for connecting to FreeSWITCH and receiving events. This is useful for real-time event monitoring.
  • Event Filters: Mechanisms to specify which events you want to receive. Filters help reduce the volume of events by allowing you to focus only on those that are relevant to your application.

How the Event System Works​

  • Event Generation: When an event occurs in FreeSWITCH (e.g., a call is answered), an event message is generated.
  • Event Dispatching: The Event System processes the event message and sends it to all subscribed listeners.
  • Event Handling: Applications or scripts that have subscribed to events receive them and can take appropriate actions based on the event data.

Basic Usage​

Here’s a step-by-step guide to using the FreeSWITCH Event System:

Connect to FreeSWITCH​

You need to connect to the FreeSWITCH server to interact with the Event System. This can be done using the Event Socket or the Event API. For simplicity, we'll focus on using the Event Socket.

Using the Event Socket​

  • The Event Socket allows you to connect to FreeSWITCH and receive events over a network socket. By default, the Event Socket listens on port 8021.

  • Open a Terminal: Access your server or local machine where FreeSWITCH is running.

  • Connect to the Event Socket: Use the telnet or nc (netcat) command to connect to FreeSWITCH:

    telnet localhost 8021

    or

    nc localhost 8021

  • Authenticate: Send the authentication command (the default password is ClueCon):

    auth ClueCon

  • Request Events: After authentication, request to receive events. For example, to receive all events:

    event plain ALL

Subscribe to Specific Events​

You can subscribe to specific types of events to receive only the information you need. For instance, to subscribe only to channel events:

event plain CHANNEL

Handle Events​

When you receive events, you can process them to perform specific actions. For example, you might want to log events to a file or trigger other system processes.

Example: Basic Event Listener Script​

Here’s an example of a Python script that connects to the Event Socket, authenticates, and listens for events:

import socket

# Define connection parameters
HOST = 'localhost'
PORT = 8021
PASSWORD = 'ClueCon'

def main():
    # Create a socket connection
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        s.connect((HOST, PORT))
        # Authenticate with FreeSWITCH
        s.sendall(f'auth {PASSWORD}\n'.encode('utf-8'))
        # Request all events
        s.sendall(b'event plain ALL\n')

        while True:
            data = s.recv(4096)
            if not data:
                break
            # Print received data
            print(data.decode('utf-8'))

if __name__ == '__main__':
    main()

This script will continuously print out all events received from FreeSWITCH.

Example Use Cases​

  • Call Monitoring: Use channel events to monitor call activity, such as detecting when a call starts or ends, and updating user interfaces or logging information.

  • System Health Monitoring: Use system events to track system errors or warnings, allowing you to respond to issues promptly and maintain system reliability.

  • User Presence Tracking: Use presence events to manage user presence in applications, such as updating status indicators or managing user sessions.

Conclusion​

The FreeSWITCH Event System is a powerful feature that allows you to monitor and respond to various events in real-time. By understanding the types of events, how to connect to the Event Socket, and how to handle events, you can build dynamic and responsive communication applications.

For more detailed information, refer to the official FreeSWITCH Event System Documentation.

Feel free to explore and experiment with the Event System to fully understand its capabilities and how it can be applied to your communication solutions.