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

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

Alexa needs to directly answer the customer’s question or fulfill the request in some way. For example:

Another 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:

Another example:

For smart home use cases, Alexa performs the action without providing an additional prompt and ends the turn after the initial utterance and response. Alexa doesn't need to prompt the customer again because the customer doesn't need more information or to take further 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.

Sample scripts

The Foodie – optimal (happy) path

USER

Alexa, open The Foodie.

ALEXA

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?

USER

My name is Justin.

ALEXA

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?

USER

I want something savory and spicy.

ALEXA

Ah! I’d recommend something Korean or Spanish. Which of those sounds better right now?

USER

Korean sounds great!

The Foodie – help

The customer might ask for help in the middle of using the skill.

USER

I don’t understand.

ALEXA

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.

USER

Oh, I would like Thai food.

ALEXA

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.