Merci de votre visite. Cette page est disponible en anglais uniquement.

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:

Showcasing the 4 elements of a turn including the user's utterance, the ongoing situation (intent) or state, Alexa's answer back to the user and her re-prompt back to start a new turn.

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:

User: "Alexa, what's the weather?"

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

User: "Alexa, get high tide for Seattle from Tide Pooler."

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:

User: "Alexa, what's the weather?"

Alexa: "Currently, in Seattle there are cloudy skies...."

Another example:

User: "Alexa, get high tide for Seattle from Tide Pooler."

Alexa: "Wednesday, February seventeenth in Seattle, the first high tide will be around one forty-two in the morning, and will peak at about ten feet."

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:

User: "Alexa, what's the weather?"

Alexa: "Currently, in Seattle there are cloudy skies with a thirty percent chance of rain in the evening so bring your umbrella."

(Half second pause.)

Alexa: "Do you want to hear about tomorrow’s forecast?"

Another example:

User: "Alexa, get high tide for Seattle from Tide Pooler."

Alexa: "Wednesday, February seventeenth in Seattle, the first high tide will be around one forty-two in the morning, and will peak at about ten feet."

(Half second pause.)

Alexa: "Would you like to know when the next high tide will occur on Wednesday or a different day?"

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:

User: "Alexa, turn on the living room lights."

(The skill turns on a set of lights in the living room.)

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.

Three examples of a welcome, help, and stop message for a skill using the elements of a conversational turn.

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


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.

Back to top