When your company decides to launch a new support channel — usually for efficiency and customer convenience — setting it up is only half the battle. The other half is driving customers toward the new channel (and away from your old ones). Without a concerted effort for customer adoption, you risk paying for a support channel that nobody uses.

Berkey Filters, a world leader in water purification and seller of water filter systems, wanted to add SMS as a support channel for their shoppers. SMS is more convenient for on-the-go shoppers and allows agents to provide service to multiple shoppers more efficiently than other channels.

Berkey Filters launched SMS with Klaviyo, and wanted wanted to add the Klaviyo SMS integration to Gorgias to unify customer conversations in one platform.

The launch was one of the most successful we’ve seen to date, both in terms of ticket efficiency and customer adoption. Within a month of launching SMS, Berkey Filters: 

• Achieved a 2-minute average first-response time for SMS
• Achieved a 20-minute average handle time for SMS
• Converted 2% of tickets to SMS from more time-consuming channels
• Decreased time-consuming phone tickets by 23%
• Decreased time-consuming email tickets by 21%

We sat down with Jessica, the Gorgias account owner and Customer Experience Analyst for Berkey Filters, to ask how Berkey Filters achieved such suburb support stats so quickly. Jessica was generously willing to share her strategies to drive customer adoption of the new support channel. 

In this Playbook, learn about the six tactics Berkey Filters used to launch SMS, increase the number of customers using this channel, and decrease ticket volume on older channels. 

Why add SMS to your helpdesk in the first place?  

SMS is one of the fastest-growing support channels today. It’s one of five channels consumers expect from brands, alongside email, website, voice, and chat. 

Consumers love SMS because it’s fast, convenient, and always with them (even on the go). They don’t need to block off time in their day to sit by their laptop or on the phone to deal with a support situation. They can carry about their day and effortlessly reply to texts whenever they have a moment – something most people already do. 

Support managers love direct messaging channels because conversations are typically shorter and resolved faster. And as long as SMS tickets are managed in the same places as other channels, it’s easy for agents to manage. 

Jessica was specifically interested in using the SMS channel in Gorgias for Berkey Filters to achieve the following goals:

1. Decrease the number of phone calls they received (because agents can only talk to one person at a time) 
2. Decrease the number of times a customer reaches out across multiple channels for the same issue (because faster response times on SMS would make it less likely for duplicate tickets to come in) 
3. Let customers using mobile — which accounts for half of their website visits — contact customer service on the device they’re already using
4. Easily send photos back and forth with customers (especially because they frequently get questions about how to fix or store their products) 
5. Offer a channel that doesn’t require a stable WiFi connection (because they have customers all over the country, including in rural areas that don’t always have reliable service) 

Jessica’s team also views SMS as a modern support channel. More and more brands want to offer a customer service experience that’s seamlessly integrated into the shopper’s day, and Berkey wanted to be an early adopter. 

While some of these benefits are pretty applicable to any store, make sure you’re clear on your “why” before adding a new support channels. This will help you know how to prioritize it compared to other channels and justify the work that goes into adding a new method of communication with your customers. 

How to add Gorgias SMS to your helpdesk

For the purposes of this playbook, we’ll assume you’ve already created your Gorgias helpdesk. If you haven’t, get started with a free trial or schedule a call with our team for a personalized demo. 

Gorgias SMS allows you to send and receive 1:1 SMS and MMS messages with your customers. To add it, go to Settings > Integrations > SMS. 

You’ll need a Gorgias phone number to get started. If you have one already (likely because you use Gorgias voice support), you can add the SMS integration without changing numbers. If you do not have a number yet, it’ll prompt you to create one first. 

If you already have a phone number but it isn’t owned by Gorgias, you’ll need to port it. Learn how in this help doc. 

If you’ve just added SMS (or any new channel), there are a few administrative tasks we recommend before following the steps outlined this playbook: 

• Create a dedicated view for SMS tickets
• Set up routing Rules for SMS tickets
• Create SMS-specific Macros (SMS messages should probably be shorter than some of your other channels, for example) 
• Review existing Rules to add or exclude SMS as a channel trigger

Now, we’ll share exactly how Jessica promoted SMS for Berkey Filters customers. 

{{lead-magnet-1}}

6 steps to drive customer adoption of your new SMS channel (inspired by Berkey Filters)

Jessica knew they would eventually add their SMS number directly on the Berkey Filters website, but she also knew she’d have to wait for her developer to do so. In the meantime, she started with the tools available to her in Gorgias. 

Here are six tactics Jessica used to drive adoption of the newly launched support channel: 

1. Launch a Gorgias Chat Campaign on the Berkey Filters “Contact us” page
2. Customize the auto-reply that was sent to new email tickets
3. Add the SMS number directly on the “Contact us” page
4. Promote SMS in the top banner of the website
5. Leverage their 2 min. first response time (FRT) for SMS in messaging
6. Maintain that FRT with an SLA view in Gorgias

Let’s break each of these down. 

1) Launch a Gorgias Chat Campaign on the Berkey Filters “Contact us” page

Even though Jessica would need to wait for her developer to update the actual page content, she knew she could launch a Gorgias Chat Campaign on the “Contact us” page to announce they now offer support via SMS. (If you don’t know, a Chat Campaign is a live chat session that automatically and proactively triggers for targeted website visitors, often to announce special promotions.) 

Here’s what their campaign looked like: 

Jessica’s campaign automatically opens a live chat box announcing the launch of SMS for anyone who stays on the Berkey Filters contact page for longer than 30 seconds. That time frame is a good way to target anyone who’s clearly trying to identify the best contact method, and not someone who accidentally clicked onto the page (and would likely bounce before 30 seconds). 

To create a Chat Campaign in Gorgias, go to Settings > Integrations > Chat and select the chat widget you want to use. Click the “Create Campaign” button in the top right. 

From here, you can enter the URL(s) the campaign should appear on, set a required time spent on the page, and customize the message that displays. 

Read this help doc to learn more about chat campaigns. 

2) Customize the auto-reply on new email tickets

One of the best ways to tell customers about a new support channel is to promote it on one of your existing channels — especially to customers who are already accustomed to those existing channels and may never visit the contact page again. 

For the segment of customers who already use email to contact support, Jessica leveraged the initial auto-reply that Berkey Filters sends when a customer emails them to announce the new, faster channel. 

In addition to the standard, “Thanks for contacting us! An agent will reply back shortly,” Jessica added, “We are currently experiencing high contact volumes and will be responding as quickly as possible. Our chat and text response times are typically faster. We are now accepting text messages at 1-800-350-4170.” 

By customizing the auto-reply to promote the new channel, Jessica met Berkey Filters’ customers where they were to make sure they knew about the latest and greatest way to get support. 

3) Add the SMS number directly on the “Contact us” page

At this point, Jessica got developer support to add the support phone number to the website. The contact page is a natural location to add any new support channels, because you know new customers will go there looking for contact information. 

Here’s what the Berkey Filters “Contact us” page looks like: 

When building this page, Jessica made many intentional decisions to funnel visitors toward the new channel. Specifically, she:

• Featured SMS next to another efficient (and therefore preferred) channel
• Put the phone number in the headline so it’s easy to see
• Added “Text Us” and a chat bubble visuals to clarify the number is for texting, not calls
• Pointed out that texting is great for “Conversation On The Go,” reminding people to use the channel if they plan to step away from the computer
• Set expectations by listing each channel’s average response time (ART) 

The lesson? When releasing a new support channel, don’t be afraid to give extra context around it to help your shoppers understand when they should use one over the other. 

4. Promote SMS in the top banner across the website

The banner at the top of the website is a high-visibility location that’s especially great for getting in front of returning customers (since they may not need to visit your contact page anymore). 

