CAI + Twilio Quick Start Guide

Version 2

    Overview

    This a guide that will walk through setting up an integration between Informatica’s Cloud Application Integration (CAI) service with the Twilio platform to send text messages and handle the text message responses being sent back. There are several pre-built CAI assets included in this guide to get you started quickly.

     

    What is Twilio?

    Twilio is a popular cloud communications platform as a service that enables you to programmatically make/receive phone calls and text messages via APIs.

     

    Why use Twilio?

    This communications method is a powerful tool for many integration scenarios that are a great fit for App modernization using CAI. Some examples in our daily lives include things like:

    • Getting text message alerts from banking transactions
    • Getting food delivery updates via text message
    • Receiving two factor authentication codes
    • And many more
    • An IICS Trial or production account
    • A Twilio Trial or production account

     

    Pre-Requisites

     

    Importing the Assets

    Import the assets attached below.

    Click here for a video guide on how to import assets into IICS.

     

    Assets included in the Import Package

    1. TwilioServiceConnector
      • Type: Service Connector
      • Details: This asset defines the actions available with the Twilio API service. Send SMS and Read SMS are the two actions included in this asset, but we’ll focus on Send SMS.
    2. TwilioAppConnection
      • Type: App Connection
      • Details: This asset defines the connection details (authentication credentials) needed for the Twilio Service Connector.
    3. Twilio_Post_Example
      • Type: Process
      • Details: A simple process that calls the TwilioAppConnection to send a text message using the Twilio API.
    4. Twilio_WebHook_Response_Example
      • Type: Process
      • Details: A simple process that acts as a webhook API to handle text message responses being sent to a Twilio phone number. It will respond with Yes, No or “Sorry I didn’t understand that” based on the body of the text message sent to the Twilio phone number.
    5. Twilio Post Example Guide
      • Type: Guide
      • Details: A guide that walks you through the Twilio_Post_Example process.

     

    Configuring the assets

    Once the assets are imported, you should configure and publish the assets in the following order:

    1. TwilioServiceConnector:
        1. Update the Test With fields appropriately (ACCOUNT SID, Auth Code)
      1. SendSMS Action:
        1. Update the “Test with” Input field From with your Twilio Sender Phone number and To with your SMS capable test phone number.
        2. Save and test the action’s configuration.
        3. Verify the text message was sent successfully and copy the MessageSID output.
      2. CheckSMS Action:
        1. Update the “Test with” Input field sid with the MessageSID you wrote down from the output of the SendSMS Action test.
        2. Save and test the action’s configuration.
        3. Verify the get call succeeded and that the MessageStatus output is the “Test Message” that was sent as part of the previous SendSMS Action test.
      3. Publish the Service Connection
    2. TwilioAppConnection:
        1. Select the TwilioServiceConnector asset we just published.
      1. Connection Properties
        1. Update the AccountSID value with your Twilio Account SID.
        2. Update the SECRET value with your Twilio Auth Code.
      2. Save and test the connection.
      3. Verify that CheckSMS and SendSMS actions are available under Metadata tab.
      4. Publish the App Connection.
    3. Twilio_Post_Example:
      1. Configure the Send an SMS Service properties
        1. Service: Verify the TwilioAppConnection is selected for Connection and SendSMS is selected for Action.
      2. Save and Publish the process.
    4. Twilio_WebHook_Response_Example:
      1. Configure the Response Sent Back to Twilio Service properties
        1. Service: Verify the TwilioAppConnection is selected for Connection and SendSMS is selected for Action.
      2. Save and Publish the process
      3. Copy the Service URL for the process that’s generated under Properties Detail.
      4. Configure the Twilio Messaging Service Webhook:
        1. Navigate to the Twilio Messaging Service you created in the Prerequisites section, and click on Integration.
        2. Under Incoming Messages, select the Send a webhook option and paste the Service URL that was generated for the Twilio_WebHook_Response_Example process.
        3. Save the changes
    5. Twilio Post Example Guide:
      1. Configure the Twilio_Post_Example Process call properties
        1. Process Call: Verify the Twilio_Post_Example is selected for Process.
      2. Save and Publish the process

     

    Using the Assets

    The assets provided here offer some basic examples of how you could send a text message via Twilio using a process built in CAI, or respond a to text messages that’s sent to your Twilio phone number programmatically using CAI.

     

    Sending a Text Message:

    1. Run the Twilio_Post_Example process using the Twilio Post Example Guide, directly in the process, or via the API. The inputs required are:
      • MessageBody: The text message being sent
      • FromNumber: The Twilio phone number the text message is being sent from.
        Must be in E.164 Phone format (Example +11234567890)
      • ToNumber: The phone number the text message is being sent to.
        Must be in E.164 Phone format (Example +11234567890)
    2. You should receive a Text Message that asks “How is your day going?”

     

    Note: The Twilio_Post_Example process is currently overwriting the MessageBody input to ask "Is your day going well?" to work with the response options provided in the Twilio_Webhook_Response_Example.
    To use this input instead, simply delete the "Define Text Message" Assignment Step.

     

    Responding to a Text Message sent from Twilio:

    1. Reply to the Text message from Twilio with Yes, No, or something else.
    2. Twilio_WebHook_Response_Example Process will be called by Twilio and send an appropriate message back based on your reply.
    3. When configuring inputs for phone numbers using the Twilio service, use the E.164 standard for phone numbers (Example +11234567890 for the U.S. Phone number 123-456-7890)
    4. Responses sent back to Twilio for the webhook calls are required to be sent using a different content-type then what is being sent. Since Twilio doesn’t tell CAI what that content-type is, we must generate an acceptable output by doing the following:
      1. Set the Output format to “Whole payload”, add an Output field Called “TwilioResponse” with the type “Attachment”
      2. Create a temp field called “xml_output” with the type “XML”
      3. Create a temp field called “ResponseMessage” with the type “text”
      4. Add an Assignment step at the very end of the process, and assign the following formula to the TwilioResponse Output field:
        sff:createAttachmentFromBase64('test.xml', util:base64Encode($temp.xml_output , "UTF-8",true()), 'text/xml')
      5. Add another Assignment step before the last and assign the following formula to the xml_output temp field:
        util:toXML(<Response><Message>{$temp.ResponseMessage}</Message></Response>)
      6. Assign an appropriate text response you wish to send back to the ResponseMessage temp field.

     

    Important notes about the Twilio Service:

    1. When configuring inputs for phone numbers using the Twilio service, use the E.164 standard for phone numbers (Example +11234567890 for the U.S. Phone number 123-456-7890)
    2. Responses sent back to Twilio for the webhook calls are required to be sent using a different content-type then what is being sent. Since Twilio doesn’t tell CAI what that content-type is, we must generate an acceptable output by doing the following:
      1. Set the Output format to “Whole payload”, add an Output field Called “TwilioResponse” with the type “Attachment”
      2. Create a temp field called “xml_output” with the type “XML”
      3. Create a temp field called “ResponseMessage” with the type “text”
      4. Add an Assignment step at the very end of the process, and assign the following formula to the TwilioResponse Output field:
        sff:createAttachmentFromBase64('test.xml', util:base64Encode($temp.xml_output , "UTF-8",true()), 'text/xml')
      5. Add another Assignment step before the last and assign the following formula to the xml_output temp field:
        util:toXML(<Response><Message>{$temp.ResponseMessage}</Message></Response>)
      6. Assign an appropriate text response you wish to send back to the ResponseMessage temp field.