Twilio Adapter
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 enable 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 customers 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 the Adapter Overview. This document assumes you have the following knowledge:
- What adapters are and how they are leveraged in Neuron ESB
- Register a Neuron ESB Adapter within a Neuron ESB Solution
- Create an Adapter Endpoint in a Neuron ESB Solution
- Set a Neuron ESB Adapter Endpoint Properties
- 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
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 ESBs 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
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 users 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 messages 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 Adapters 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 users 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 users 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.