Brands usually use the top banner for promotions or sales, but Berkey Filters uses it for a mix of sales and support to cater to the entire customer experience. If you refresh their website a few times, you’ll see it rotate through three messages: 

1. Free shipping on orders over a certain amount
2. Chat now for an immediate response
3. Text us for support on the go

5. Promote first response time (FRT) for SMS in messaging

You might’ve picked up on this already, but Jessica was doing something really strategic with her messaging about SMS: She was promoting their first response time of 2 minutes.  

That’s fast! And therefore, a pretty compelling reason for shoppers to use it over other, slower channels like email or voice. 

Now, obviously this only works if your team is achieving a fast response time like that and willing to maintain it. (More on that in the next point.) 

What’s important is that Gorgias gives you insights into your support team’s performance. While that’s useful for internal planning (staffing, budgeting, etc.), we also highly recommend leveraging these data points with your own customers to show the value of the support you provide. 

Support stats that are great to leverage when promoting support via SMS: 

• Global first response time
• SMS first response time
• Global resolution time
• SMS resolution time
• Global CSAT score
• Total or percentage of tickets your brand has answered via SMS (if you’re still trying to increase adoption post-launch)

We don’t currently include SMS CSAT score in Gorgias reporting. If you’d like to measure and promote your SMS CSAT score, share that product feedback here!

6. Maintain that FRT with an SLA view in Gorgias

To help her team keep those impressive first response and resolution times, Jessica knew she needed to improve (and not just measure) those times. She set up a service-level agreement (SLA) view in Gorgias that shows SMS tickets that are open and were created more than one minute ago. 

Here’s what that looks like: 

This view sits at the top of their sidebar along with a few other SLA-based channel views, so agents can quickly prioritize what tickets they should solve next. 

In addition to the view, Jessica created an Auto-Reply Rule that sends the first message to an SMS ticket. 

This message thanks the customer for texting support, and states the business hours for Berkey Filters. We love how this helps set expectations right from the start, especially for customers who might text in outside of these hours. (So they don’t text again waiting for a reply!) 

Here’s what that Rule looks like: 

Last but not least, it’s worth mentioning that Jessica was also incredibly intentional about rolling all of this out to the Berkey Filters agents. Specifically, she involved them in the decision to launch the new channel, trained them on the new system, and made sure they were prepared before launch. 

None of this would be possible if agents were unsure how to handle incoming SMS tickets or use the SLA view.

{{lead-magnet-2}}

Berkey Filters’ results from adding support via SMS

We’ve already teased some of the impact that Berkey Filters has seen since adding SMS support, but how does it all add up? 

In their first 30 days using Gorgias SMS, Berkey Filters: 

• Closed over 250 SMS tickets
• Sent almost 1400 messages via SMS
• Achieved a 2-minute first response time
• Achieved 20-minute resolution time
• Converted 2% of all tickets to SMS
• Decreased phone calls by 23%
• Decreased emails by 21%

That’s remarkable! And while those stats certainly speak to the high quality of their support team, they first needed to make customers aware and excited about the new channel.  If you decide to launch a new support channel, we recommend following Berkey’s lead and creating an intentional adoption campaign to accompany the launch. 

Get your customers excited about texting your brand

Prioritizing SMS shifts customer service conversations to a “live” channel where agents can help multiple customers at once, giving everyone a better experience. 

And even if you’re strained for resources (like waiting for your developer to be able to update your store’s site) you can follow Berkey Filters’ lead and use other features and channels in Gorgias to start promoting your new channel.

Gorgias also integrates with SMS marketing platforms like Klaviyo to make texting a seamless part of your customer journey (and easy for agents to manage).

Specifically, if customers reply to an SMS sent with Klaviyo, Gorgias will create a ticket so your agents can respond right away. Plus, Klaviyo and Gorgias share customer data in real time, so you have as much information about your customers as possible in both tools:

“Having the Gorgias + Klaviyo integration has helped provide a service to our customers that we did not have before. Our customer service department is now able to provide a near-instant response via text message without having to exit Gorgias. This feature has made the entire process of getting to these tickets so effortless and much more efficient.”

— Jessica Robles, Customer Experience Analyst at Berkey Filters

To get started with Gorgias SMS, log into your helpdesk or click here to sign up for free.

Every month, our product team holds a casual, conversational event with our customers to demo new features, receive real-time feedback, and host live Q&As. 

Watch the video below or read on for a recap of our latest product updates. 

1. Admins can require Two-Factor Authentication for all users (3:18) 

While Gorgias does a lot to keep your data secure, one of the best ways to add an extra layer of security is to encourage agents to use secure passwords and two-factor authentication (2FA). 

And with our latest update, you can do more than just encourage. Admins can now require agents to set up two-factor authentication. 

1. Admins can require Two-Factor Authentication for all users (3:18) 

‍

Once an admin toggles the option, all users in your account will have 14 days to set up 2FA. After 14 days, users will need to set it up to access your helpdesk. 

2. Add a contact form in Gorgias Chat for a better CX outside business hours (11:38) 

It can be hard to follow up with chat tickets that were left during off-business hours. Sometimes customers don’t include enough details in their message, making it harder to follow up on the next day. 

Using a contact form in Gorgias Chat, you can capture a customer's email and message in a short conversational way. The contact form is designed to collect more information without disrupting the conversational experience, so you can easily follow up and help via email when you log back into Gorgias. 

The contact form prompts your web visitors to select a subject (to help you triage tickets faster), and then provide more details about their issue so your agents know what they’re trying to solve. Last, it collects the shopper’s email address so you know who to follow-up with and where to reach them. All of this information will be collected in a single ticket in your helpdesk. 

Read this help center article to learn how to enable the contact form in your Gorgias chat. 

3. Create sub-categories in Help Center (19:55) 

Create multiple levels of categories to help your shoppers navigate to improve help center organization and find help content for related issues more easily. 

These new categories also give your team more options when creating a Help Center, so you can organize FAQs in whatever way makes sense for your brand. 

4. New Managed Rules (For Automation Add-on Subscribers) (21:30) 

Rules are a powerful feature that let Gorgias users automatically organize, tag, and reply to tickets. Thousands of Gorgias customers have adopted rules in their customer support workflow to save time and allow themselves to provide faster and higher quality service. Focusing on the common inquiries like WISMO, we’ve built Managed Rules to optimize time for Automate subscribers. 

Managed Rules are pre-built automations developed by the Gorgias team and include some of the most common and helpful automations. They need no code, no setup. Install them from the Rule Library and you’re good to go! If we improve the Rule, it will automatically update in your helpdesk, no action from you required.

Customer Q&A (24:44) 

Tune into the above timestamp if you want the full 25 minutes of customer questions and answers from our product team. Here were a few of the highlights!

With only two weeks left in Q2, which of the planned releases on the public roadmap will actually launch? (25:44)

Some features listed in Q2 of our public roadmap will indeed be released in Q2, while others will spill into Q3 (or later). We’re proud to provide transparency with our public roadmap, but please understand that it’s subject to change throughout the quarter. We do our best to update our roadmap frequently but can’t always do so right away.

Although we can’t promise to release any of these features in Q2, a few features we plan to release sooner than later include:

• FAQ article recommendations in chat
• Create a Chat report in help desk statistics
• Display agents phone availability state

Our team is actively prioritizing the roadmap for Q3 right now. Check back soon to see the latest plan! 

Will you be improving the returns and cancellations workflow for the Help center? We use Loop, but can’t integrate our self-service return portal with our new Help Center. (33:40)

This is a limitation we’re definitely aware of, and are exploring options. The long-term solution is to build better integrations with Loop and other top returns platforms. If this is a feature you’d like to see, please submit the request here. 

