Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] FS vs SW examples #125

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/SignalWire-Examples/dial-sipendpoint.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
## Dialing a SignalWire SIP Endpoint from FreeSWITCH Dialplan

To dial a SignalWire SIP endpoint from FreeSWITCH dialplan, follow these steps:

1. Create a gateway with SignalWire SIP endpoint details. Refer to this guide for instructions on how to create a gateway in FreeSWITCH: [Gateway Creation Guide](https://github.com/ShashiKumar-SignalWire/SW-example-Docs/blob/main/FS_SIPEndpoint_registration.md).

2. Create the following dialplan in your FreeSWITCH `dialplan/public.xml` to forward your incoming calls to the public dialplan:

```xml
<extension name="Dial">
<condition field="destination_number" expression="^(.*)$">
<action application="set" data="sip_custom_header=X-MyCustomHeader: Value-ShashiKumar"/>
<action application="bridge" data="sofia/gateway/signalwire_prod/sip:[email protected]"/> <!-- Replace example.sip.signalwire.com with your actual SignalWire SIP endpoint URI -->
<action application="hangup"/>
</condition>
</extension>
```
If you want to pass custom SIP headers when calling the SIP endpoint, set custom variables as shown below:

```xml
<extension name="Dial">
<condition field="destination_number" expression="^(.*)$">
<action application="set" data="sip_h_X-AccountCode=4321"/> <!-- Custom header to pass in INVITE -->
<action application="set" data="sip_h_X-MyCustomHeader: Value"/> <!-- Custom header to pass in INVITE -->
<action application="bridge" data="sofia/gateway/signalwire_prod/sip:[email protected]"/> <!-- Replace example.sip.signalwire.com with your actual SignalWire SIP endpoint URI -->
<action application="hangup"/>
</condition>
</extension>
```

Replace example.sip.signalwire.com with your actual SignalWire SIP endpoint URI and SignalwireUsername with your SignalWire SIP endpoint username.
49 changes: 49 additions & 0 deletions docs/SignalWire-Examples/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
import { Link } from '@docusaurus/router';
import Layout from '@theme/Layout';


# Welcome to the Evolution of Telecommunications

## From FreeSWITCH to SignalWire

FreeSWITCH has been the backbone of open-source telecommunications for years, enabling countless businesses to build robust communication solutions. Now, with SignalWire, we take it a step further, offering advanced APIs, unparalleled scalability, and a seamless transition for FreeSWITCH users.

## Why Choose SignalWire?

### Scalability and Flexibility
Leverage our elastic cloud infrastructure to scale your applications globally with minimal latency. SignalWire provides a robust platform that grows with your business needs, ensuring high availability and performance.

### Enhanced API Capabilities
Simplify the development of voice, messaging, and video applications with our powerful and intuitive APIs. SignalWire's APIs offer greater functionality and ease of use compared to traditional methods, enabling you to build complex communication solutions with minimal effort.

### Continuous Support
Benefit from the expertise of the original FreeSWITCH developers and an active, supportive community. With SignalWire, you get access to dedicated support channels, extensive documentation, and a vibrant community ready to help you succeed.

## Explore Our Examples

We provide detailed examples to help you transition from FreeSWITCH to SignalWire seamlessly. Explore how common tasks and setups in FreeSWITCH can be easily achieved and enhanced using SignalWire's advanced platform.

### Basic Voicemail Setup
Learn how to set up a basic voicemail system with SignalWire, leveraging our powerful APIs to simplify the process and add new capabilities.

### Interactive Voice Response (IVR)
Discover how to build a sophisticated IVR system with SignalWire, using our low-code options to create flexible and dynamic customer interactions.

### Call Recording and Forwarding
See how SignalWire streamlines call recording and forwarding, providing real-time analytics and seamless integration with your existing systems.

## Start Building with SignalWire

Ready to take your telecommunications solutions to the next level? [Sign up](https://signalwire.com/signup) for SignalWire today and start building powerful communication applications with ease.

## Join the Community

Join SignalWire's developer community for support, collaboration, and networking. Connect with other developers, share your experiences, and get help from the experts who built FreeSWITCH and SignalWire.

<blockquote>
SignalWire empowers you to focus on your ideas instead of worrying about developing, scaling, maintaining, and overpaying for complex communications technology and services.
</blockquote>

## Contact Us

For more information and personalized assistance, [contact our support team](https://signalwire.com/contact) and let us help you build the future of communication.
263 changes: 263 additions & 0 deletions docs/SignalWire-Examples/office-hours.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,263 @@
# Signalwire Office Hours Call Forwarding examples
## Introduction
In this guide, we will explore various examples of creating office hours call forwarding to agents using different methods: SignalWire Markup Language (SWML), FreeSWITCH, and SignalWire Call Flow Builder. Each method offers unique capabilities and approaches to implementing office hours call forwarding functionality within telecommunication systems.

## FreeSWITCH Dialplan for Office Hours Call Forwarding
## Introduction
This FreeSWITCH dialplan configuration forwards incoming calls to an external number during office hours (Monday to Friday, 9 AM to 6 PM). Outside of these hours, the calls are sent to voicemail.

### Dialplan Configuration
The following XML configuration should be added to your FreeSWITCH dialplan (e.g., `dialplan/default.xml`).

```xml
<extension name="office_hours">
<condition field="destination_number" expression="^(10[01][0-9])$">
<action application="export" data="dialed_extension=$1"/>
</condition>
<!-- Condition for Monday to Friday, 9 AM to 6 PM -->
<condition wday="1-5" hour="9-17">
<action application="set" data="hangup_after_bridge=true"/>
<action application="set" data="continue_on_fail=true"/>
<action application="bridge" data="sofia/gateway/signalwire/+198XYXYXY"/>
</condition>

<!-- Default condition to send the call to voicemail -->
<condition>
<action application="answer"/>
<action application="sleep" data="1000"/>
<action application="voicemail" data="default ${domain_name} ${dialed_extension}"/>
</condition>
</extension>
```
### Explanation

1. **Working Hours Condition (9 AM to 6 PM, Monday to Friday):**
- The condition checks if the current time is within the specified working hours.
- Sets `hangup_after_bridge` to `true` to ensure the call is terminated after the bridge completes.
- Sets `continue_on_fail` to `true` to continue executing the dialplan if the bridge action fails.
- Bridges the call to the external number via the specified SIP gateway during working hours.

2. **Default Condition (Outside Working Hours):**
- Acts as the fallback condition when the working hours condition is not met.
- Answers the incoming call.
- Pauses for 1 second (1000 milliseconds).
- Sends the call to voicemail for the specified domain and dialed extension.

### Adjustments

- Replace `${domain_name}` with your actual domain name.
- Replace `+198XYXYXY` with the actual phone number you want to forward calls to during working hours.

### How to Use

1. **Update the Dialplan**: Copy the XML configuration into your FreeSWITCH dialplan file (e.g., `dialplan/default.xml`).
2. **Reload the Dialplan**: After updating the dialplan, reload it using the FreeSWITCH CLI:
```bash
fs_cli -x "reloadxml"
```

## SignalWire SWML for Office Hours Call Forwarding
### Introduction
In this guide, we will explore an example of using SignalWire Markup Language (SWML) to create office hours call forwarding. SignalWire Markup Language (SWML) is a scripting language used to control the behavior of voice calls, such as initiating calls, playing audio, recording messages, and more.

**Description:**
This SWML script is designed to handle incoming calls and forward them to a specific number during office hours (Monday to Friday, 9 AM to 6 PM). It also provides a message informing callers about the office hours and requests them to call during that time frame.

```json
{
"sections": {
"main": [
"answer",
{
"request": {
"method": "GET",
"save_variables":true,
"url": "https://f47d-103-52-38-2.ngrok-free.app/is_working_hours"
}
},
{
"switch": {
"case": {
"success": [
{
"cond": [
{
"then": [
{
"connect": {
"from": "+16XYXYXYX",
"to": "+198XYXYXYX"
}
},
{
"switch": {
"case": {
"connected": [
{
"transfer": "ZYFRTspBKf-34skFsEoO8"
}
]
},
"default": [
{
"switch": {
"case": {
"noAnswer": [
{
"transfer": "ZYFRTspBKf-34skFsEoO8"
}
],
"busy": [
{
"transfer": "ZYFRTspBKf-34skFsEoO8"
}
],
"decline": [
{
"transfer": "ZYFRTspBKf-34skFsEoO8"
}
],
"error": [
{
"transfer": "ZYFRTspBKf-34skFsEoO8"
}
]
},
"default": [
"hangup"
],
"variable": "connect_failed_reason"
}
}
],
"variable": "connect_result"
}
}
],
"when": "%{request_response.isInWorkingHours} == true"
},
{
"else": [
{
"play": {
"url": "say:Our office hours are from Monday to Friday, spanning 9 AM to 6 PM. To connect with our agents, kindly place your call during this time frame. We look forward to assisting you!",
"say_language": "en-US",
"say_gender": "female",
"say_voice": "gcloud.en-US-Standard-C"
}
},
{
"transfer": "ZYFRTspBKf-34skFsEoO8"
}
]
}
]
}
]
},
"default": [
{
"play": {
"url": "say:Oops! Something's not quite right on our end. Please try calling back later. Thank you!",
"say_language": "en-US",
"say_gender": "female",
"say_voice": "gcloud.en-US-Standard-C"
}
},
{
"transfer": "ZYFRTspBKf-34skFsEoO8"
}
],
"variable": "request_result"
}
}
],
"ZYFRTspBKf-34skFsEoO8": [
{
"hangup": {
"reason": "hangup"
}
}
]
},
"version": "1.0.0"
}
```


### Breakdown and Explanation:
1. **Answer**: The call is answered to initiate the communication process.
2. **Request**: A GET request is made to the specified URL to check if the current time is within working hours.
3. **Switch**: Depending on the success of the request, the script either forwards the call to the specified number or plays a message indicating office hours.
- **Success Case**:
- If the request is successful and the current time is within working hours:
- The call is connected from the specified number to the destination number.
- If the call is successfully connected, it is transferred to the specified endpoint (`ZYFRTspBKf-34skFsEoO8`).
- If the call cannot be connected for various reasons (e.g., no answer, line busy, etc.), it's transferred to the specified endpoint (`ZYFRTspBKf-34skFsEoO8`).
- **Default Case**:
- If the request fails or the current time is outside working hours:
- A message is played to inform the caller about the office hours and to call during that time frame.
- After playing the message, the call is transferred to the specified endpoint (`ZYFRTspBKf-34skFsEoO8`).
4. **Hangup**: Finally, if the call cannot be connected or handled, it is hung up with the reason specified as "hangup".

5. **Configuration Note**: The URL in the request needs to be replaced with the actual Ngrok URL/public URL containing the provided Node Express code to determine working hours.

**Version:**
This SWML script version is "1.0.0".

***NodeJS Expess code***
```javascript
const express = require('express');
const app = express();

// Middleware to check time and day
app.use((req, res, next) => {
const now = new Date();
const hour = now.getHours();
const day = now.getDay(); // Sunday is 0, Monday is 1, and so on...

// Check if current time is between 9 AM and 6 PM and if it's Monday to Friday
if (hour >= 9 && hour < 18 && day >= 1 && day <= 5) {
res.locals.isInWorkingHours = true;
} else {
res.locals.isInWorkingHours = false;
}
next();
});

// Route to handle requests
app.get('/', (req, res) => {
res.send('Welcome! The service is available.');
});

// Route to check if it's working hours and return JSON
app.get('/is_working_hours', (req, res) => {
res.json({ isInWorkingHours: res.locals.isInWorkingHours });
});

// Start server
const port = 3000;
app.listen(port, () => {
console.log(`Server is running on port ${port}`);
});

```

## SignalWire Call flow builder for Office Hours Call Forwarding

### Introduction
In addition to traditional scripting methods like SignalWire Markup Language (SWML), SignalWire offers a user-friendly drag-and-drop interface called SignalWire Call Flow Builder. This intuitive tool allows users to create complex Interactive Voice Response (IVR) systems visually, without extensive coding knowledge.

SignalWire Call Flow Builder empowers users to design IVRs by arranging various call flow elements such as connect, join_room, play, switch, etc., using a simple drag-and-drop interface. This approach streamlines the process of building telephony applications, enabling rapid development and iteration cycles.

Now, let's create an example for Office Hours Call Forwarding step-by-step using SignalWire Call Flow Builder, accompanied by screenshots to guide you through each stage of the process.

Create call flow with nodes shown in the picture below
![image](https://github.com/ShashiKumar-SignalWire/SW-example-Docs/assets/45973234/80172702-a13f-469d-b037-32afbf222a9d)


In the request node add URL, Method GET/POST, and enable Set Variables as shown in the screenshot below:

![image](https://github.com/ShashiKumar-SignalWire/SW-example-Docs/assets/45973234/bbc436c8-e190-4367-a652-6b2c723dd647)

Once you've configured the call flow, click on "Deploy" to activate it. and Configure the SWML script to use your SignalWire phone number (you can refer to the Purchase a phone number guide for assistance) and save the changes.
26 changes: 26 additions & 0 deletions docs/SignalWire-Examples/sip-endpoint-registration.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
## Setting up a SignalWire SIP Endpoint in FreeSWITCH

To register a SignalWire SIP endpoint in FreeSWITCH, follow these steps:

1. Set up a SIP endpoint in the SignalWire space.
- You can create a SIP endpoint manually within your SignalWire Space or programmatically through the [Create A SIP Endpoint API](https://developer.signalwire.com/apis/docs/rest/2020-12-11/account/sip-endpoints/create-a-sip-endpoint).
- If you want to create a SIP endpoint in your SignalWire Space, visit the SIP tab and click "Create a Sip Endpoint."
![image](https://github.com/ShashiKumar-SignalWire/SW-example-Docs/assets/45973234/f385b59c-023e-413d-b7e6-07765e2b5b43)

- You will need to set a few things: the username you will register your SIP endpoint as, a password to authenticate your endpoint when registering, which SignalWire or verified phone number you would like to show when dialing a PSTN number (if left blank, a random number from your purchased numbers will be chosen), encryption status, an outbound call policy (whether to allow calls to PSTN), and the default codecs/ciphers you would like to use. You can create a SIP endpoint programmatically by making a POST request to the SIP Endpoint resource.

2. Configure the SIP endpoint in FreeSWITCH.
- First, follow the official FreeSWITCH documentation [link](https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Configuration/Sofia-SIP-Stack/Gateways-Configuration_7144069/) to create a gateway.
- Create a new XML file in your FreeSWITCH `conf` directory under `sip_profiles/external/` and name it `signalwire_gateway.xml`.

```xml
<gateway name="signalwire_gateway">
<param name="proxy" value="example.sip.signalwire.com"/> <!-- SignalWire SIP endpoint URI -->
<param name="extension-in-contact" value="true"/>
<param name="username" value="username"/> <!-- SignalWire SIP endpoint username -->
<param name="password" value="password"/> <!-- SignalWire SIP endpoint password -->
<param name="transport" value="udp"/>
</gateway>
```

- Now, go to fs_cli and then execute reloadxml. After a successful XML reload, execute reload mod_sofia, and to see your gateway in fs_cli, execute sofia status.
Loading
Loading