What is new (Final Round)?

  1. Google / Apple Maps navigation using 'Alexa for Apps'
    On mobile devices, users now get an option to launch Maps applications with directions to the top restroom preloaded. Thanks to the 'Alexa for Apps (preview)' team for whitelisting the skill to integrate with their 'preview' software.

  2. Search by address, city and state.
    Previously address based search was limited to zip code which is neither natural nor granular enough. With the latest release, users can search using full addresses like '2121 Denny Way', '535 Pontius Avenue, California' etc.

  3. Personalized results on ambiguous addresses.
    'Alexa, find restrooms at Union Street' is an ambiguous query because there are many 'Union Streets' across US. The latest update leverages user's current location and device registration address to personalize the search results. So, a user in Seattle will find restrooms near 'Union Street, Seattle' and a user in California will find restrooms near 'Union Street, California'.
    Note: If the user hasn't granted permissions to use their location, we perform a generic search. Such users can always try again by specifying city and state.
    Note: The signals are used only to influence the search results and not as a strict filter. If users are not satisfied, they will have to provide city and state.

  4. Robust input correction
    Alexa Conversations models were updated to allow for more robust input corrections and non linear dialogs. Users can switch between location based, zip code based and address based searches and correct their inputs multiple times in the same session.

  5. Better error case handling
    Instead of ending the session when users provide an unsupported address, we now let them choose to provide an alternate address or end the session.

How did Alexa Conversations Help??

  1. Heavy lifting outside code: In the most complex case, the skill collects 7 inputs from user. That would have been a lot of boiler plate cumbersome code in a traditional skill where as in AXC, I just had to configure dialogs and dialog acts and AXC does most of the heavy lifting before delegating over to the developers Lambda.

  2. Reliable input corrections: In one of the paths, the skill collects full addresses where the likelihood of an ASR mis-recognition is higher. That makes input correction very important. I'm pleased with how easy and reliable AXC's input corrections are once the dialogs are modeled properly. I tried correcting all inputs several times in a single session and it works!

  3. Error handling: 'Request Alt' is a poorly documented but a powerful dialog act. It helped me build dialogs to nudge the user away from unsupported addresses like '24th Avenue' towards supported addresses like 'Union Street' without having them to start over. I could retain all other inputs and just get them to correct the invalid input without leaving AXC.

  4. AI predictions: While building the AXC model, I only used the word 'restrooms' in all my utterance sets. When I asked a friend to test the skill, they surprised me by asking for 'washrooms'. I was pleasantly surprised to see AXC handle utterances asking for 'washrooms' just fine. Even today, my utterance sets only contain 'restrooms' but AXC is able to handle other variations like 'washrooms' and 'toilets' just fine.

  5. APL / APL-A: My skill has 21 APL-A responses and 10 APL responses. Each of the APL-A responses has multiple variations to make the skill sound human. In a traditional skill developers wouldn't create so many multimodal responses because it is too cumbersome. AXC made it significantly easier and decoupled from code which encourages developers to create more multimodal responses.

Key Test Cases:

1. search for restrooms near me (try this on a mobile device)
2. search for gender neutral restrooms by address
3. search for accessible and toddler friendly restrooms by zipcode
4. switch context by asking for help after initiating a search
5. initiate a search and when Alexa asks you to confirm the inputs, change the inputs
6. try the skill with email and location permissions enabled and disabled
7. try a non-existent zip code like 98100
8. try an unsupported address like 24th Avenue