When will the option to convert phone calls to SMS be available? (45:15)

We’re hoping to release more features around that at the start of 2023. Today if you receive a phone call, you can always reply to that ticket via SMS. In the future, we’ll focus on helping you deflect the phone call entirely and prioritize SMS instead. 

Join us for the next monthly product event

Thanks for checking out the recap of our June customer product event. We hold these events once as a month as a way to share the latest releases and connect with our customers in real-time. It’s a favorite – from both customers, and the Gorgias team. 

If you’d like to sign up for the next one to attend live, you can register here. We’d love to have you join us! 

‍

There are now over 85 incredible integrations in the Gorgias App Store with the tools that power your ecommerce store. While each app is unique, together these integrations can help your agents work more efficiently to provide excellent service to your customers. 

Take a look at the newest additions so far from 2022. 

In the first half of the year, we’ve launched 15 new integrations for your Gorgias helpdesk: 

1. Klaviyo (updated!)
2. Gorgias SMS
3. Thankful AI
4. Netsuite
5. Okendo
6. Narvar
7. Skio
8. Via Software
9. Clyde
10. Smartrr
11. ShipMonk
12. Annex Cloud
13. Daton
14. Shogun Frontend
15. Gobot
16. Shop2app

Read on to learn how you can use these tools to help manage your store, and visit the Gorgias App Store to activate them today!

Klaviyo (updated early 2022)

Klaviyo is an email and SMS marketing automation platform built for ecommerce. Gorgias was the first helpdesk to connect to Klaviyo SMS, allowing your brand to create seamless conversations between your marketing campaigns, shoppers, and support team.

With the updated Klaviyo integration, you can: 

• Automatically create tickets in Gorgias from replies to Klaviyo SMS campaigns
• Reply to Klaviyo SMS messages in the same place as every other customer conversation, with all the context of your ecommerce integrations
• Create contact lists in Klaviyo based on support events in Gorgias

This integration helps you streamline customer interactions and create higher-converting marketing campaigns. To learn more, go to the Gorgias App Store. 

Gorgias SMS

We recently released Gorgias SMS, an easy way for your brand to offer this convenient and conversational communication channel. It’s one of the fastest-growing support channels for ecommerce brands, and one of the most reliable for customers to contact you on (since it’s not dependent on internet access). 

With Gorgias SMS, you can: 

• Talk to customers on their (since they likely always have their phone on them) 
• View order information in the same window as SMS tickets
• Easily send photos back and forth with customers

Click here to learn more about Gorgias SMS, available with all plans. 

Thankful AI

Thankful AI is a platform dedicated to helping you deliver better support for the post-purchase needs of your customers. The AI is tailored specifically for retail and ecommerce businesses, so you don’t have to worry about a disjointed experience. 

With this integration, the Thankful AI agent can: 

• Triage and route tickets to real agents
• Tag tickets in Gorgias 
• Respond to tickets across all written channels

This frees up your agents to focus on more meaningful conversations with customers. Visit the Gorgias App Store to learn more about the Thankful integration. 

NetSuite

NetSuite is a cloud ERP including financials, CRM, and ecommerce. It helps brand work more efficiently, take control of inventory and fulfillment, and bring all your tools together in a unified business management suite. ​​

Sync NetSuite data into Gorgias to give your agents important customer & order information in a single tab. 

With this integration, you can: 

• Add over 60 NetSuite fields to a widget in the Gorgias Customer Sidebar.
• Sync customer information from NetSuite into Gorgias.
• Sync order information & shipping details from NetSuite into Gorgias.
• Sync RMA information from NetSuite into Gorgias.
• View the last 10 orders that have been created or modified.

This helps your agents have all the context they need next to every conversation they have. Visit the Gorgias App Store to learn more. 

Okendo

Okendo is a customer marketing platform and an Official Google Reviews partner that helps brands capture and showcase high-impact social proof such as product ratings & reviews, customer photos & videos, and Q&A messageboards.

With this integration, you can: 

• Automatically create tickets in Gorgias for Okendo product reviews
• Easily respond to every customer who leaves a review
• Add an Okendo widget to the Gorgias Customer Sidebar for customer loyalty insights next to every ticket

Visit the Gorgias App Store to learn more about our Okendo integration. 

Narvar

Link Narvar Return & Exchanges for Shopify with Gorgias to automate returns management and get rich insights that help you save costs and improve operations.

With this integration, you can: 

• ‍Create flexible return policies. Deploy tailored returns flows, policies, and fees for different products or customer segments to offer a differentiated experience.‍
• Retain revenue with recommended exchanges. Convert up to 45% of refunds to exchanges by recommending exchanges of same or different value to customers right within the returns flow.‍
• Bring customers back by incentivizing store credit. Add a credit bonus to store credit refunds based on specific exchange rules that will incentivize customers to keep shopping in your store.

To learn more about our Narvar integration, visit the Gorgias App Store. 

Skio

Skio helps brands on Shopify sell subscriptions. With this integration, you can add a Skio widget to your Customer Sidebar in Gorgias. This gives your agents insights into customer subscriptions right in the helpdesk without having to switch tabs. 

With this integration, you can: 

• View Skio customer information in the Gorgias Customer Sidebar
• Quickly click out to Skio right from Gorgias if needed
• Respond to subscription questions from one central location 

To learn more about our Skio integration, visit the Gorgias App Store. 

Via Software

Via is a mobile commerce (SMS marketing) platform for ecommerce businesses. Send personalized messages to your customers for increased revenue and customer satisfaction. 

With this integration, you can: 

• Automatically create tickets in Gorgias based on customer replies to Via SMS
• Respond to Via SMS messages directly from the Gorgias helpdesk
• View the entire conversation, including replies from Gorgias, in the Via platform

Visit the Gorgias App Store to learn more. 

Clyde

With Clyde and Gorgias working together, you can create a seamless and positive support experience by syncing all warranty data inside your Gorgias account. Stay focused and close tickets faster by viewing Clyde contracts and claims information in the same window you use to talk to customers.

With this integration, you can: 

• See the full picture of every customer
• Find open warranty claims in a flash
• Turn your support center into a profit center

Manage warranty requests & find claims information in one tool. Head to the Gorgias App Store to learn more. 

Smartrr

Smartrr is a seamless, full-service subscription solution. Paired with Gorgias, you can equip your team with the best customer service tools in one convenient location to increase customer satisfaction and drive customer loyalty. 

With this integration, you can: 

• Sync subscription data from Smartrr in Gorgias
• Help agents stay focused in a single tab 
• Provide better, faster support for subscription questions

To learn more about our Smartrr integration, go to the Gorgias App Store. 

ShipMonk 

ShipMonk is an order fulfillment platform for eCommerce businesses ready to scale.  They offer technology-driven fulfillment solutions that enable business founders to devote more time to the things that matter most in their businesses.

With this integration you'll be able to:

• Pull order fulfillment data and tracking information from ShipMonk to Gorgias
• Access specific orders in ShipMonk directly from the Customer Sidebar in Gorgias

Learm more about the ShipMonk integration in the Gorgias App Store. 

Annex Cloud

Annex Cloud is a cloud-based customer loyalty platform for enterprises. They provide integrated loyalty, engagement, and retention solutions across a range of program types like paid memberships, incentives, and more. 

With this integration, you can: 

• Sync customer’s loyalty data across tools
• Show loyalty information of a customer when opening a new or existing ticket

Click here to learn more about our Annex Cloud integration. 

Daton

Daton can replicate Gorgias data to your data warehouse in minutes, freeing up your analysts to focus on generating important business insights instead of extracting data.  

With this integration, you can sync information from Gorgias to your data warehouse like:

• Customers
• Jobs
• Users
• Tickets

To learn more about Daton, visit the listing in the Gorgias App Store. 

Shogun Frontend

Shogun is a headless ecommerce platform built for merchants. Convert more with richer merchandising and sub-second store speed. The Gorgias integration allows merchants to add chat capabilities to their Shogun-powered shops. 

With Gorgias chat on your Shogun Frontend, you can: 

• Promote your products and provide order details, all connected to your ecommerce platform
• Create chat campaigns to proactively message customers while they’re shopping live on your site
• Have agents answer live chats or create customizable, automated flows to free up agents for the most important conversations

Click here to learn more about our integration with Shogun Frontend.

Gobot

Gobot helps fast-growing Shopify stores convert more shoppers and reduce support burden with beautiful guided selling quizzes and AI-powered support chatbots.

With this integration, you can: 

• Sync recommendation data from Gobot into Gorgias so reps can respond and address questions via chat or email. 
• Collect post-purchase survey data and automatically connect select customers with questions/feedback to support reps in Gorgias.
• Automate repetitive customer support inquiries with Gobot’s AI Support Automation and seamlessly transition to Gorgias live chat or email support for those who require human assistance.

Visit the Gobot listing in the Gorgias App Store to learn more. 

Shop2app

Shop2app is a mobile app builder. It’s designed for local delivery, national delivery, and in-store pickup, and also makes it easy to manage subscriptions and send push notifications to customers. 

With this integration, you can: 

• Automatically create tickets in Gorgias when customers contact a merchant from their mobile app.
• Allow customers to initiate a support ticket directly from past orders within the mobile app.

Visit the Shop2app listing in the Gorgias App Store to learn more. 

Supercharge Gorgias, your CX command center

The Gorgias App Store features 85+ high-quality integrations with other leading ecommerce tools. By connecting the apps that power your store, you can give your agents the context they need to provide remarkable customer service from a single workspace. (No more switching tabs!) 

To add any of these apps to your helpdesk, go to Settings > Integrations or visit the Gorgias App Store. 

Each month, our product team holds a casual, conversational event with our customers to demo new features, receive real-time feedback, and answer live Q&As. 

Watch the video recap here, or read on for a recap of the latest releases. 

1. SMS is officially live for all accounts (3:10) 

With this new channel, you can receive and respond to SMS and MMS messages within Gorgias. This makes it easy for your customers to communicate with your store while they’re on the go, and easy for your agents to provide fast, conversational support. 

We’re releasing SMS this quarter as a free trial for every customer on every plan. Conversations will count toward your plan’s ticket count, but there are no additional charges for minutes, usage, phone numbers, etc. In the coming months, we’ll be assessing the best way to provide Voice and SMS so we can continue to innovate and build powerful new features for these channels.

2. SMS Pro-tip: Create a Gorgias Rule to set up a double opt-in (11:55) 

If you want customers to consent to receive SMS messages before your agents actually reply, you can do this with a simple Rule in Gorgias. Here’s what it would look like: 

Read this article for four more Gorgias Rules to help automate SMS. 

3. Agents will now receive browser notifications when a ticket is assigned to them (14:55) 

This is especially great for anyone who gets tickets assigned to them, but may not be looking at Gorgias throughout their entire workday. (Think managers, social media collaborators, etc.) 

To see these notifications, you may need to adjust your browser and/or computer settings. You can see an example for Chrome + Mac in our official Product Update. 

4. Quick response flows in self-service got a revamp  (21:48) 

Quick response flows bring in a critical component to self-service, creating more ways to engage with shoppers who visit your store online. We designed quick response flows with the guidance that 60% of the time, customers use chat to ask pre-purchase questions. Most successful merchants leverage their FAQ content to prompt conversation with quick response flows that result in generating revenue, trust and loyalty.

If you haven’t yet activated quick response flows, you’re in for a treat. With this revamp, you can now easily manipulate every step of the experience for quick response flows from self-service settings. Immediately under the Quick Response Flows tab, you can write in any question and answer you prefer and hit save. There is no other place or screen you’d need to navigate. Using the preview on the right, you can reassure the quality of the experience you want to create for your customers. 

If customers click on a quick response flow and find the information they need, this will not count towards your monthly ticket volume. 

If they click on a quick response flow  and select “No, I need more help” option, it will create a ticket for an agent to address. 

Best practices

It’s amazing when our merchants start using a feature and take it to the next level. We’ve seen some of the best practices to include creating unique tags for each quick response flow created (e.g. Quick_Response_Flow_1), then adding a corresponding view in Tickets. This way, you can track closely the conversations prompted by quick response flows and dedicate a select group of agents who are trained to expand on the subject and help your customers become fans. For more on this subject, check out Quick Response Flows help doc here. 

Customer Q&A (26:50) 

Tune into that timestamp if you want the full 25 minutes of customer-led questions and answers from our product team. Here were a few of the highlights!

Gorgias Phone vs Aircall: What are the differences? What’s the timeline for improvement for Gorgias Voice? (32:40) 

Gorgias phone is an easy way to add a basic phone line to your store. If you’re looking for advanced, full call center features, our partners like Aircall or RingCentral may be a better solution for you. 

For example, their phone-specific statistics are more in-depth than ours, but the ability to create a phone number and answer it in the Gorgias helpdesk is naturally easier with Gorgias. 

Our long-term vision for Gorgias Phone is not to fully compete with apps like Aircall, but rather to invest in ecommerce-specific solutions so you can provide the best voice support to your shoppers. 

What’s up with WhatsApp? (37:50)

It’s our next new channel, coming Q3! We have access to the API and are ready to start building at the end of the quarter. (Just need to polish up a few existing channel bugs first.) 

Any plans to integrate with Shopify Blogs? (43:15) 

Not yet, but we’d love to hear more feedback about this if it’s something you’re interested in! Submit this idea on our Product Roadmap to help us prioritize it. 

Join us for the next monthly product event

That completes our recap of our May customer product event. We hold these events once as a month as a way to review the latest releases and connect with our customers in real-time. It’s a favorite – from both customers, and the Gorgias team. 

If you’d like to sign up for the next one to attend live, you can register here. We’d love to have you join us! 

Wondering if your team should add voice support to your ecommerce channels this year? You’re not alone. ‍

Over 15% of our customers currently have a phone integration added to their account, thanks to the Gorgias Voice integration and partners like Aircall and RingCentral. ‍

While voice support may feel like an “outdated” channel in the age of live chat and social media, this tells us that ecommerce support teams are increasingly finding value in offering it to their clients. ‍

Here are 4 benefits of adding voice support to your ecommerce store: 

• You can achieve faster first response times and faster resolution times. 
• It’s easier to express empathy with customers.
• Having a phone number builds trust and brand quality. 
• It makes your support more accessible. 

You can achieve faster first response times and faster resolution times. 

Phones are an immediate communication channel, so it’s not surprising that adding voice support can boost your first response time. What we weren’t expecting, however, was by how much: ‍

Our customers with phones have a first response time that’s 7x faster than merchants that don’t offer voice support. (30 minutes compared to 4 hours.) ‍

What’s even more important to note, however, is that adding voice support doesn’t decrease resolution time (like many support managers fear). In fact, it makes quite a positive impact: ‍

Our merchants using phones have an average resolution time that’s 34% faster than customers who don’t. 

So not only does this channel help you respond to customers faster, but it helps you resolve their issues faster. That means your team can work more efficiently and spend up to 66% less time resolving each ticket. (Imagine how that could help increase your store’s revenue!) 

It’s easier to express empathy with customers (which can lead to better Satisfaction scores).

Talking (literally) to shoppers and hearing their tone of voice is the best way your agents can adjust their responses to create a great customer experience. 

