loading...
Twilio

SMS Code Of Conduct Reporting with Twilio Studio and Slack

annthurium profile image Tilde A. Thurium Originally published at twilio.com ・5 min read

If you care about ensuring the safety and comfort of your community, you must have a code of conduct. Writing a code of conduct document is a necessary first step, but it’s not enough. What happens when a violation occurs? You need processes for reporting and responding to code of conduct incidents. Ideally, there are multiple reporting channels so that people can communicate over text or in person. Some folks might not feel comfortable (or be able) to report code of conduct violations face to face.

Decisions Decisions

There are many possibilities for technology to enable text based code of conduct reporting. Laying out requirements will help us narrow down our choices.

  • Accessible. Reporting technology should be accessible to as many event attendees as possible. Accessibility here means having access to devices that run the technology, as well as usability for folks with disabilities.
  • Secure. Code of conduct reports should flow to a private place where only organizers can see them.
  • Fast. When somebody reports a code of conduct violation, they should receive a response as fast as possible. Don’t leave folks hanging during a vulnerable moment.
  • Scalable. When a code of conduct violation comes in, multiple organizers should be able to respond.
  • Robust. All code requires maintenance, though the less the better. If we can avoid running our own server, great. Organizer turnover is also normal and expected. Ideally we should avoid having a hard coded list of names that needs to be updated as people come and go.

Based on how I stack ranked these priorities, I decided to build an SMS integration with Twilio Studio and Slack for the Write Speak Code community. Most folks at your community or event likely have access to SMS-capable devices, which is a win on the accessibility front. Twilio Studio gives us conditional logic for sending and receiving messages without running our own servers. Slack is “faster” than email in that it’s generally used more synchronously. Email occupies a different, more asynchronous mental space. Depending on your community’s needs and priorities, you might make different choices and that’s fine.

Getting Started

What do you need to get started? First, a Twilio account -- you can sign up for a free one here, or on Twilio.org if your community is a registered nonprofit. You’ll also need a Slack workspace. Sign up for a free one here. If you’ve never used Twilio Studio, check out the quickstart guide.

First, head to the Twilio Studio dashboard. Create a new flow and give it a name, like “Code of Conduct Reporting.” Start from scratch with a blank flow, which gives you 3 triggers. We’ll focus on the incoming message trigger first. Create a new HTTP Request widget, from the Widget library on the right. Call it post_to_slack. Connect the widget to the Incoming Message by dragging and dropping.

Incoming Webhook Ahoy

The post_to_slack widget needs a URL to know where to send the data. To get one, head over to Slack. Enable the incoming webhook integration. Configure the incoming webhook to post to the channel where your reports will be sent. Next, copy the Webhook URL to the clipboard.

A screenshot of Slack's "Integration Settings" UI. There's a "Post to Channel" flyover menu that allows you to select the channel, as well as a "webhook URL" text box to copy from.

Heads up: the channel dropdown only shows private channels you have joined. If you set up a webhook and then leave a private channel, the webhook will continue to work.

Now head back to the Studio dashboard. In the Config for post_to_slack, paste the webhook URL as the Request URL. Change the request method to “POST” and the content type to “Application/JSON”. In our response, we want the sender’s phone number as well as the message they sent, so organizers can follow up with the sender. So let’s put both in the JSON response. You can leave out the phone number if you want to allow anonymous reports, although anonymous reports can be more difficult to properly respond to.

{"text": "message: {{trigger.message.Body}}, number: {{trigger.message.From}}"}

the HTTP REQUEST widget UI from Twilio Studio. There's a request URL text box, where the Slack webhook URL is pasted. A "CONTENT TYPE" menu where "Application/JSON" is selected. A "Request Body" text box where the code snippet above is pasted

Finishing Touches

Next we’ll add response success and failure messages, so that the human on the other end knows whether or not the message was received. Add a new Send Message widget and drag it onto the canvas. Add a warm message. Maybe something like, “Thanks for reporting, one of our organizers will be in touch with you shortly.” Connect the Send Message widget to the success node on the post_to_slack widget.

Time to deal with the failure case. Add another Send message widget. It could say “Sorry, your report didn’t make it through. Please try again or contact the organizers in person.” Connect the failure Send Message widget with the failure node on the post_to_slack widget. If somebody calls the number, we should tell them to try SMS instead. Drag a new Say/Play widget on to the canvas and compose your message. Connect that widget to the “incoming call” node.

The entire Studio flow looks like this:

The UI for an entire Twilio Studio code of conduct reporting workflow.

You’ll need to save and publish your flow when you’re done making changes.

Finally, buy a Twilio phone number. Configure the phone number so that when a call or message comes in, we respond with our new studio flow. Pull out your phone, try it out and see if the message sent to the Slack channel successfully.

The UI for configuring Twilio phone numbers. Voice & Fax is configured to "Accept incoming Voice Calls", with "Webhooks, TwiML Bins, Functions, Studio." When a call comes in, use the "Code of Conduct Reporting" studio flow.  Messaging is configured with the same settings.

Conclusion

Code of conduct enforcement may not be a light or joyous topic, but it’s important. In order to keep people in our communities safe, sometimes we’ve gotta talk about the hard things. Fortunately, many folks are working to push code of conduct best practices forward. Otter.technology has written up best practices for code of conduct language. WeAllJS made a cool command line tool to keep your open source code of conduct up to date. Together we can keep iterating towards better inclusivity, one small step at a time.

Posted on by:

annthurium profile

Tilde A. Thurium

@annthurium

Twilio Developer Evangelist. JavaScripter and Pythonist. Painter of algorithms. they/them.

Twilio

We ❤️developers. Unlock the magic of communications to improve human experience. Twilio has democratized channels like voice, text, chat, and video through APIs.

Discussion

pic
Editor guide