In an ideal world, every individual could use the restroom that aligns with the gender they identify with. We do not live an ideal world though and one of the biggest battlefields upon which the fight for transgender rights is taking place daily are restrooms (especially when they are traveling to a new place and don't know where to find a safe restroom). Despite legislative victories in recent years regarding restroom usage, many transgender individuals still face both verbal and physical harassment simply for using the restroom of their choice. Nobody should have to face that - and that is why I created the 'Refugee Restrooms' skill.

What it does

Refuge Restrooms is an Alexa skill that seeks to provide safe restroom access for transgender, intersex, and gender nonconforming individuals. The skill also supports users looking for accessible restrooms and restrooms with changing tables.

The skill's primary goal is to help users who are traveling or planning their travel.

For users who are traveling- The skill supports restroom search by proximity to their current location. We use their phone's location to search for restrooms near by. If the user hasn't consented to use their geo location, we request the user to grant location permissions or nudge them to search by zipcode instead. Once a restroom is found, we also offer to launch Google Maps or Apple Maps on their phone with directions to the restroom preloaded.

For users who are just planning their trip- The skill supports restroom search by full address or zip code.
A bug in Alexa Conversations prevents us from supporting numbered streets like 24th Ave, 1st street etc. I'm working with an Amazon solution architect to fix the bug and in the meantime we implemented an experience to let the user provide an alternate street address without numbers. For ex, 601 Union Street.

In either case, the criteria that we currently support are unisex restrooms (for gender non-conforming users), accessible restrooms (for differently abled customers) and parent friendly restrooms (for parents traveling with a kid who needs diaper changes).

User's get the results delivered through multiple means -

  1. Through voice (the top result)
  2. On their echo devices with screens (the top result, uses APL)
  3. In their Alexa companion app (up to 5 results)
  4. Users also get an email with clickable Google Maps links to the top 10 restrooms, sorted by distance.
  5. Most importantly, users on mobile devices also get an option to launch either Google Maps or Apple Maps with directions to the top restroom loaded and ready to go.

How I built it

Architecture Diagram

Refugee Restrooms Architecture Diagram

Alexa Conversations The skill requires the following inputs from the user -

  1. Whether they want to search by proximity to their current location or at a specific address or zip code.
  2. The street, city and state if they are searching by address.
  3. The zip code if they are searching at a specific zip code.
  4. One or more of the three supported search criteria. (unisex, accessible, parent-friendly).
  5. Users can also convey that they don't have any search criteria and that any restroom works for them. (In future we plan to add more criteria like restroom ratings, how recently it is updated etc.).

In the most complex case, we need to collect seven pieces of information from the user. To write a skill that collects seven inputs from the user would be quite tedious using the traditional custom skill model.

That is when I learned about Alexa Conversations. I was able to use the power of AI to easily handle the entire conversation around gathering inputs using Alexa Conversations. Once all the inputs are collected and confirmed, I transfer control to the custom skill to actually search and present the restrooms.

AWS Simple Email Service As I built the skill, I realized that just searching for restrooms and giving a voice response isn't really sufficient. In most cases, people don't need the restroom right away and are just planning ahead. It is also very important that they have a clickable navigation link (like Google Maps) which is not possible through voice or Alexa companion app.

So, I decided to enhance the experience by sending an email to the users with the search results (only if the user gave permissions to use their email). The email lets us provide rich information which is prohibitive in a voice interface. The email contains up to 10 results and each result has directions, notes, ratings, Google Maps links, the features of the restroom etc.

I used AWS SES to implement this. It was my first time using SES and I was pleasantly surprised how easy it is to send templated and personalized HTML emails.

Alexa for Apps 'Alexa for Apps' is a preview technology by Alexa that is not yet generally available. It lets us launch 3P applications on a mobile device from an Alexa skill. I was convinced that 'Refugee Restrooms' is a great use case for 'Alexa for Apps' where we can launch Google Maps or Apple Maps with directions to the top restroom result.

Thanks for Alexa for Apps team which was very responsive and helpful to first approve my skill and secondly for their technical help as I tried to get it working with the skill.

Challenges I ran into

  1. Getting a hang of all the concepts of Alexa Conversations took some time. The cook book code samples and the office hours helped a lot.

  2. I habitually rely a lot on ASK CLI based replay-testing while developing skills. However, that is not yet supported for Alexa Conversations based skills. So, I had to double down on unit testing to make sure I keep my development turn around time short instead of having to deploy the skill every time I make a minor change. End of the day, I ended up with as much test code as source code giving me a lot of confidence as I make changes to the skill.

  3. Figuring out the right technology to send emails to the customers was challenging. Once I settled on AWS SES, it was quite easy.

  4. In this skill, I also decided to try slots with multiple values feature recently introduced by Alexa. It made my skill model significantly simpler.

  5. Figuring out how to launch Google Maps and Apple Maps on Android and iOS devices was a challenge. It was a technical challenge and also a UX challenge because I haven't designed a skill that launches other applications before.

Accomplishments that I'm proud of

Bugs I found While building a skill on a new platform is quite fulfilling, I'm actually quite proud of the number of bugs / issues I found with the Alexa-Conversations model. I submitted about 10 issues on the Amazon developer forum and hopefully, these reports help make the platform better as it grows out of beta.

Here are some potential bugs in Alexa Conversations that I submitted -

  1. Data binding not supported in Alexa Conversations APL responses
  2. Poor error messages
  3. Lists in API Arguments are not being sent as slots
  4. Wrong locale format in Alexa Conversations request objects
  5. When utterance set is bulk edited, slot types are being lost resulting

Incorporating APL Incorporating APL in Alexa Conversations responses was a good accomplishment. It dramatically enhanced the Alexa Conversations experience on Echo Show devices and FireTVs. I plan to invest in it even more.

Testing At the onset, I decided to invest a lot in testing my code. I wrote as much test code as source code and I can confidently say every branch has an integration test. I'm very proud of this accomplishment and it helped me iterate very quickly with my code and make changes confidently.

What's next for Refugee Restrooms

  1. The skill currently supports searching at a specific zip code but that is quite limited. User's planning to travel somewhere would be more likely to ask for restrooms by city or full address. I will add support to search for restrooms by full addresses. This is now implemented.

  2. The Refugee Restrooms database backing this skill is international. I need to expand the skill to other locales. Arguably, safe restroom access is even more vital outside the United States.

  3. The Refugee Restrooms database has attributes like rating, recent usages etc. Adding the ability to filter by these attributes will let the users make an informed choice while choosing their restroom. This is an area where Alexa Conversations really shines because I can add more search criteria without having to handle everything myself in the skill code.

  4. The skill is currently one-way. There is no way for users to provide feedback. User feedback is vital for the crowd sourced refugee restrooms database. I need to extend the skill to make it possible for users to provide feedback.

  5. Currently, I send emails to customers with search results. Users on the go would probably prefer an SMS. I plan to add support for that.

Built With

Share this project: