Twilio Spoke v/s Twilio Direct - OR - Integration Hub v/s Notify : ~ The Complete Picture ~

[Nirupam Biswas]

ServiceNow ships two ways to integrate with Twilio, namely - Twilio Spoke and Twilio Direct (which is part of Notify product). In this post I will explain the differences between the two and guide which to use when. So let's get started.

Let me explain the difference using two pictures, which I will then explain.

The above diagram shows a typical interaction with Integration Hub Spokes. In this case "your code" will typically be a Flow in Flow Designer. You will typically invoke the Spoke Actions from your Flow. In case of Twilio Spoke, let us say you invoke Send SMS, then the Action will take care of passing on your request to the Twilio Server. The Action will complete possibly with success or error. A success result does not mean the SMS has been sent, it merely means that Twilio will forward the SMS to network carrier as soon as possible. It is possible that the network carrier is very busy or the receiver's phone is out of network area or switched off. In those cases the SMS might reach after considerable delay or might expire and it never reaches. However, you Flow will never be able to know that.

Another thing to notice is that if you want to use Actions from other Spokes, even if they are functionally equivalent, you will need to make changes to your Flow or code.

The above diagram shows how you use Twilio Direct via Notify. What is clear in the above picture is that your code does not directly interact with Twilio Direct. It goes through Notify provided APIs. Notify is a framework which provides a uniform set of APIs which abstracts away the actual provider. This allows you to write codes which need not change at all when replacing one functionally similar provider with another. Provided that you have a "connector" or "driver" which connects the said provider with Notify. This is similar to Integration Hub where you will need to have the Spoke for the provider to make the call. In fact "Notify Zoom Connector" and "Notify for MS Teams Connector" both actually use their respective Integration Hub Spokes to make the calls to the provider servers! For historical reasons Twilio Direct does not use Twilio Spokes outbound Twilio Rest calls, but technically it can.

Other than the above difference, the biggest differentiating factor is that Notify connectors not only makes outbound calls but also ship inbound event listeners, which allows the provider's server to push events back into ServiceNow instance. Recall the send SMS example which I mentioned before. When sending SMS using Notify, similar to Twilio Spoke, you will get success and failure. However, Notify also ships Data Models (DB Tables) keeps record of all these external entities and their statuses. In this case Notify's send SMS API will ensure to create an entry in notify_message table. Later as and when the SMS delivery status is intimated by Twilio server, Twilio Direct will take care to update that notify_message record's state to delivered or failed as the case maybe. You can then define Flows which are triggered on such updates and you can then do interesting stuffs based on that.

Let's recap the differences in bullet points

	Twilio Spoke	Twilio Direct (Notify)
Pros	Available in Flow Designer. Provides Actions for Twilio account management. Since the setup is manual, you can use the same Twilio account for multiple instances in anyway you please. Very flexible.	Uniform, provider agnostic, API provided by Notify. Provides Twilio server events listener which listens for SMS, calls and conference events. Effectively makes use of Notify provided DB Tables, and ensures their states accurately mirror that on Twilio server. Provides simple one-click express setup experience.
Cons	Requires manual setup which is quite complex and varies depending upon which Twilio Spoke Actions you want to use. All Pros of Twilio Direct are missing in Twilio Spoke.	If you want to make use of this in our custom implementations then it is accessible only in Workflows or scripting. No Flow Actions available as of Rome. The only way to use this in Flows is invoke from Script Actions. Only one Twilio account (or sub-account) can be used per ServiceNow instance (including prods, sub-prods, tests, etc.).

When to use which?

If you want to manage Twilio accounts or just send normal volume of SMSes (and you don't care about their delivery statuses) then Twilio Spoke should be your choice.

If you need to send large number of SMSes and all SMS contain the same message then Twilio provides a Twilio Notify Service API which allows you to send SMS to 10k targets in a single call. This is much more performant than calling send SMS for each number using a loop. Each API call takes approximately 4ms so for 10k numbers it will take around 40s. However, a call to Twilio Notify bulk SMS for 10k numbers will take approximately 10ms. This is supported by Twilio Spoke as well but requires specialised setup and change in the code which is making the bulk SMS call. In case of Twilio Direct, it is a checkbox away. Turning on this feature from Twilio Direct Configuration page is all that is needed.

Making a call from Twilio Spoke will be pain since you will need to create Rest Trigger Flows which are exposed as unauthenticated Rest endpoints. There, not only you will need to understand the internals of Twilio's TwiML XML language but also need to implement your own logic to validate the Twilio payload to ensure that it is actually from Twilio.

In case you want to respond to incoming SMS then you will need to unauthenticated Rest Trigger Flows as above, which is a pain to secure. In case it is easier to just use Twilio Direct.

The rule of thumb is, if you are using Flow Designer and just need to send SMS or manage account then try using Twilio Spoke and see if that works well for you. In all other cases try using Twilio Direct via Notify first.