Engine Works

Under the hood of Alteryx: tips, tricks and how-tos.
Alteryx Alumni (Retired)

Prerequisite: A Twilio Account

To get set up:

  1. Sign up for a Twilio account
  2. Select SMS, IT Service Alerts, JavaScript, and Not a Production App
  3. Enter Alteryx Alerts as the project name
  4. Click Get a number
  5. Choose this number
    • Save this number - you'll need it when configuring the Twilio SMS tool
  6. Enter a message and send it to your phone as a test
  7. Save the Account SID and Authorization Token - they'll be needed to configure the Twilio SMS Alert tool
    • These can be found in the curl example shown on Twilio. First, check the Show your Auth Token checkbox. Both credentials can be found after the -u argument (e.g., Account SID: Authorization Token) in the curl example.


The Twilio SMS Alert tool is similar to the Message tool. The Message tool allows you to write messages specific to a workflow to the Results window; whereas, the Twilio SMS Alert tool allows you to send text messages. An example use case related to monitoring data quality would be to use the tool to send an alert when an incoming data stream contains unexpected nulls. You can even use the tool to notify you when a workflow is finished running. The tool can be found on my Github page - download the TwilioSMSAlert.yxi.



Configuration only requires five or six entries/selections. Credentials are entered in the top section. You'll need to enter your Twilio Account SID, Authentication Token, and Phone Number in their respective text fields. Your credentials can be found in your Twilio account (i.e., steps 5/7 of Prerequisite: A Twilio Account).

The Message Options selections are based on incoming data stream fields. The To field requires a phone number in a <code>+1555555555</code> format. The Body field can be any text, up to 1600 characters. The Media URL field is optional and requires an address to a hosted image (e.g., gif, png, jpg up to 5mb).

Figure 1:  Twilio SMS Alert configuration interfaceFigure 1: Twilio SMS Alert configuration interface


The Twilio SMS Alert tool uses the HTML GUI SDK to provide an HTML configuration interface. Building a tool with the HTML GUI SDK gives you a choice of either a Python or Macro engine. For this tool, I decided to use a macro since the engine side of the tool is fairly straightforward.


Frontend - HTML GUI SDK


The frontend was built using an HTML file and no added JavaScript (outside of what is provided by the HTML GUI SDK). Below is a snippet of the code that creates the widgets:


  <legend class="tool-legend">Twilio SMS Alert</legend>
  <label class="section-header">Credentials</label>
  <ayx data-ui-props='{type:"TextBox", widgetId:"accountSID", placeholder:"Account SID"}' data-item-props='{dataName:"accountSID", dataType:"SimpleString"}'></ayx>
  <ayx data-ui-props='{type:"TextBox", widgetId:"authToken", placeholder:"Authentication Token"}' data-item-props='{dataName:"authToken", dataType:"SimpleString"}'></ayx>
  <ayx data-ui-props='{type:"TextBox", widgetId:"from", placeholder:"Twilio Phone Number"}' data-item-props='{dataName:"from", dataType:"SimpleString"}'></ayx>
  <label class="section-header">Message Options</label>
  <ayx data-ui-props='{type:"DropDown", widgetId:"to", searchable:true, clearable:true, placeholder:"To"}' data-item-props='{dataName:"to", dataType:"FieldSelector"}'></ayx>
  <ayx data-ui-props='{type:"DropDown", widgetId:"messageBody", searchable:true, clearable:true, placeholder:"Body"}' data-item-props='{dataName:"messageBody", dataType:"FieldSelector"}'></ayx>
  <ayx data-ui-props='{type:"DropDown", widgetId:"mediaUrl", searchable:true, clearable:true, placeholder:"Media URL (optional)"}' data-item-props='{dataName:"mediaUrl", dataType:"FieldSelector"}'></ayx>

Figure 2: Code snippet from TwilioSMSAlertGui.html


The frontend consists of six widgets that are defined within the TwilioSMSAlertGui.html file using <ayx> tags. The first attribute of the ayx tag, data-ui-props, defines the widget type and properties of it. The data-item-props attribute defines the data item properties which will be used to determine how data will be connected to the engine file.


Backend - Alteryx Macro

Figure 3:  Screenshot of the frontend and corresponding Interface toolsFigure 3: Screenshot of the frontend and corresponding Interface tools

The first step when using a macro as an engine is linking the frontend widgets to corresponding Interface tools. The Account SID, Authentication Token, and Twilio Phone Number fields are linked to Text Box tools. The Message Option fields are slightly more complicated and use Drop Down tools populated with incoming field names through a link to a Macro Input tool.


 Figure 4:  Screenshot of the field selection section of the engine macroFigure 4: Screenshot of the field selection section of the engine macro

The Field Selection portion of the macro is concerned with bringing in records associated with the To, Body, and MediaURL fields selected from the interface. The Macro Input tool feeds in an incoming data stream. Dynamic Select tools are configured using Question Constants to select only the field chosen in the Message Options drop-downs. Question Constants are great to use when you want to reference Interface tool values without using Action tools. The benefit is that your workflow looks cleaner but at the cost of readability in knowing where Interface tool values are referenced throughout your workflow. The Text Input and Union tool combinations are used to populate placeholder metadata downstream and avoid error messages. The Dynamic Rename tools are then used to rename the fields to To, Body, and MediaURL. This is done so that downstream tools can be configured using known field names.


