Skip to content

Introduction

Twilio’s popularity as a communications Infrastructure as a Service provider makes it an easy choice for any customer interaction scenario that includes in-app VOIP/Telephony or text/picture messaging. The new Neuron ESB Twilio adapter and your Neuron ESB integration infrastructure enables you to quickly add these feature sets to your own services and products.

The Adapter provides easy accessibility to Twilio’s REST API and it supports both publish and subscribe modes. Solicit/response and request/reply patterns are also supported. This enables you to build customer communication scenarios that include you own internal processes in the communications patterns that your customers expect. For example, you can fire off processes that are initiated from customer phone calls or text messages or respond to any event with direct phone calls or texts out to your customer’s mobile devices. Neuron ESB and Twilio turn your business systems into customer retention tools.

Before reading this document

If you are not familiar with Neuron ESB Adapters, take a moment to consult our online help by clicking here. This document assumes you have the following knowledge:

  1. What adapters are and how they are leveraged in Neuron ESB
  2. Register a Neuron ESB Adapter within a Neuron ESB Solution
  3. Create an Adapter Endpoint in a Neuron ESB Solution
  4. Set a Neuron ESB Adapter Endpoint Properties
  5. Invoke a Neuron ESB Adapter Endpoint

Adapter Registration and Setup

The first step in using a Twilio adapter is to register the Adapter in the Neuron ESB Explorer. Afterward you can create the adapter endpoint configuring you and configure the various Twilio property settings.

 Adapter Properties

article-adapter-t1

Send Timeout (Default: 60) - Sets the amount of time to wait for a call to Twilio to complete

Error Reporting (Default: Error) - Sets the type of event that an error is logged as in the Neuron event logs

Account SID - The SID of the Twilio account being used

Auth Token - The authorization token for the Twilio account being used

Base URL (Required for Request-Reply and Publish Modes) - A user-defined and locally-hosted URL that the Neuron ESB adapter for Twilio uses to host a connection to receive HTTP requests from Twilio.  The Base URL must be local to the Neuron installation (i.e. sit on the server that Neuron ESB’s host is running). Therefore, the Neuron ESB server could expose the Base URL directly inside the DMZ or could linked from an external facing load balancer or Proxy.  Messages sent from Twilio to Neuron ESB will be published to the Neuron ESB Topic that is associated with the connector Publisher Party.  You must also configure the Base URL within Twilio.

Custom Message - The custom message sent back to sender for acknowledgment notification

Adapter Modes

article-adapter-t2

Subscribe Mode

When in Subscribe mode, the Twilio adapter will listen for messages on the Neuron ESB bus as a subscriber that is selected from the drop down menu on the General tab of the adapter endpoint.  The adapter will only receive messages from the topic(s) that this subscriber has subscriptions on.  When a message is published to a topic that the adapter subscribes to, the adapter will forward the message on to Twilio.  The message must be correctly formatted XML.  Below is a simple example of a Neuron ESB message passed over the bus to a topic that will send an SMS message to the phone number “+18005551234” from user’s Twilio number “+18005555678” with a body of “Hello, World!”

<SendMessageRequest>

<To>+18005551234</To>

<From>+18005555678</From>

<Body>Hello, World!</Body>

</SendMessageRequest>

There are also commands for viewing a specific message and viewing the list of messages received and sent.  The XML element name used to view a specific message is <ViewMessageRequest>.  The message’s SID is required to get the specific message.  Below is an example Neuron message for retrieving a Twilio message with SID “MM800f449d0399ed014aae2bcc0cc2f2ec”:

<ViewMessageRequest>

<MessageSid>MM800f449d0399ed014aae2bcc0cc2f2ec</MessageSid>

</ViewMessageRequest>

The XML element name used to view a list of messages is <ViewMessageListRequest>.  Users can add the <To>, <From>, and/or <DateSent> elements to the <ViewMessageListRequest> in order to filter by those values.  As an example, listing the messages sent to +18005551234, the message published to Neuron would be:

<ViewMessageListRequest>

<To>+18005551234</To>

</ViewMessageListRequest>

Solicit Response Mode

When in Solicit Response mode, the adapter, much like Subscribe mode, will listen for messages sent over the bus to the topic chosen.  The difference is that Neuron will expect a response from Twilio when a message is sent and the semantic should be “request” for the message published to the bus.  Twilio will automatically return a response to the message sent containing information about the message such as the price of the message, any error codes, the actual message body that was sent, etc...

Publish Mode

When in Publish mode, the Twilio adapter will receive messages sent to the phone number that a user is given from Twilio.  Once a message is received, the adapter will publish it to the bus.  See Base URL under “Setup the Adapter’s Properties” for more information about how to use publish mode.

Request-Reply Mode

As with Publish mode, Request Reply mode receives messages from Twilio that are sent to a user’s Twilio phone number.  The difference is that a reply is expected.  The adapter will wait for a reply to be sent back to it on the bus and then it will send that reply back to the original sender.  The message that is originally sent to the user’s Twilio phone number and that gets published to the bus will have a “request” semantic.  The message that is returned from the subscriber should use the “reply” semantic.