FreeSWITCH ESL ALL

Summary

JDK 1.8 +

Netty used 4.1.x, 5.x is not supported

Spring Boot 2.x / 3.x / 4.x, one starter for all of them, see Compatibility

Features

1. Support to connect FreeSWITCH Cluster
2. Easy to integrate with FreeSWITCH ESL
3. Support spring boot starter
4. Support to dynamic add or remove remote server
5. Support Spring Boot 2.x, 3.x and 4.x with the same artifact

AI Skills (Qoder)

Two Qoder skills are maintained for this library, so an AI coding agent can wire it up correctly without reading the whole source tree. They are documentation-only: no MCP server, no credentials, no network calls.

Both also carry the failure modes that are easy to get wrong: InboundClient is a JVM-wide singleton, closeChannel(addr) closes the ESL socket rather than a call, events you did not subscribe to are never delivered, and sync commands are serialised per connection.

Install

From the Qoder plugin marketplace, search freeswitch-esl and install the plugin you need, or install it by name:

qodercli plugin install freeswitch-esl-spring-boot-starter

Or install a local plugin directory / zip. --scope accepts user (default, global), project (shared and committed to VCS) or local (personal, not committed):

qodercli plugin install --scope user /path/to/freeswitch-esl-spring-boot-starter
qodercli plugin validate /path/to/freeswitch-esl        # optional structure check

Or drop the skill folders into a project so the whole team gets them from git:

/.qoder/skills/freeswitch-esl/SKILL.md
/.qoder/skills/freeswitch-esl/references/*.md

/.qoder/skills/freeswitch-esl-spring-boot-starter/SKILL.md
/.qoder/skills/freeswitch-esl-spring-boot-starter/references/*.md

Use

1. Reload skills (/skills reload) or restart the session, then confirm with /skills list.
2. Invoke explicitly with /freeswitch-esl-spring-boot-starter or /freeswitch-esl, or just describe the task in natural language - Chinese and English triggers both work (FreeSWITCH, ESL, event socket, originate, 事件订阅, 呼叫控制, 话单).
3. Typical prompts: “add FreeSWITCH ESL inbound to this Boot 3 service with a hangup handler”, “why does my originate block the thread”, “expose an admin endpoint to add a switch node”, “tune executor threads for 200 events/s”.

Keep the skills in step with the library: they pin examples at 2.2.0 and describe the current behaviour of InboundClient, InboundClientOption and FreeswitchEslAutoConfiguration. After a breaking change, update both skills together with this README.

Maven

Latest release is 2.2.0, see Maven Central.

   link.thingscloud
   freeswitch-esl
   ${freeswitch-esl.version}

Quick Start

freeswitch-esl-spring-boot-starter

Maven Central

    link.thingscloud
    freeswitch-esl-spring-boot-starter
    ${freeswitch-esl.version}

application.properties

link.thingscloud.freeswitch.esl.inbound.servers[0].host=127.0.0.1
link.thingscloud.freeswitch.esl.inbound.servers[0].port=8021
link.thingscloud.freeswitch.esl.inbound.servers[0].timeout-seconds=5
link.thingscloud.freeswitch.esl.inbound.servers[0].password=ClueCon
link.thingscloud.freeswitch.esl.inbound.servers[2].host=127.0.0.2
link.thingscloud.freeswitch.esl.inbound.servers[2].port=8021
link.thingscloud.freeswitch.esl.inbound.servers[2].timeout-seconds=5
link.thingscloud.freeswitch.esl.inbound.events=CHANNEL_CREATE CHANNEL_DESTORY 
# performance monitor - event driven - business logic processing time
link.thingscloud.freeswitch.esl.inbound.performance=true 
link.thingscloud.freeswitch.esl.inbound.performanceCostTime=200 
# event performance monitor - event driven - event generate time and event receive time
link.thingscloud.freeswitch.esl.inbound.eventPerformance=false 
link.thingscloud.freeswitch.esl.inbound.eventPerformanceCostTime=200

application.yml

link:
  thingscloud:
    freeswitch:
      esl:
        inbound:
          defaultPassword: ClueCon
          performance: false
          performanceCostTime: 200
          #read-timeout-seconds: 0
          servers:
            - host: 127.0.0.1
              port: 8021
              timeoutSeconds: 5
            - host: 127.0.0.2
            - host: 127.0.0.3
          events:
            - CHANNEL_CREATE
            - CHANNEL_DESTORY

@Slf4j
@Component
public class ExampleInboundClient {
    @Autowired
    private InboundClient inboundClient;

    @Autowired
    private InboundClientBootstrap inboundClientBootstrap;

    @PostConstruct
    public void startup() {
        System.out.println(inboundClientBootstrap);
    }

}

@Slf4j
@Component
public class InboundClientOptionHandlerExample extends AbstractInboundClientOptionHandler {

    /**
     * {@inheritDoc}
     */
    @Override
    protected void intercept(InboundClientOption inboundClientOption) {
        List serverOptions = inboundClientOption.serverOptions();
        log.info("serverOptions before : {}", serverOptions);
        serverOptions.clear();
        serverOptions.add(new ServerOption("127.0.0.8", 8021));
        log.info("serverOptions after  : {}", serverOptions);
    }
}