While you can do your best to read clues in email and chat, it’s always going to be easier to match the customer’s tone when actually listening to them on the phone. 

And when your agents can express empathy and solve the problem accordingly, you’ve got a better chance at getting that 5-star review and positive customer feedback. ‍

Our customers using phones have an average Satisfaction score of 4.56 out of 5. ‍

While that score also depends a lot on your support agents and their personal approach to customer service, there’s no denying that actually speaking to clients is helpful for both parties in those moments.

Having a phone number builds trust and brand quality. 

Especially if you sell high-end products or have VIP customers (like wholesalers buying in bulk), having a phone number adds a level of legitimacy to your business. 

Since most online stores don’t immediately add phones as a support channel, it will stand out to customers when your shop does offer voice support. 

Phones add a sense of maturity to your business (and especially if you’re using an integrated solution like Gorgias Voice), there’s not much cost involved to elevate the status of your store like this. 

It makes your support more accessible. 

While the internet has come a long way over the years in terms of accessibility, the truth remains that phone support may be an easier and more comfortable contact method for some of your customers than digital channels. 

Test your live chat experience with a screen reader, for example. What’s the experience like? (And how does it compare to dialing a phone number and talking verbally to someone?) 

If there’s a chance that voice support is more approachable for a part of your customer demographic, you’ll create a better shopping experience for them by adding a phone line. 

Now that you know the benefits of phone support, how do you actually add it? 

The first thing you’ll need to decide is who on your team will actually be answering the phones. ‍

A few options to explore: 

1. Having your existing support agents answer phones. This is best if your agents aren’t already too busy, or you have someone who’s particularly good at verbal communication. 
2. Hiring a new agent(s). This is the situation many support managers find themselves in -- they want to add phones, but don’t feel like they have the right staff yet to manage it. Hiring someone new can help, but we also recommend following these tips to keep resolution times fast and phone processes efficient. 
3. Outsourcing phone support. If you’re expecting a large amount of call volume and don’t feel you can internally staff the team to support it, outsourcing to a call agency is always an option. This can be expensive upfront, however, so it may be best to try one of the other options and consider this as a last resort. 

Next, you’ll need to choose a phone platform. 

If you’re adding our built-in voice channel to your Gorgias helpdesk, all you have to do to get started is log into your Gorgias helpdesk and create a new number (or forward or port an existing one, if you happen to have one already). 

Our phone integration is included in all Gorgias plans, and unlike other providers, there’s no annual contract fee and no minimum seat requirement. 

This makes it a great option for teams looking to add phones for the first time or who want to manage all communication channels in one place. 

Plus, our ecommerce integrations save your agents time by displaying callers’ shopping history right in the helpdesk, so they don’t have to go searching for the last order, for example. 

For more tips on how to create efficient phone processes and increase resolution time by 34%, check out this article. ‍

Finally, once you’ve set up your team and chosen your provider, all that’s left to do is make your number visible. 

If you’re offering voice support for all your customers, you might place it in the footer of your website or all transactional emails. 

If you’re piloting voice support or using it exclusively for a segment of shoppers, you might save it for smaller email segments or place it only on dedicated landing pages just for them. 

Wherever you decide to put your number, just make sure it's easily accessible and clearly visible so your shoppers can start calling, and your support team can start delivering even better customer experiences!

SMS is a convenient way for customers to contact your brand and receive fast support. It’s no wonder it’s one of the top five channels that consumers expect to engage with brands, alongside email, voice, website, and in-person. 

Every Gorgias plan now includes two-way SMS at no additional cost, making it easy for your brand to start offering this conversational channel.

Why offer SMS support?

There are many reasons to offer customer service messaging, but here are the top four:

It’s fast and conversational

SMS is a conversational, real-time channel. The benefit of this is that customers tend to keep the conversation short and reply quickly to follow-up questions, meaning your agents can resolve the situation quickly, too. 

Customers can contact you while they’re “on the go” 

Most people keep their phone with them everywhere they go. With SMS, it’s easy for customers to start the conversation and follow-up as they move throughout their day, instead of feeling stuck to a chat conversation on their laptop. 

It’s natural for younger customers

Sending text messages feels like you’re texting a friend, even if it’s actually between customers and your brand. Younger clientele will feel natural using this support channel, and it can even help you build that friendly-feeling into your brand perception. 

It makes sending photos back and forth easy

Does your refund or return policy require photo evidence to kick off the process? If your customers ever need to send pictures of damaged items or wrong products, SMS is the perfect channel because they’re probably taking those photos on their phone anyway. 

Still not sure if SMS is a support channel your brand should prioritize? Try it for 2 weeks. Because SMS is included in every Gorgias plan, it’s easy to turn off if you decide it isn’t right. 

Recommended reading: Our list of 60+ fascinating customer service statistics.

How to add SMS to your helpdesk 

You’ll need two things to get started with Gorgias SMS. (Don’t worry, they’re both quick!) 

If you’re new here, get started on the  Gorgias helpdesk. It only takes a few minutes to create an account, and you can always book a call with our sales team if you have questions. 

The second is a Gorgias-owned phone number, meaning you either created it in Gorgias or ported it from your previous phone provider. You can do both of these actions in Settings > Phone Numbers. 

Note: SMS is currently only available for US, UK, and Canadian numbers. 

Once your phone number is ready in Gorgias, you can add the SMS integration to it. You can do this from Settings > Integrations > SMS. 

Once the integration is active, you’re ready to start replying to SMS conversations from your customers. 

To tell your customers they can now text your brand, we recommend adding “Text us,” plus your phone number, in some or all of these places: 

• The footer of your website
• The “Contact Us” page of your website
• Your Gorgias Help Center
• Transactional emails (order confirmation, return initiated, etc.)

4 automation Rules to help you get started 

Below are four top automation rules to take full advantage of SMS customer service. We also have a full guide on customer service messaging that includes templates and macros to upgrade your SMS support.

Auto-tag with “SMS”

SMS is an official channel in Gorgias, meaning you can see SMS-specific stats or create SMS-specific Views out of the box. There may be times when you also want to Tag tickets with “SMS” however, in which case you can do so with a Rule like this: 

Auto-assign to a real-time team

SMS is a fast, conversational channel, so you’ll want to assign these tickets to agents that can keep up with the pace. If you have a dedicated chat team, they’ll be naturals at answering questions via SMS, as well. Here’s a Rule that will automatically assign SMS tickets to a specific team. 

Auto-reply: Message received

When customers text your brand, they’ll expect a fast response. In order to buy your agents some time, we recommend sending an auto-response to let the customer know their message has been received and an agent will be with them shortly. This will also give them confidence that the text message did in fact go through, so they don’t follow-up right away. 

Auto-reply: Order status

Whenever you add a new communication channel for your customers, you should consider how you’ll respond to WISMO (“Where is my order?”) questions on it. With SMS, you’ll want to keep the length of your reply in mind so you’re not sending an insanely long text message back to customers. We recommend creating a Rule that can A) make sure the reply follows the best format for SMS and B) save your agents from having to answer these WISMO questions manually.

Next: Connect your SMS marketing apps for a seamless experience

Gorgias SMS empowers your brand to keep the conversation going on SMS, even when your customers are on the go.

We also integrate with SMS marketing apps, making it easier for agents to answer promotion replies from one workspace. They can work more efficiently while turning SMS questions into opportunities for better customer value. 

In the Gorgias App Store, you’ll find some of the top ecommerce integration partners like Klaviyo, Attentive, Postscript, and more. 

If your brand is using any of these apps to drive sales via SMS, we highly recommend integrating with Gorgias so your team can work more efficiently toward your revenue goals. When SMS marketing and SMS customer service work in tandem, they are far more powerful.

