Adding AI capabilities to FreeSWITCH

Did you know you can add an AI agent to your FreeSWITCH instance to handle your calls? In this guide, we’ll walk through an example code snippet for bridging a FreeSWITCH dialplan to a SignalWire AI Agent. This will allow an AI agent to take over the call as a virtual assistant or an IVR replacement, which is especially useful if you’re receiving many calls at once.

What is the SignalWire AI Agent?

SignalWire’s AI Agent is a low-code voice agent you can build using plain-text instructions. Personality, skills, and areas of expertise can all be customized in a simple drag-and-drop interface. You can also code your own if you want it to perform more complex functions.

You can use an AI agent as a virtual receptionist for your business, or as your own personal AI assistant. With the power of AI, the agent does not require pre-recorded messages or even text-to-speech prompts - it’s smart enough to engage in conversation with callers based on plain language instructions.

Add a SIP Address to your AI Agent

Once you have created your AI Agent, add a SIP Address to the agent’s Addresses. FreeSWITCH bridges calls to that SIP Address, and the AI Agent takes over every call that reaches it.

To add a SIP Address to the AI Agent from your SignalWire Dashboard:

Open the AI Agent and select its Addresses & Phone Numbers tab.
Select + Add, then SIP Address.
On the New SIP Address page, fill out the Domain and Display Name, then select Create.

To create one in code, use Create SIP address. For the other Resources that can take a SIP Address, see Resource SIP Addresses. SIP Addresses explains the address format and its options.

Restrict who can send calls to your SIP Address

Limit the SIP Address to your FreeSWITCH server’s public IP address. Under IP Whitelisting, turn on IP Auth Enabled and enter the server’s IP address in Authorized IPs. IP authentication is off by default, so without it or a password, anyone who knows the address can send calls to it.

For more complex AI use-cases, you might want to consider using SignalWire Markup Language (SWML). You can use a SWML script resource to define the AI agent’s behavior.

FreeSWITCH Dialplan Configuration

Now that we have configured our AI agent in the SignalWire dashboard, we can now bridge the FreeSWITCH dialplan to the AI agent.

We’ll break down the components of the following code snippet:

<extension name="testing_ai" continue="false" uuid="6d0ecaef-9049-4920-8d1a-fc97ff4731f0">
	<condition field="destination_number" expression="^55555$">
		<action application="ring_ready" data=""/>
		<action application="answer" data=""/>
		<action application="sleep" data="500"/>
		<action application="set" data="hangup_after_bridge=true"/>
		<action application="set" data="ringback=local_stream://default"/>
		<action application="bridge" data="sofia/external/FreeSWITCH_AI@example-space-freeswitch-ai.dapp.signalwire.com;transport=tcp"/>
	</condition>
</extension>

FreeSWITCH_AI@example-space-freeswitch-ai.dapp.signalwire.com is a placeholder. Replace it with your AI Agent’s SIP Address before you use the dialplan. SignalWire builds the host from your Space name and the Domain you chose, in the form <YOUR_SPACE>-<domain>.dapp.signalwire.com. The user part of a SIP Address defaults to *, which accepts any username, so FreeSWITCH_AI can stay as it is.

Dialplan Details

The given dialplan defines an extension within a FreeSWITCH configuration file. Let’s break down its components for a clearer understanding:

`<extension>`

<extension name="testing_ai" continue="false" uuid="6d0ecaef-9049-4920-8d1a-fc97ff4731f0">

name="testing_ai": The name of the extension. This is a unique identifier for the extension.
continue="false": Indicates whether FreeSWITCH should continue processing more extensions if this extension is executed. false means no further extensions will be processed.
uuid="6d0ecaef-9049-4920-8d1a-fc97ff4731f0": A unique identifier for this specific extension instance.

`<condition>`

<condition field="destination_number" expression="^55555$">

field="destination_number": This specifies that the condition is based on the destination number of the call.
expression="^55555$": A regular expression that matches the number 55555. Only calls to this exact number will trigger the actions defined in this extension.

`<action>`

Each <action> element represents a step in the call handling process. This configuration is particularly useful for setting up specialized call routing and handling behaviors in FreeSWITCH.

This block provides a detailed breakdown of the extension, condition, and actions within the provided FreeSWITCH dialplan configuration.

The actions are executed sequentially when the condition is met:

ring_ready

Sends a ringing signal to the caller, indicating that the call is being processed but not yet answered.

<action application="ring_ready" data=""/>

answer

Answers the call.

<action application="answer" data=""/>

sleep

Pauses the call processing for 500 milliseconds.

<action application="sleep" data="500"/>

Set hangup_after_bridge

Sets a variable hangup_after_bridge to true, which means the call will be hung up immediately after the bridge application completes its execution.

<action application="set" data="hangup_after_bridge=true"/>

Set ringback

Sets the ringback tone to be played to the caller. In this case, it uses a default local stream.

<action application="set" data="ringback=local_stream://default"/>

bridge

Bridges the call to a SignalWire SIP URI using the TCP transport. This effectively forwards the call to the specified SIP Address. example-space-freeswitch-ai.dapp.signalwire.com is a placeholder for the host of your AI Agent’s SIP Address.

 <action application="bridge" data="sofia/external/FreeSWITCH_AI@example-space-freeswitch-ai.dapp.signalwire.com;transport=tcp"/>