Managed Connection : SignalWire

What is SignalWire?

SignalWire allows us to send and receive text messages globally using applications like VoiceWorx platform.

The VoiceWorx platform allows for the rapid integration of SignalWire Text message service to various voice channels such as, Alexa, Lex, Google Assistant and more.

Prerequisites

• You need to have an active SignalWire account

• Enough balance so you can send messages.

• Configuration

  • Base URL

  • Project ID

  • Auth Token

  • Phone Number

To get the required information, Log into your SignalWire Sign In Page. You should a screen like this.

Enter your space to continue.

Once logged in, go to “API Credentials” page by clicking on API menu in left as shown in below screenshot.

From this page, copy Project ID, Space URL and Token as we will need this to apply on VoiceWorx platform.

If you do not have any token created before, you can create a new token by clicking on +New button. This will redirect you to create a New API Token screen as shown below. Enter name and click on save to create it.

Once saved, you should be back on the API Credentials screen as shown in previous screenshot.

Now, to get the phone number, click on the “Phone Numbers” menu at left, you should see a screen as shown below. If you do not have any number, you can purchase one by clicking on +New button.

Now you are ready with above prerequisites, you can configure it on VoiceWorx platform.

Configure SignalWire with VoiceWorx platform:

To Configure SignalWire, browse to: Integration > Connect System > Connect External System in the VoiceWorx platform and select options as shown below.

On the configuration screen, provide the required information as shown below.

You should be already familiar with the above required configuration as it is explained in the prerequisites section of this document.

Configuration	Info
Service Instance Name	Give any name of your choice
SignalWire Base URL	https://spacename.signalwire.com/api/laml/2010-04-01 In above URL, Just replace spacename by your actual SignalWire space name.
SignalWire ProjectId	Project ID as explained above.
Auth Token	Auth Token as explained above. This behaves like a password.
SignalWire Number	One of the 10-digit phone number (without +1) that you have purchased on SignalWire. Make sure to remove any extra characters like +, - etc.

Once you have saved settings, browse to: Custom Skills > Manage Skills and create a new Custom Skill by clicking on “Create New Custom Skill” button.

Now, create a Data Source for the SignalWire by navigating to Data Source tab in the same screen.

Now you can create methods for the SignalWire Instance.

As of the publication of this document, the VoiceWorx platform supports following SignalWire methods,

1. SendTextSMS

2. SendSMSWithMedia

Create App in VoiceWorx

On Manage Apps menu under Custom Apps menu in the left navigation, click on New Custom App.

Fill up following details to create app.

Name: SignalWire Demo

Custom App Type: Search

Category: Default

Click on Save.

Next step is to create a datasource that communicates with the integration created in Step 2.

After the data source has been created, we now have to create methods. VoiceWorx supports

1. SendTextSMS

2. SendSMSWithMedia

Send Text SMS

Parameter	Sample Value	Info
ToNumber	{{ToNumber}} E,g.one of the purchased phone numbers in SignalWire	A phone number which is going to receive the message. Note: If you are using SignalWire Trial account only, there are some limitations. You can use only one of the SignalWire trial phone numbers.
Body	{{Message}}	Actual Message Content. Note: {{}} represents that the value for these parameters are going to be read from the user as input.

Fill the following details:

Parameter	Info
Method Name	SendTextSMS
Request Type	SendTextSMS This is the method that you are using
Parameters	As explained in table above
Result Type	Record It indicates that the method can return a single record.
Record JsonPath	Each method returns data in json format and to pick any specific information from the json, we need to specify the Record JsonPath so Voice Worx platform will pick that data in consideration while displaying results. Example: $.[*] This selects all the records that is returned.
Empty Result Template	I'm sorry, there was problem delivering your message to {{Input.ToNumber}}. Please try again, How else can I help you? Note: Anything written in between {{ }} is represented as a json field and it’s case-sensitive. Input.* refers that you are taking that value from the inputs provided above.
Result Template	Your message has been delivered to {{Input.ToNumber}}. How else can I help you?

You can now test the method. On the actions menu, click on Test, provide the parameter value and

Click on Method Test . You can observe the return from method in Object tab and the result displayed to user in Result Tab.

Send SMS With Media

Parameter	Sample Value	Info
ToNumber	{{ToNumber}} e.g. 6787014967	A phone number which is going to receive the message. Note: If you are using SignalWire Trial account only, there are some limitations. You can use only one of the SignalWire trial phone numbers.
Body	{{Message}} e.g. Hello there	Actual Message Content
MediaURL	{{MediaUrl}} e.g['https://voiceworx.ai/assets/images/vw-logo-100.png']	Public URL for the media content.

Fill the following details:

