Using Oracle Integration Cloud and Twilio to send SMS with REST

In this tutorial I will be teaching users how to use both the Twilio and Oracle Integration Cloud Platform to send messages.


Prerequisites:

  1. Oracle Integration Cloud (OIC) Subscription. (https://www.cloud.oracle.com)
  2. Twilio Account with registered phone number. (https://www.twilio.com/)
  3. Rest Client such as Post Man. (https://www.getpostman.com/)

To get the necessary information from Twilio, you need to navigate to the dashboard (https://www.twilio.com/console). From the home page you will see a “Project Info” panel that has the required info needed for the next sections that you need to save. These being “ACCOUNT SID” and “AUTH TOKEN”. Take out a note pad and save these codes, but do not share them with anyone as it will give others access to your Twilio account.

Next, you will want to navigate to the page that contains your phone number that you registered as noted in the prerequisites (https://www.twilio.com/console/phone-numbers/incoming). On the page you will see the phone number registered to your account in the format “+1 999-999–9999.” On the same notepad that you saved the “ACCOUNT SID” and the “AUTH TOKEN,” save the phone number in the format of “+19999999999.” The format requires a “+” and a “1” in the beginning as well as no “-” in order for the message to be sent correctly.


After saving your information to a notepad or safe place, navigate to your Oracle Integration Cloud Page and then go to the “Connections” Section.

Click on the Create button and then select Twilio from the list of options.

One the Twilio section is selected you will want to name it something you can remember. Set the Role to “Invoke,” which should be the default. After clicking create, then you should have an option to “Configure Security.” Once opening “Configure Security” you can use the “ACCOUNT SID” and the “AUTH TOKEN” that was saved earlier and then “Test” and “Save” the connection.


After created the connect you are now ready to test create the Integration. Head back to the menu and choose the “Integrations” section. Once there you will be able to see all the previously created Integrations. As with before click on “Create” and choose “Orchestration”. Give the Integration a name you will remember and set it as an “Application event or business object,” that way it will run when triggered rather than a set period of time.

When done with this fairly basic integration it should look like this:

Completed Integration
REST connections under the Invokes Tab

Upon creating the Integration you will be presented with a blank canvas. From here you can choose what connections will be used and how they interact with other connections and data. To begin click on the “Invokes” tab on the right and then choose a simple REST connection to drag onto the canvas onto the “+” which should have now grown larger.

Upon dropping the REST connection onto the canvas a menu will pop up. You may call it anything you want. In my case I called it something simple such as “Sample Rest Endpoint.” You will also want to give a relative resource URI so that you can call this specific integration when working with ICS and set the action to “GET”, in my case I called it “/sendsms/”. This will come up again when we use Postman to call the SMS. Scroll down and check the “Custom” boxes in the Configure Request and Response Headers. After selecting these boxes you should be able to configure the header which the REST call will look for when sending a call to the Integration Cloud. In my case I set the request and response headers to “smsnumber”. After completing the connection and clicking done, you will be sent back to the Integration canvas.

Configuring the REST Endpoint.

After setting up the REST endpoint, you will see a new option called “Map to XXXXXX” which will correlate to the REST endpoint which was just created. We won’t use this at this moment. First we need to add the Twilio connection. Under the “Invokes” section select the “Twilio” tab and drag over the Twilio connection which was created in the previous section to the “+” that is only visible below the “Map to XXXXXX” when dragging. Once again you will be presented with a menu that shows the dialog similar to the earlier REST invoke. You may call this whatever you like that helps you know what the connection actually involves. In my case I called it “Twilio_Call”. Under the operations choose” Send SMS or MMS”.

The Twilio Connection upon completion.

Now we will configure the mappings. This is where the magic of Oracle Integrations come into play. Click on the “Map to Rest_Endpoint”, and then click the pencil. You will be presented with a different menu than previously seen. For this simple mapping we will just want to drill down the execute>HTTPHeaders>CustomHTTPHeaders>smsnumber and then drag it over to the executeResponse>HTTPHeaders>CustomerHTTPHeaders>smsnumber. Save the mapping to return to the canvas.

Complete Sample REST Endpoint Mapping

Now click the pencil after clicking on the “Map to Twilio_Call”. This is where you will be mapping the actual SMS message. Similar to the step before map the execute>HTTPHeaders>CustomHTTPHeaders>smsnumber and drag it to the sendMEssage_POST>accountResource.definitions.requestPayload_newSMS>To. This is means that the number you set for the the header is the number that will receive the text. In the “From” field, click on it to edit and add the “+19999999999” format number that you previously wrote down on a number pad (without quotes), which was pulled from your Twilio account. Now click on “Body” and edit to be whatever you want to send to the number receiving the text. “Validate” and “Save” the mapping. Now you will be able to save the Integration and set the tracking. Use any variable you wish to track.

URL for your newly created Integration.

Once the Integration is activated you will be presented with a URL. Make sure to save this URL to use in Postman. If you click on this url it will take you to a page that asks for you Oracle Cloud credentials to log in and then present you with all the resources available from the Integration.


The final portion of this tutorial is the culmination of all your work. Open up Postman and paste in the URL of your integration. The URL should look something like “https://XXXXXXXXXXXXXX.us2.oraclecloud.com/integration/flowapi/rest/TWILIO_INTEGRATION/v01/sendsms”

In order for your Integration to be called you will want to go to the Authorization tab, choose “Basic” and then enter your credentials for the Oracle Integration account. After entering this information click “Update.

Authorization tab within Postman

Once the authorization is complete, navigate to the “Headers” tab. You should now see a field that has “Authorization” with the “value” filled in. In another “key” field add in “smsnumber” and with the corresponding “value” field enter the phone number you wish to text with a “+” prepending the number.

The completed Headers tab

Upon clicking the “Send” button, the phone number in the “smsnumber” field should have a text sent to it that has a message with the value of the “Body” that was set in the “Map to Twilio_Call.”

Congratulations, you have now send a basic SMS call using Twilio, REST, Postman, Oracle Integration Cloud.