Extension: Twilio - quandis/qbo3-Documentation GitHub Wiki

The qbo3.Twilio.Message and qbo3.Twilio.Attachment plugins allow users to utilize Twilio Voice, SMS and Fax within QBO. Features include:

• Launch Twilio Voice Calls with any parameter available when creating Twilio Calls.
• Retrieve the details of a Twilio Call.
• Optionally save the details of a call to a QBO Message for record and auditing purposes.
• An endpoint to forward inbound faxes to, in order to save them as QBO Attachment documents.
• Ability to launch any QBO Method Signature when faxes are saved, such as starting a Workflow to identify and parse the document.

In order to work with this plugin, you must create a Standard Twilio API Key to link QBO to your Twilio account.

Twilio API Keys

Insert a QBO Credential using the qbo3.Twilio.Message Setup guide:

• Uri Prefix (Advanced): The value for the plugin setting APIUrl defaulted to https://api.twilio.com/2010-04-01.
• Username: Your API Key's KeySID from Twilio.
• Password: Your API Key's KeySecret from Twilio.

Hit Save to save your credential in the system.

You must now insert your Account SID in the plugin settings to complete the linking of your account with QBO. This is found in Twilio's Console dashboard under Project Name.

Your Auth Token is not required.

Twilio Console

Insert your Account SID into QBO using the Settings tab of the qbo3.Twilio.Message Setup screen. Click the AccountSID setting, and insert the value found in Twilio's Console and hit Save.

You have now linked your Twilio account to QBO and can start utilizing the plugin.

In order to receive faxes redirected from your Twilio fax number with ReceiveFax, you must configure your QBO environment properly in a few different areas.

1. You must allow Twilio's automation to access the QBO environment using Basic Authentication. You can do this by adding the TwilioProxy user-agent prefix to the qbo.Security.Properties.Settings.BasicAuthenticationUserAgents setting, using the bottom most panel on any Security module /Config page. E.g. Gecko/ /21.0;Amazon Simple Notification Service Agent;LogicMonitor;LLC;TwilioProxy

Be careful not to leave a trailing ; character in this setting.

2. Installing the qbo3.Twilio plugin normally includes a Person user named [email protected] to act as the user for Twilio's automation. This Person also comes tied to a Role named TwilioCallback with basic permissions to process faxes. Give this user a password by determining the PersonID assigned to [email protected] and calling .../Security/Person.ashx/SetPassword?PersonID={PersonID Here}&Password={xyz}. Save this password for later steps.

You may discover the PersonID of [email protected] by hovering your cursor over the account in the main User Accounts page and looking at what url it points to. Ensure that your password is URL encoded if it contains any special characters.

3. Your Twilio account must contain a fax number, that is configured to run a TwiML Bin script when A FAX COMES IN. Create a TwiML Bin that redirects incoming faxes as a POST request to the Attachment/Twilio.ashx/ReceiveFax endpoint of your QBO system. Include the [email protected] user and the password previously set with SetPassword as embedded Basic Authentication credentials in the action URL. Ensure that mediaType is set to application/pdf. You may optionally set storeMedia to false if you don't want to save copies of the fax in your Twilio account.

Ensure the embedded Basic Authentication credential contains URL Encoded values, in the format of https://{Username}:{Password}@qbowebsite.quandis.net/Attachment/Twilio.ashx/ReceiveFax.

Example TwiML Bin configured correctly to forward faxes to QBO:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Receive mediaType="application/pdf" storeMedia="false" action="https://TwilioCallback%40Quandis.com:ABC123%[email protected]/Attachment/Twilio.ashx/ReceiveFax"/>
</Response>

With QBO set up correctly, and your Twilio Fax number pointed to the system, you may now begin to receive faxes.

qbo3.Twilio plugins come with Setup screens that contain a tab for different settings that can be customized as needed to change the behavior of each plugin.

There are a number of qbo3.Twilio.Message Settings that you may alter in order to adjust the behavior when Creating a call, retrieving the details of a call, or utilizing SMS.

AccountSID:

The Account SID associated with the Twilio account to use for the plugin, as described in the setup section earlier in this document. This is always required for the plugin, and must be the account that owns the key for the QBO Credential.

DefaultFromNumber:

The default number to use when creating calls as the from parameter. If this is blank, from is always required.

DefaultMethod:

The default HTTP method to use when accessing the final URL used when utilizing twimlBin or twimlUrl, in place of method.

APIUrl:

(Advanced) The API Url to use for the plugin, which must correlate to the URI Prefix used for the QBO Credential.

MappedUser:

(Advanced) The user that Twilio uses to log in to QBO to deliver SMS messages with.

There are a number of qbo3.Twilio.Attachment Settings that you may alter in order to adjust the behavior when receiving a fax.

IncomingFaxTemplate:

You may provide a name of an AttachmentTemplate here to assign as the parent of new saved fax Attachment objects.

IncomingFaxPathURL:

You may change the default PathURL value given to new fax Attachment objects, which defaults to TwilioFaxes/{FileName}. Using {FileName} is recommended in order to ensure PathURL values are unique.