Parameter	Info
Method Name	SendSMSWithMedia
Request Type	SendSMSWithMedia This is the method that you are using
Parameters	As explained in table above
Result Type	Record It indicates that the method can return a single record.
Record JsonPath	Each method returns data in json format and to pick any specific information from the json, we need to specify the Record JsonPath so Voice Worx platform will pick that data in consideration while displaying results. Example: $.[*] This selects all the records that is returned.
Empty Result Template	I'm sorry, there was problem delivering your message to {{Input.ToNumber}}. Please try again, How else can I help you? Note: Anything written in between {{ }} is represented as a json field and it’s case-sensitive.
Result Template	Your message has been delivered to {{Input.ToNumber}}. How else can I help you?

You can repeat the same method to test the method. Following screen shows a sample response.

Create Intents:

Create Intents corresponding to the methods.

1. SendTextSMSIntent

Details

Name: SendTextSMSIntent

Intent Type: Search

Intent Action: Execute Method

DataSource :SignalWireDS

Data Source Method: SendTextSMS

1. SendSMSWithMediaIntent

Details

Name: SendSMSWithMediaIntent

Intent Type: Search

Intent Action: Execute Method

DataSource : SignalWireDS

Data Source Method: SendSMSWithMediaI

Create Slots:

Slots represent the parameters for the intents. You shall create slots of the exact same name as the parameters used in the method. Slots map to the parameters of the method.

1. SendTextSMSIntent

Details:

Name: ToNumber

Slot Order: 0 or 1

Reprompt message: what’s the phone number

Type: Number

Custom App: SignalWire Demo

Intent: SendSMSWithMediaIntent

Name: Message

Slot Order: 3

Reprompt message: what’s your message

Type: Full Name

Custom App: SignalWire Demo

Intent: SendSMSWithMediaIntent

1. SendSMSWithMediaIntent

Details:

Name: ToNumber

Slot Order: 0 or 1

Reprompt message: what’s the phone number

Type: Number

Custom App: SignalWire Demo

Intent: SendSMSWithMediaIntent

Name: MediaUrl

Slot Order: 2

Reprompt message: please provide the media url

Type: Text

Custom App: SignalWire Demo

Intent: SendSMSWithMediaIntent

Name: Message

Slot Order: 3

Reprompt message: what’s your message

Type: Full Name

Custom App: SignalWire Demo

Intent: SendSMSWithMediaIntent

Note: If you have slot with same name in different intents of the same app, e.g. Message slot in above example, make sure that their type is also same , otherwise you might encounter error in further steps.

Create Utterances

Utterances are the short texts that invoke the intent. You have to define a unique utterance for each method.

1. SendTextSMS

Details

Value: send text message

Custom App: SignalWire Demo

Intent: SendTextSMSIntent

1. SendSMSWithMedia

Details

Value: send multi media message

Custom App: Twilio Demo

Intent: SendSMSWithMediaIntent

Create Input

The next step is to create input for the intents. Create Inputs corresponding to every intent. You need to create and manage parameters corresponding to the slots for each intent. For example for SendTextSMSIntent, you had two slots: “ToNumber” and “Message”, hence for SendTextSMSInput , you need to create two parameters: “ToNumber” and “Message”. Let’s look into the process in the following screens:

1. SendTextSMSInput

Click on Manage parameters on the action menu.

Click on Input Parameters and provide the details as shown below in the resulting pop up: Make sure to map the Input parameter to the same parameter. Also be careful of the data type used. It should be similar/ compatible with the data type of the slot.

Let’s Add another parameter “Message”.

1. Send SMSWithMediaInput

Repeat the same process for SMSWithMediaIntent. Create Input “SMSWithMediaInput” and create parameters.

Parameter Details:

Details:

Name: ToNumber

Slot Order: 0 or 1

Reprompt message: what’s the phone number

Type: Number

Custom App: SignalWire Demo

Intent: SendSMSWithMediaIntent

Name: MediaUrl

Slot Order: 2

Reprompt message: please provide the media url

Type: Text

Custom App: SignalWire Demo

Intent: SendSMSWithMediaIntent

Name: Message

Slot Order: 3

Reprompt message: what’s your message

Type: Text

Custom App: SignalWire Demo

Intent: SendSMSWithMediaIntent

Create Publish Profile

Once you’ve completed all of the above steps, your app is now ready to be publish to VoiceWorx supported channels. Let’s set up a publish profile.

Details:

External App Name: SignalWire Name

App Type: Search

Channel: Alexa

Skill Invocation: signalwire messaging

Messaging: all of the messages shall be auto populated. You would want to double check and confirm all of the messages are provided.

Click on Save and you shall see the publish profile in VoiceWorx portal. Click on the actions menu and then on Publish to Alexa.

Once the publish profile is created. On the action menu, Click on Publish to Alexa. Select the appropriate LWA account and click on publish.

On success, you shall get a similar screen

Click on Go to Alexa Skill. It will redirect you to Alexa developer console, where you can start testing your app starting with the skill invocation text defined in previous step.

For further details on app building, you can refer to this document for required guidance on building the remaining steps of app building.