Update 06/14/2022 — there is a new article demonstrating how to do more efficient integration between Twilio and TeamDesk using Call URL actions and webhooks.
While TeamDesk does not support sending SMS messages, it is still possible via built-in third-party services integration features. In this article we’ll show how to use Call URL actions and REST API to build SMS chat via Twilio services.
First thing you’ll need is to register an account with Twilio. Once registered, navigate to the console and note Account SID, Auth Token and phone number.
Now, to TeamDesk. At bare minimum, we need a table, say Messages, with two columns: “To” phone number column and “Body” text column. Then let’s set up a change trigger when record is created and attach Call URL action to it. This action will be our workhorse. Set it up as in the following screenshot:
In Authorization section, username is your Twilio Account SID and the password is Auth Token. Account SID also appears in API URL. Request’s Body supplies three parameters: From is your Twilio phone number and To and Body parameters are filled in from columns in our Messages table. Save.
Create new record, type in your phone number in To field in international format (e.g. +15417543010, no spaces or separators), type “Hello” in the Body, save the record and wait for the message to arrive to your phone. Done.
Checking SMS delivery status
Yet, the process of sending message is asynchronous. With API call above you instruct Twilio to queue the message, but it takes some time for the message to be delivered. Or there might be an error due to, say, phone number is wrong. If you are interested in querying delivery status, a bit of extra work is required.
First, we need two more columns in our Messages table. One is Message-ID of text type. It will store unique message identifier reported by Twilio. Another column is Status, also of text type with the word “pending” as default value.
Then we need two assignments to add to “Send SMS…” action to extract message id and current status from Twilio API response:
Response("$.sid") to Message-ID
Response("$.status") to Status
Once we have Message-ID we can then query status with another Call URL action.
It’s setup follows the same pattern as “Send SMS…” action: Account SID and Auth Token is used for username/password pair in Authorization section, Account SID is also the part of the URL. Add
Response("$.status") to Status
assignment and attach the action to either custom button, or time-dependent trigger or both. As status won’t change when it is either delivered, undelivered or failed it might be useful to add
“Status is not one of delivered, undelivered, failed” filter in button/trigger.
Receiving replies
Twilio is capable to handle incoming SMS messages by calling some URL with the phone numbers and SMS content payload. TeamDesk can not receive this data directly, but you can set up Twilio function to get the data, transform it and forward to TeamDesk REST API.
First, create API authorization token in TeamDesk | Setup | Database | Integration API section. Next, in Twilio Console, navigate to Runtime | Functions, create a function and copy there the code from this link.
Adjust config parameters with your database id, API token, table name and columns names if needed.
Save.
Then add reference to got package version 9.6.0 as outlined here.
Next, navigate to Phone Number | Manage Numbers, click on a phone number and Configure tab, Messaging section configure “A message comes in” property to use your function.
Done. If configuration is correct the message sent to Twilio number should appear in TeamDesk almost instantly. Otherwise check function’s logs – in case of TeamDesk REST API error, you should see more or less extensive description of what went wrong prefixed with “TD>ERROR”.
For your convenience we’ve built a sample database based on the principles described in the article, plus phone number format validation, extended error diagnostics and chat-like views.
Feel free to explore!
