SMS with Zendesk and Twilio

SMS Support with Zendesk and Twilio

In Tech by Justin Hamilton2 Comments

SMS with Zendesk and Twilio

SMS can be a very effective channel for quickly replying to customer inquiries (especially when the response is short and simple). The goal of this project was to enable CoachUp’s Customer Experience team to take advantage of SMS support in an organized and scalable way.

There are a handful of out-of-the-box options for providing SMS support through Zendesk (for example); however, we decided to build a custom solution for a couple reasons:

  1. Owning the technology is hugely valuable – building our own apps gives us the ability to customize the behavior, which we’ll likely iterate on in the future.
  2. We’d prefer to use Twilio for all SMS solutions – see below for more on why we use Twilio for all SMS communication (including our repliable SMS).

Using Twilio to provide SMS support through Zendesk isn’t an original concept. This Twilio blog post from 2011 provides a fairly well-documented approach, and Tamer Zoubi wrote a followup blog post in 2014.

However, we didn’t build off these examples; we outlined our own ideal experience and went at it from scratch. Here are a couple reasons why:

  1. On the Zendesk side, these examples lack perhaps the most crucial component: an option for agents to choose whether they’re sending a response via email or SMS.
  2. Both examples use PHP. We want to stick with Ruby on Rails so that we can leave the door open to interact with our primary application if the need arises.

Zendesk Setup

Let’s start by addressing item #1 (above). To elaborate on this requirement, not only do we want agents to choose between SMS or email for a response (sometimes alternating back and forth within the same ticket), we also want this option to only be available if a correctly formatted phone number is present for the requester. After all, we don’t want to risk sending an SMS that doesn’t reach the requester (our support team wouldn’t even know about the delivery failure).

Custom Ticket Field: “Send as Text Message”

  • In Zendesk, go to Manage > Ticket Fields and click “add custom field.”
  • Select “Checkbox” as the type, and set a descriptive title (such as “Send as Text Message”).
  • Make sure the field is NOT set to “Required.”
  • Set a tag to add when the field is checked (useful for metrics on feature usage).
  • When this field is checked and the ticket status is updated (to “Pending” or “Solved”), the public comment will send as an SMS based on the new external target and trigger (see below).

Sidebar Apps:

Note: Zendesk provides some helpful introductory resources for developing apps…

Resource 1

Resource 2

Resource 3

  • Add Phone: Update Ticket
    • Loads if the agent is viewing an existing ticket.
    • Checks if the requester’s phone number exists for the user immediately upon loading the ticket (since the ticket exists, the requester is known).
  • Add Phone: New Ticket
    • Loads when an agent creates a new ticket.
    • New tickets will not have a requester present to check against until the agent inputs the requester — thus, this app checks the requester’s phone number upon the agent adding the requester.

Both apps allow you to submit a phone number (valid format required), which updates the phone number for the requester in Zendesk (and enables as ‘direct line’). The apps essentially transform our “Send as Text Message” field into a conditional field, hiding it so long as a valid phone number is not associated with the requester.

  • Sidebar apps setup on Zendesk (below)
Zendesk sidebar apps

External (HTTP) Target (send ticket comment to Twilio)

  1. In Zendesk, go to Settings > Extensions > Targets and click “add target.”
  2. Select “URL target.”
  3. Name your target (something descriptive, like “Twilio SMS”).
  4. Set “URL” to:{{}}&From=+18888888888
    • Replace ‘XXXXXX’ with your Twilio Account SID.
    • Replace ‘8888888888’ with the phone number you’ve set up in Twilio.
  5. Method: POST
  6. Attribute Name: Body
  7. Basic Authentication: Enter your Twilio Account SID and Auth Token in the Username and Password fields
  8. Save it!

New Trigger (references Custom Ticket Field)

Your final step in Zendesk is to set up a separate trigger that pushes your outbound text message to your Twilio target based on the custom ticket field you’ve set up.

  1. Clone your existing trigger for notifying the requester (default = “Notify requester of comment update”).
  2. Edit your cloned trigger and title it appropriately (“Notify requester via Text Message if Custom Field checked”).
  3. Add a condition to “Meet all of the following conditions”:
    • Ticket: [Your custom field title] == “Checked”
  4. Set “Perform these actions” to:
    • Notify Target == [Your target name]
    • Message: {{ticket.latest_public_comment}}  (NOTE: Don’t use {{ticket.comments_formatted}})
  5. Save your new trigger!

Twilio Setup

Tiffany Huang (who also built our phone call automation via Twilio) created several Ruby files to handle inbound SMS responses:

  • ZendeskUserRetriever: Looks up the user based on the “from” phone number.
  • ZendeskTicketRetriever: Identifies which ticket to post comment to based on the user lookup.
  • ZendeskTextToCommentGenerator: Handles SMS response body and prepends “Text message response:”.

These files are ultimately responsible for user identification (for proper ticket routing), parsing the SMS body to a comment and posting the comment to the correct ticket (or creating a new ticket, when applicable). The final app, which is linked to in the Twilio phone number setup, references those files and does the following for each inbound SMS:

  • Creates a new ticket comment if there is a ticket for the user which is not ‘Closed’.
  • Creates a new ticket if the user is found based on their phone number, yet there are no tickets for the user which are not ‘Closed’.
  • Does not create a ticket if there are no user in Zendesk with the given phone number.

Final Step: Twilio Phone Number Setup

Follow Twilio’s nice tutorial to make sure your phone number is assigned to your new SMS application.

Also, you may want to create a separate app to handle voice calls to that number (if a user gets an SMS and calls the number back). You can link to that app through the same steps as above, except input the URL in the “Voice Request URL” field. Our app is a simple redirect to our support line.

Hope this comes in handy – comments always welcome!