Figure 5:  Screenshot of the API Prep & Call section of engine macroFigure 5: Screenshot of the API Prep & Call section of engine macro

The API Prep & Call section of the macro creates Authorization, URL, and From fields and POSTs the To, Body, and MediaURL to the Twilio API. The Authorization field is a combination of Account SID and Authentication Token (e.g., accountSID:authToken) that is Base64 encoded and prepended with 'Basic'. The URL field is created using the accountSID and the Twilio API SMS endpoint. The Download tool has a straightforward configuration. The Basic tab has URL selected as the URL field. The Headers tab passes the Authorization field and the Payload tab POSTs the To, From, Body, and MediaUrl fields.


Figure 6:  Screenshot of the Response Messaging section of engine macroFigure 6: Screenshot of the Response Messaging section of engine macro

The final section of the engine macro handles the API response and outputs the data stream. RegEx is used to parse the API response data and determine if the API call was successful. If the API call was unsuccessful, an error is thrown by the Message tool.



The Twilio SMS Tool is a good example of the extensibility and flexibility that is provided by the Alteryx Platform. You can use this tool as a template for creating additional tools that access a 3rd party API. If you would like to make tweaks to the tool or understand it further you can find the source files in my Github repo twilio-sms-alert-tool.

Stephen Wagner
Product Manager, Technology Alliances

Stephen Wagner is a Product Manager, Technology Alliances with a passion for enabling users to take full advantage of the Alteryx platform. Stephen’s background includes analyzing sales, marketing, and operational data for a Fortune 50 retailer, as well as data visualization development as an Analytics Consultant.

Stephen Wagner is a Product Manager, Technology Alliances with a passion for enabling users to take full advantage of the Alteryx platform. Stephen’s background includes analyzing sales, marketing, and operational data for a Fortune 50 retailer, as well as data visualization development as an Analytics Consultant.

Alteryx Alumni (Retired)

Very cool! Just tested it out on my own, works great. Thanks for sharing Stephen!

8 - Asteroid

This is really cool. Always wanted to figure out something similar.




ACE Emeritus
ACE Emeritus

Hi @StephenW, I am looking to have a play with this because I can see many ways this would interest our clients however I'm struggling to get the same flow as your getting in your initial steps.


Would you be able to post screenshots of you walking through this initial setup, or even better a video? 


Will be really useful to helping not only me get started but I'm sure many others too!



Alteryx Alumni (Retired)

@BenMoss I've attached a PDF with instructions and screenshots to the main post.  Please let me know if there's anything that requires clarification.

ACE Emeritus
ACE Emeritus

@StephenW this documentation is perfect! Thank you! Message successfully sent.



7 - Meteor


I couldn't find this path: 

  1. Select SMS, IT Service Alerts, JavaScript, and Not a Production App

Can anyone help me please?

Alteryx Alumni (Retired)

Hi @Luciano-Vasconcelos


Take a look at Twilio SMS Alert Account Creation Instructions.pdf.  It should help clarify how to setup the Twilio account.  The Twilio setup path may have changed, so use your best judgement if it doesn't match the PDF exactly.

7 - Meteor


I'm reading it.




Is there any reason why this macro is not listed under 'Workflow Assets' when uploading to the Gallery. Does it require installation on the server instead of packaging?


Thanks in advance for your help!


@wendysdbcb for visibility

Alteryx Alumni (Retired)



Yes, it'll need to be installed on the Server.

8 - Asteroid

I keep getting the error "Message body required" - I'm just using a text input tool arranged like this:

toPhone              messageBody           mediaURL

+353(xxxxxx)        Test message


which then leads to the Twilio text message tool I downloaded from your Github. I populated the configuration window with my credentials in the top 3 boxes, bottom three I linked to the incoming text fields (toPhone, messageBody, mediaURL). I know that my Twilio account is working as I can send myself an SMS from there.


is there some other configuration step I have missed or usage I need to fix?

Alteryx Alumni (Retired)


I'm thinking that the "Message body required" error is a red hearing. Try changing the toPhone format to something like +1555555555 (i.e., include the country code and remove the parens)



8 - Asteroid

I actually already have the number in that format - 353 is the country code, and I don't have parenthesis in the number that was just me typing something random to hide the true number.


I tried adding a select and formula tool as I noticed the "+" was being dropped as Alteryx was forcing the number to int64 so I changed it to VString and added the "+" back but still no joy...

Alteryx Alumni (Retired)



I'd try to troubleshoot the API calls in a tool like Postman to ensure it's functioning correctly. Once you've got it working, you can then transfer what you've learned to the Alteryx workflow.

7 - Meteor

Hi @StephenW , this is elaborate and quite interesting. However, the URL in the workflow is throwing an error saying it's not valid. Could you please tell me which URL should be used here? Thanks!

6 - Meteoroid

Hi, can this tool send the text as a group text?