@Slf4j
@Component
@EslEventName(EventNames.HEARTBEAT)
public class HeartbeatEslEventHandler implements EslEventHandler {
    /**
     * {@inheritDoc}
     */
    @Override
    public void handle(String addr, EslEvent event) {
        log.info("HeartbeatEslEventHandler handle addr[{}] EslEvent[{}].", addr, event);
    }
}

@Slf4j
@Service
public class ServerConnectionListenerImpl implements ServerConnectionListener {
    /**
     * {@inheritDoc}
     */
    @Override
    public void onOpened(ServerOption serverOption) {
        log.info("onOpened serverOption : {}", serverOption);
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void onClosed(ServerOption serverOption) {
        log.info("onClosed serverOption : {}", serverOption);
    }
}

freeswitch-esl

Maven Central

    link.thingscloud
    freeswitch-esl
    ${freeswitch-esl.version}

InboundClientOption option = new InboundClientOption();

// set default esl password, if ServerOption not set password, use this default value
option.defaultPassword("ClueCon")
    .addServerOption(new ServerOption("127.0.0.1", 8021));

// set esl subscribe events
option.addEvents("all");

// ESL event listener
option.addListener(new IEslEventListener() {
    @Override
    public void eventReceived(String addr, EslEvent event) {
        System.out.println(addr);
        System.out.println(event);
    }

    @Override
    public void backgroundJobResultReceived(String addr, EslEvent event) {
        System.out.println(addr);
        System.out.println(event);
    }
});

option.serverConnectionListener(new ServerConnectionListener() {
    @Override
    public void onOpened(ServerOption serverOption) {
        System.out.println("---onOpened--");
    }

    @Override
    public void onClosed(ServerOption serverOption) {
        System.out.println("---onClosed--");
    }
});

InboundClient inboundClient = InboundClient.newInstance(option);

// start client
inboundClient.start();

// shutdown client, after shutdown, can't start again, shutdown with JVM
inboundClient.shutdown();

// Get InboundClient Instance
InboundClient inboundClient = InboundClient.getInstance();

// Get InboundClient FreeSWITCH API
InboundClient.getBootstrap()

// add server option
inboundClient.option().addServerOption(new ServerOption(host, port));
// InboundClient.getInstance().option().addServerOption(new ServerOption(host, port));

// remove server option
ServerOption serverOption = inboundClient.option().serverOptions().get(0);
inboundClient.option().removeServerOption(serverOption);
// InboundClient.getInstance().option().removeServerOption(serverOption);

Star history

Notice

1. Send api is recommended to use asynchronous operation, especially the originate command
2. There is a message timeout mechanism at present to deal with the false death of the connection caused by the direct shutdown of the server. Set the value of readTimeoutSeconds parameter to 0 to turn off this feature
3. In order to improve performance, when processing EslEvent, use Netty's worker thread. If the processing logic involves IO or time-consuming operation, the processing logic must be put in a new thread to process, and the disablePublicExecutor parameter is set

WeChat User Groups - Please note the source

LICENSE

Apache License, Version 2.0 Copyright © Apache Software Foundation