IncomingFaxMethodSignature:

You may provide a standard QBO method signature here, in the form of Module/Method?Paramters=SomeValue. Utilizing {AttachmentID} is recommended to utilize the new fax Attachment. For example, if you wanted to launch a Workflow with each incoming fax, you could define this as Decision/Save?Template=Process Twilio Fax&Object=Attachment&ObjectID={AttachmentID}. The TwilioCallback role must either have all permissions for this method, or simply the permissions to queue the method into an elevated security/administrator queue.

IncomingFaxQueue:

If IncomingFaxMethodSignature is defined, you may specify which queue to use here. If not defined, the default qbo queue will be used instead. You may specify an administrator queue here, but ensure the TwilioCallback role has permissions to push items to this queue.

MappedUser:

(Advanced) The user that Twilio uses to log in to QBO to deliver faxes with.

.../Message/Message.ashx/TwilioCreateCall?...

Launch a new Twilio Voice call.

You can make use of most parameters available to creating a Call, as defined in the Twilio documentation here:

Create a Call

Important: Ensure you click C# in the code example in order to get the correct version of the names of the parameters in the main page. These parameters all start with lowercase, where the usual QBO standard is to start with uppercase, which may make it easier to distinguish between the two.

In order to include these parameters with TwilioCreateCall, besides a few exceptions, pass the parameter while calling TwilioCreateCall by how the parameter is named in the Twilio documentation above with the desired value, respecting casing (record=true, not Record=true).

Be sure to make note of what is required, and what is optional in the documentation, however to summarize:

1. The 'to' parameter is always required.

2. 'from' is required if a DefaultFromNumber is not specified in the Twilio plugin Settings.

3. One of 'twimlBin' (extra parameter we offer), 'applicationSid', 'twimlUrl' (or url from documentation), or 'twiml' parameters is required.

If more than one of these are provided, the first one found is used and the rest are ignored, in this order.

twimlBin:

This is an extra parameter that TwilioCreateCall offers, that allows you to simply provide the SID for a TwimlBin, as opposed to the full twimlUrl. The TwiML Bin SID would come after /twiml/ such as in https://handler.twilio.com/twiml/EH84af16f2e2655ec3490e91a2994235a5 and is also available to copy near the top of the screen when viewing a TwiML Bin script.

twimlUrl(url):

Please use twimlUrl in place of url to define the url where a twiml file can be retrieved.

If calling the service from a brower URL bar or other web request, ensure you URL encode the address so that it passes to the service correctly.

pathAccountSid / accountSid:

Do not use this parameter, as it will be ignored. The Account SID is picked up from the credential used.

SIP Parameters / Headers:

When the to parameter is defined as a SIP address, you can define extra SIP headers to be passed when connecting to the SIP address by appending a query string after the address.

sip:[email protected]?displayName=Alice&customerID=375d1d60-083b-404d&selectedProductID=87144192-73e2-45a6

Template TwiML Bins:

When using twimlBin, or twimlUrl defined as a TwiML Bin, you may pass in extra parameters to the TwilioCreateCall service, where extra parameters will be appended to the twimlUrl address as a query string, effectively allowing the usage of 'template' TwiML Bins to substitute these parameters in the TwiML.

.../Message/Message.ashx/TwilioCreateCall?to=9491112222&from=9492223333&twimlBin=2FEH84af16f2e2655ec3490e91a2994235a5&CustomParameter=12345&CustomParameterTwo=XYZ

statusCallbackEvent / recordingStatusCallbackEvent

For statusCallbackEvent and recordingStatusCallbackEvent, you may pass multiple values using a comma-delimited list without spaces.

...statusCallbackEvent=initiated,answered

.../Message/Message.ashx/TwilioGetCallDetails?...

Retrieves the metadata details of a Call, given a Call SID.

The only parameter used for this service, a Call Resource SID, is as follows.

sid:

The SID of the Call Resource to retrieve. This will be stored in the Message.Message property in QBO if you choose to save Message objects.

You can choose to save QBO Message objects for Call services by using the parameters that follow.

An XML representation will be saved as the BodyText property, the Call Resource's SID will be saved under the label property Message, and finally, the status of the Call Resource will be saved as the Message's Status.

If a Message object already exists with a particular Call Resource's SID, the Message found will be updated as opposed to a new Message being created.

MessageSave:

Whether or not to save Message Objects. If this value is false, the rest of the Message parameters are ignored.

MessageParentObject:

The parent object type name to save the Message with.

MessageParentObjectID:

The ID of the parent object to save the Message with.

MessageTemplate:

The name of the MessageTemplate to bind the Message to.

.../Attachment/Twilio.ashx/ReceiveFax?...

You may receive faxes and save them as Attachment objects by pointing a Twilio fax number to forward incoming faxes to the ReceiveFax endpoint after the steps in the "Setting Up Twilio.Attachment" section are completed. This endpoint is designed to be used by Twilio's automation, and will not function properly otherwise.