Write Out a Script with Conversational Turns
Once you’ve got a purposeful concept defined and you’ve outlined some features, the next step is to write your dialog as a script. You write your conversations down the same way you’d write a film or stage script.
- Script writing
- Understand the elements of a conversational turn
- Write the shortest route to completion
- Create alternate paths
- Note the behind-the-scenes system logic
- Write out your welcome, help, and error messages
- Give it a test run
- Sample scripts
A basic script won’t fully represent how customers will interact with your skill in real life. Customers may say too little, too much, or say things that you weren’t expecting. Writing a script is a way to visualize any number of pathways that a customer might interact with in your experience. It helps you stress-test your logic to ensure you’ve captured any necessary errors or variables to consider. Here are a few techniques you should explore when you write your script:
Understand the elements of a conversational turn
The easiest way to design for Alexa is first to understand the elements of a turn, or the order of operations in the conversational flow. Here’s how it works:
The customer always starts the conversation
The customer’s dialog is called the utterance. The customer starts the utterance by waking the device with a wake word (or pressing a physical or touch-screen button). The customer then asks Alexa a question or makes a request.
For example, customers interact with the built-in weather service like this:
When customers interact with a custom-built skill to look up tide information, the utterance is very similar, although the customer must include a name identifying the skill ("Tide Pooler" in this example):
The Alexa service maps these utterances to intents and slots. For example the utterances “get high tide” or “when is high tide” would map to the getTideInformation intent and a “tideLevel” slot with the value of “high”. When you build your skill, you define your own interaction model of utterances, intents, and slots. Pre-built models, such as Smart Home, have the interaction model already set up for you to modify. For more information about how to build intents and slots, see Create Intents, Utterances, and Slots.
In conjunction with the intent and slot information, your skill identifies the situation
The skill can assess if this is a first time use of a skill, a return, or if the customer has information saved in the skill that the skill needs to access.
Alexa formulates a response
She needs to directly answer the customer’s question or fulfill the request in some way. For example:
Alexa asks a prompt.
If your skill has more features or information that would be pertinent to the use case, Alexa prompts the customer for more information. If not, you can end the skill session here. For example:
For smart home use cases, Alexa will perform the action without a prompt and end the turn after the initial utterance and response. Alexa does not provide a prompt back to the customer because she completed the request and the customer doesn’t require further information or action. For example:
Write the shortest route to completion
You can create the shortest route to completion when the customer gives all information and slots at once, the customer has already linked an account if needed, and other prerequisites are satisfied in a single invocation of the skill.
Create alternate paths
Often, what the customer says doesn’t include all information necessary to complete the request. Identify alternate pathways and customer decisions. For example, “Tell me about X brand” or “I’d like to know my card balance” requires one-off responses that you need to consider and, where applicable, leverage as ways to drive the customer back into the main flow of the skill.
Note the behind-the-scenes system logic
Identify behind-the-scenes system decisions in brackets, not dialog, as a note to yourself. This will help you later when you outline your storyboards.
Write out your welcome, help, and error messages
These are required as part of the Alexa experience. You should customize them to fit your skill since they are direct moments of need for the customer.
Give it a test run
When you have a good amount of dialog, test it aloud with a friend. One of you play the customer and the other play Alexa. Testing this way, you can quickly see if your conversation flows well or is stilted. You can also figure out quickly if this is a natural way to use the skill or if there are some edge cases you haven’t thought about but need to design for.
The Foodie – optimal (happy) path
Alexa, open The Foodie.
Howdy! Welcome to the Foodie. I’ll help you find the right food right now. To make that easier, you can give me permission to get your location, just check the Alexa app. How rude of me- I forgot to ask. What’s your name?
My name is Justin.
Hi Justin! Nice to meet you. I can recommend cuisines based on flavor profiles. You can ask for things like spicy, savory, greasy, and fresh. What sounds good to you?
I want something savory and spicy.
Ah! I’d recommend something Korean or Spanish. Which of those sounds better right now?
Korean sounds great!
The Foodie – help
The customer might ask for help in the middle of using the skill.
I don’t understand.
I can help you find food nearby or find recipes for you. You can tell me a flavor profile, a type of cuisine, or dietary restriction and I’ll do my best to help you find a great meal.
Oh, I would like Thai food.
Sounds good! Let’s talk about allergies and dietary preferences, such as allergies to peanuts or dietary preferences, such as kosher or vegan. Do you have any other food preferences or allergies I should know about?
Once you've got a few scripts ready to go, it's time to create your storyboards to see how it all comes together.