Want to see an example of a brand that successfully launched SMS customer support and effectively drove customers to use the new channel? Check out our playbook of Berkey Filters, an ecommerce merchant that did just that.

Ready to get started with this conversational support channel? Add SMS to your Gorgias helpdesk today or book a call with our team to learn more.

As we all locked down in March 2020 and changed our shopping habits, many brick-and-mortar retailers started their first online storefronts. 

Gorgias has benefitted from the resulting ecommerce growth over the past two years, and we have grown the team to accommodate these trends. From 30 employees at the start of 2020, we are now more than 200 on our journey to delivering better customer service.

Our engineering team contributed to much of this hiring, which created some challenges and growing pains. What worked at the beginning with our team of three did not hold up when the team grew to 20 people. And the systems that scaled the team to 20 needed updates to support a team of 50. To continue to grow, we needed to build something more sustainable.

Continuous deployment — and the changes required to support it — presented a major opportunity for reaching toward the scale we aspired to. In this article I’ll explore how we automated and streamlined our process to make our developers’ lives easier and empower faster iteration.

Scaling our deployment process alongside organizational growth

Throughout the last two years of accelerated growth, we’ve identified a few things that we could do to better support our team expansion. 

Before optimizing the feature release process, here’s how things went for our earlier, smaller team when deploying new additions:

1. Open a pull request (PR) on GitHub, which would run our tests in our continuous integration (CI) system
2. Merge those changes into the main branch, once the changes are approved
3. Automatically deploy the new commit in the staging/testing environment, after tests run and pass on the main branch
4. Deploy these changes in our production environment, assuming all goes well up until this point
5. Post on the dedicated Slack channel to inform the team of the new feature, specifying the project deployed and attaching a screenshot of all commits since the last deployment.
6. Watch dashboards for any changes — as a failsafe to back up the alerts that were already triggering — to check if the change needed to be rolled back.

This wasn’t perfect, but it was an effective solution for a small team. However, the accelerated growth in the engineering team led to a sharp increase in the number of projects and also collaborators on each project. We began to notice several points of friction:

• The process was slow and painful. The continuous integration and continuous deployment (CI/CD) systems are meant to speed the process up, but we still need to perform rigorous testing. We needed to find the sweet spot between speed and rigorous testing and we believed both aspects left room for improvement.
• Developers didn’t always take full ownership of their changes. When a change wasn’t considered critical (which happened fairly often), a developer would often let the next developer with a critical change deploy multiple commits at the same time. When problems occurred, this made it much more difficult to diagnose the bad commit.
• It was a challenge to track version changes. To track the version of a service that was deployed in production, you had to either check our Kubernetes clusters directly or go through the screenshots in our dedicated Slack channel.
• Each project had its own set of scripts to help with deployment. We wanted to streamline our deployment process and add some consistency across all projects.

It was clear that things needed to change.

Adjusting practices and tools to lay the foundation for implementing GitOps

On the Site Reliability Engineering (SRE) team, we are fans of the GitOps approach, where Git is the single source of truth. So when the previously mentioned points of friction became more critical, we felt that all the tooling involved in GitOps practices could help us find practical solutions.

Additionally, these solutions would often rely on tooling we already had in place (like Kubernetes, or Helm for example).

What is GitOps?

GitOps is an operational framework. It takes application-development best practices and applies them to infrastructure automation. 

The main takeaway is that in a GitOps setting, everything from code to infrastructure configuration is versioned in Git. It is then possible to create automation by leveraging the workflows associated with Git. 

What are the benefits of implementation?

One such class of that automation could be “operations by pull requests”. In that case, pull requests and associated events could trigger various operations. 

Here are some examples:

• Opening a pull request could build an application and deploy it to a preview environment
• You could add a commit to said pull request to rebuild the application and update the container image’s version in the preview environment
• By merging the pull request, you could trigger a workflow that would result in the new changes being deployed in a live production environment

Using ArgoCD as a building block

ArgoCD is a continuous deployment tool that relies on GitOps practices. It helps synchronize live environments and services to version-controlled declarative service definitions and configurations, which ArgoCD calls Applications. 

In simpler terms, an Application resource tells ArgoCD to look at a Git repository and to make sure the deployed service’s configuration matches the one stored in Git.

The goal wasn’t to reinvent the wheel when implementing continuous deployment. We instead wanted to approach it in a progressive manner. This would help build developer buy-in, lay the groundwork for a smoother transition, and reduce the risk of breaking deploys. ArgoCD was an excellent step toward those goals, given how flexible it is with customizable Config Management Plugins (CMP).

ArgoCD can track a branch to keep everything up to date with the last commit, but can also make sure a particular revision is used. We decided to use the latter approach as an intermediate step, because we weren’t quite ready to deploy off the HEAD of our repositories. 

The only difference from a pipeline perspective is that it now updates the tracked revision in ArgoCD instead of running our complex deployment scripts. ArgoCD has a Command Line Interface (CLI) that allows us to simply do that. Our deployment jobs only need to run the following command:

The developers’ workflow is left untouched at this point. Now comes the fun part.

Building automation into our process to move faster

Our biggest requirement for continuous deployment was to have some sort of safeguard in case things went wrong. No matter how much we trust our tests, it is always possible that a bug makes its way to our production environments.

Before implementing Argo Rollouts, we still kept an eye on the system to make sure everything was fine during deployment and took quick action when issues were discovered. But up to that point, this process was carried out manually. 

It was time to automate that process, toward the goal of raising our team’s confidence levels when deploying new changes. By providing a safety net, of sorts, we could be sure that things would go according to plan without manually checking it all.

Argo Rollouts can revert changes automatically, when issues arise

Argo Rollouts is a progressive delivery controller. It relies on a Kubernetes controller and set of custom resource definitions (CRD) to provide us with advanced deployment capabilities on top of the ones natively offered by Kubernetes. These include features like:

• Blue/Green, which consists of deploying all the new instances of our application alongside the old version without sending traffic to it at first. We can then run some tests on the new version and flip the switch when we made sure everything was fine. Once no more traffic is sent to the old version, we can tear it down.
• Canary deployments, which allow us to start by only deploying a small number of replicas, using the new version of our software. This way, we’re able to shift a small portion of traffic to the new version. We can do multiple steps here and only shift 1% of the traffic towards the new version at first. Then 10%, 50% or even more depending on what we try to achieve.
• Analyzing new deployments’ performance. Argo Rollouts allows us to automate some checks as we are rolling out a new version of our software. To do that, we describe such checks in an AnalysisTemplate resource, which Argo Rollouts will use to query our metric provider and make sure everything is fine.
• Experiments, which are another resource Argo Rollouts introduces to allow for short-lived experiments such as A/B testing.‍
• Progressive delivery in Kubernetes clusters by managing the entire rollout process and allowing us to describe the desired steps of a rollout. It allows us to set a weight for a canary deployment (the ratio between pods running the new and the old versions), perform an analysis, or even pause a deployment for a given amount of time or until manual validation.

We were especially interested in the canary and canary analysis features. By shifting only a small portion of traffic to the new version of an application, we can limit the blast radius in case anything is wrong. Performing an analysis allows us to automatically, and periodically, check that our service’s new version is behaving as expected before promoting this canary. 

Argo Rollouts is compatible with multiple metric providers including Datadog, which is the tool we use. This allows us to run a Datadog query (or multiple) every few minutes and compare the results with a threshold value we specify. 

We can then configure Argo Rollouts to automatically take action, should the threshold(s) be exceeded too often during the analysis. In those cases, Argo Rollouts scales down the canary and scales the previous stable version of our software back to its initial number of replicas.

Each service has its own metrics to monitor, but for starters we added an error rate check for all of our services.

Creating a deployment conductor to simplify configuration and deployment management

Remember when I mentioned replacing complex, project-specific deployment scripts with a single, simple command? That’s not entirely accurate, and requires some additional nuance for a full understanding.

Not only did we need to deploy software on different kinds of environments (staging and production), but also in multiple Kubernetes clusters per environment. For example, the applications composing the Gorgias core platform are deployed across multiple cloud regions all around the world.

ArgoCD and Argo Rollouts might seem to be magic tools, we actually still need some “glue” to make things stick together. Now because of ArgoCD’s application-based mechanisms, we were able to get rid of custom scripts and use this common tool across all projects. This in-house tool was named deployment conductor.

We even went a step further and implemented this tool in a way that accepts simple YAML configuration files. Such files allow us to declare various environments and clusters in which we want each individual project to be deployed.

When deploying a service to an environment, our tool will then go through all clusters listed for that environment.

For each of these, it will look for dedicated values.yaml files in the service’s chart’s directory. This allows developers to change a service’s configuration based on the environment and cluster in which it’s deployed. Typically, they would want to edit the number of replicas for each service depending on the geographical region.

This makes it much easier for developers than having to manage configuration and maintain deployment scripts.

Enabling continuous deployment

This leads us to the end of our journey’s first leg: our first encounter with continuous deployment.

After we migrated all our Kubernetes Deployments to Argo Rollouts, we let our developers get acclimated for the next few weeks. 

Our new setup still wasn’t fully optimized, but we felt like it was a big improvement compared to the previous one. And while we could think of many improvements to make things even more reliable before enabling continuous deployment, we decided to get feedback from the team during this period, to iterate more effectively.

Some projects introduced additional technicalities to overcome, but we easily identified a small first batch of projects where we could enable CD. Before deployment, we asked the development team if we were missing anything they needed to be comfortable with automatic deployment of their code in production environments. 

With everyone feeling good about where we were at, we removed the manual step in our CI system (GitLab) for jobs deploying to production environments.

Next steps on the path to continuous deployment

We’re still monitoring this closely, but so far we haven’t had any issues. We still plan on enabling continuous deployment on all our projects in the near future, but it will be a work in progress for now.

Here are some ideas for future improvements that anticipate potential roadblocks:

• Some projects still require additional safeguards before continuous deployment. Automating database migrations is one of our biggest challenges. Helm pre-upgrade hooks would allow us to check if a migration is necessary before updating an application and run it when appropriate. But when automating these database migrations, the tricky part is avoiding heavy locks on critical tables.
• It still isn’t that easy to track what version of a service is currently deployed. When things go according to plan, the last commit in the main branch should either be deployed or currently deploying. To solve this, we could go a step further and version the state of each application for each cluster, including the version identifier for the version that should be deployed. We’re also monitoring the Argo image updater repository closely. When a stable version is released, it could help us detect new available versions for services, deploy them, and update the configuration in Git automatically.
• When there are multiple clusters per environment with the same services deployed, we end up with too many ArgoCD applications. One thing we could do is use the “app of apps” pattern and manage a single application to create all the other required applications for a given service.
• On the bigger projects, the volume of activity may require the queuing of deployments. In fact, if two people merge changes in the main branch around the same time, there could be issues. The last thing we want is for the last commit to be deployed and then replaced by the commit preceding it.

We’re excited to explore these challenges. And, overall, our developers have welcomed these changes with open arms. It helps that our systems have been successful at stopping bad deployments from creating big incidents so far. 

While we haven’t reached the end of our journey yet, we are confident that we are on the right path, moving at the right pace for our team.

As you work with SQLAlchemy, over time, you might have a performance nightmare brewing in the background that you aren’t even aware of.

In this lesser-known issue, which strikes primarily in larger projects, normal usage leads to an ever-growing number of idle-in-transaction database connections. These open connections can kill the overall performance of the application.

While you can fix this issue down the line, when it begins to take a toll on your performance, it takes much less work to mitigate the problem from the start.

At Gorgias, we learned this lesson the hard way. After testing different approaches, we solved the problem by extending the high-level SQLAlchemy classes (namely sessions and transactions) with functionality that allows working with "live" DB (database) objects for limited periods of time, expunging them after they are no longer needed.

This analysis covers everything you need to know to close those unnecessary open DB connections and keep your application humming along.

The problem: your database connection states are monopolizing unnecessary resources

Leading Python web frameworks such as Django come with an integrated ORM (object-relational mapping) that handles all database access, separating most of the low-level database concerns from the actual user code. The developer can write their code focusing on the actual logic around models, rather than thinking of the DB engine, transaction management or isolation level.

While this scenario seems enticing, big frameworks like Django may not always be suitable for our projects. What happens if we want to build our own starting from a microframework (instead of a full-stack framework) and augment it only with the components that we need?

In Python, the extra packages we would use to build ourselves a full-fledged framework are fairly standard: They will most likely include Jinja2 for template rendering, Marshmallow for dealing with schemas and SQLAlchemy as ORM.

Request-response paradigm vs. background tasks

Not all projects are web applications (following a request-response pattern) and among web applications, most of them deal with background tasks that have nothing to do with requests or responses.

This is important to understand because in request-response paradigms, we usually open a DB transaction upon receiving a request and we close it when responding to it. This allows us to associate the number of concurrent DB transactions with the number of parallel HTTP requests handled. A transaction stays open for as long as a request is being processed, and that must happen relatively quickly — users don't appreciate long loading times.

Transactions opened and closed by background tasks are a totally different story: There's no clear and simple rule on how DB transactions are managed at a code level, there's no easy way to tell how long tasks (should) last, and there usually isn't any upper limit to the execution time.

This could lead to potentially long transaction times, during which the process effectively holds a DB connection open without actually using it for the majority of the time period. This state is known as an idle-in-transaction connection state and should be avoided as much as possible, because it blocks DB resources without actively using them.

The limitations of SQLAlchemy with PEP-249

To fully understand how database access transpires in a SQLAlchemy-based app, one needs to understand the layers responsible for the execution.

At the highest level, we code our DB interaction using high-level SQLAlchemy queries on our defined models. The query is then transformed into one or more SQL statements by SQLAlchemy's ORM which is passed on to a database engine (driver) through a common Python DB API defined by PEP-249. (PEP-249 is a Python Enhancement Proposal dedicated to standardizing Python DB server access.) The database engine communicates with the actual database server.

At first glance, everything looks good in this stack. However there's one tiny problem: The DB API (defined by PEP-249) does not provide an explicit way of managing transactions. In fact, it mandates the use of a default transaction regardless of the operations you're executing, so even the simplest select will open a transaction if none are open on the current connection.

SQLAlchemy builds on top of PEP-249, doing its best to stay out of driver implementation details. That way, any Python DB driver claiming PEP-249 compatibility could work well with it.

While this is generally a good idea, SQLAlchemy has no choice but to inherit the limitations and design choices made at the PEP-249 level. More precisely (and importantly), it will automatically open a transaction for you upon the very first query, regardless whether it’s needed. And that's the root of the issue we set out to solve: In production, you'll probably end up with a lot of unwanted transactions, locking up on DB resources for longer than desired.

Also, SQLAlchemy uses sessions (in-memory caches of models) that rely on transactions. And the whole SQLAlchemy world is built around sessions. While you could technically ditch them to avoid the idle-in-transactions problem with a “lower-level” interface to the DB, all of the examples and documentation you’ll find online uses the “higher-level” interface (i.e. sessions). It’s likely that you will feel like you are trying to swim against the tide to get that workaround up and running.

Postgres and the different types of autocommits

Some DB servers, most notably Postgres, default to an autocommit mode. This mode implies atomicity at the SQL statement level — something developers are likely to expect. But they prefer to explicitly open a transaction block when needed and operate outside of one by default.

If you're reading this, you have probably already Googled for "sqlalchemy autocommit" and may have found their official documentation on the (now deprecated) autocommit mode. Unfortunately this functionality is a "soft" autocommit and is implemented purely in SQLAlchemy, on top of the PEP-249 driver; it doesn't have anything to do with DB's native autocommit mode.

This version works by simply committing the opened transaction as soon as SQLAlchemy detects an SQL statement that modifies data. Unfortunately, that doesn't fix our problem; the pointless, underlying DB transaction opened by non-modifying queries still remains open.

When using Postgres, we could in theory play with the new AUTOCOMMIT isolation level option introduced in psycopg2 to make use of the DB-level autocommit mode. However this is far from ideal as it would require hooking into SQLAlchemy's transaction management and adjusting the isolation level each time as needed. Additionally, "autocommit" isn't really an isolation level and it’s not desirable to change the connection's isolation level all the time, from various parts of the code. You can find more details on this matter, along with a possible implementation of this idea in Carl Meyer's article “PostgreSQL Transactions and SQLAlchemy.”

At Gorgias, we always prefer explicit solutions to implicit assumptions. By including all details, even common ones that most developers would assume by default, we can be more clear and leave less guesswork later on. This is why we didn't want to hack together a solution behind the scenes, just to get rid of our idle-in-transactions problem. We decided to dig deeper and come up with a proper, explicit, and (almost) hack-free method to fix it.

Visualizing an idle-in-transaction case

The following chart shows the profile of an idle-in-transaction case over a period of two weeks, before and after fixing the problem.

As you can see, we’re talking about tens of seconds during which connections are being held in an unusable state. In the context of a user waiting for a page to load, that is an excruciatingly long period of time.

The solution: expunged objects and frozen models

Expunging objects to prevent long-lasting idle connections

SQLAlchemy works with sessions that are, simply put, in-memory caches of model instances. The code behind these sessions is quite complex, but usage boils down to either explicit session reference...

...or implicit usage.

Both of these approaches will ensure a transaction is opened and will not close it until a later ***session.commit()***or session.rollback(). There's actually nothing wrong with calling session.commit() when you need to explicitly close a transaction that you know is opened and you’re done with using the DB, in that particular scope.

To address the idle-in-transaction problem generated by such a line, we must keep the code between the query and the commit relatively short and fast (i.e. avoid blocking calls or CPU-intensive operations).

It sounds simple enough, but what happens if we access an attribute of a DB model after session.commit()? It will open another transaction and leave it hanging, even though it might not need to hit the DB at all.

While we can't foresee what a developer will do with the DB object afterward, we can prevent usage that would hit the DB (and open a new transaction) by expunging it from the session. An expunged object will raise an exception if any unloaded (or expired) attributes are accessed. And that’s what we actually want here: to make it crash if misused, rather than leaving idle-in-transaction connections behind to block DB resources.

Building an expunging context manager to handle transactions and connections

When working with multiple objects and complex queries, it’s easy to overlook the necessary expunging of those objects. It only takes one un-expunged object to trigger the idle-in-transaction problem, so you need to be consistent.

Objects can't be used for any kind of DB interaction after being expunged. So how do we make it clear and obvious that certain objects are to be used in within a limited scope? The answer is a Python context manager to handle SQLAlchemy transactions and connections. Not only does it allow us to visually limit object usage to a block, but it will also ensure everything is prepared for us and cleaned up afterwards.

The construct above normally opens a transaction block associated to a new SQLAlchemy session, but we've added a new expunge keyword to the begin method, instructing SQLAlchemy to automatically expunge objects associated with block's session (the tx.session). To get this kind of behavior from a session, we need to override the begin method (and friends) in a subclass of SQLAlchemy's Session.

We want to keep the default behavior and use a new ExpungingTransaction instead of SQLAlchemy's SessionTransaction, but only when explicitly instructed to by the expunge=True argument.

You can use the class_ argument of sessionmaker to instruct it to build am ExpungingSession instead of a regular Session.

The last piece of the puzzle is the ExpungingTransaction code, which is responsible for two important things: committing the session so the underlying transaction gets closed and expunging objects so that we don't accidentally reopen the transaction.

By following these steps, you get a useful context manager that forces you to group your DB interaction into a block and notifies you if you mistakenly use (unloaded) objects outside of it.

Using frozen models to deal with expunged objects

What if we really need to access DB models outside of an expunging context?

Simply passing models to functions as arguments helps in achieving a great goal: the decoupling of models retrieval from their actual usage. However, such functions are no longer in control of what happens to those models afterwards

We don't want to forbid all usage of models outside of this context, but we need to somehow inform the user that the model object comes “as is,” with whatever loaded attributes it has. It's disconnected from the DB and shouldn't be modified.

In SQLAlchemy, when we modify a live model object, we expect the change to be pushed to the DB as soon as commit or flush is called on the owning session. With expunged objects this is not the case, because they don't belong to a session. So how does the user of such an object know what to expect from a certain model object? The user needs to ensure that she:

• Doesn't access an unloaded attribute of a live DB object, as it may open an unwanted transaction
• Doesn't modify attributes of an expunged object, as it won't be saved

To safely and explicitly pass along these kind of model objects, we introduced frozen objects. Frozen objects are basically proxies to expunged models that won't allow any modification.

To work with these frozen objects, we added a freeze method to our ExpungingSession:

So now our code would look something like this:

Now, what if we want to modify the object outside of this context, later on, (e.g. after a long-lasting HTTP request)? As our frozen object is completely disconnected from any session (and from the DB), we need to fetch a warm instance associated to it from the DB and make our changes to that instance. This is done by adding a helper fetch_warm_instance method to our session...

...and then our code that modifies the object would say something like this.

When the second context manager exits, it will call commit on tx.session, and changes to my_model will be committed to the DB right away.

Frozen Relationships

We now have a way of safely dealing with models without generating idle-in-transaction problems, but the code quickly becomes a mess if we have to deal with relationships: We need to freeze them separately and pass them along as if they aren’t related. This could be overcome by telling the freeze method to freeze all related objects, recursively walking the relationships.

We'll have to make some adjustments to our frozen proxy class as well.

Now, we can fetch, freeze, and use frozen objects with any preloaded relationships.

Additional recommendations and caveats

• Don't call session.commit() inside an expunging context manager's block. In fact, avoid using session at all and use tx.session instead. The context manager will take care of flushing and committing the session when exited.
• Avoid nested sessions inside the context block.
• Try to use one single query inside a context manager. If you need multiple queries, it often makes sense to use separate context blocks for each one.
• If you don't need to pass along an entire model object, you don't need to freeze it. Imagine that you only need an object's id or name attribute; you can simply store it in a variable while inside the expunging context block.

Avoid idle-in-transaction connection states to preserve DB resources

While the code to access the DB with SQLAlchemy may look simple and straightforward, one should always pay close attention to transaction management and the subtleties that arise from the various layers of the persistence stack.

We learned this the hard way, when our services eventually started to exhaust the DB resources many years into development.

If you recently decided to use a software stack similar to ours, you should consider writing your DB access code in such a way that it avoids idle-in-transaction issues, even from the first days of your project. The problem may not be obvious at the beginning, but it becomes painfully apparent as you scale.

If your project is mature and has been in development for years, you should  consider planning changes to your code to avoid or to minimize idle-in-transaction issues, while the situation is still under control. You can start writing new idle-in-transaction-proof code while planning to gradually update existing code, according to the capacity of your development team.