Transform Slots Into Formats Your URLs Accept

When a user interacts with the Alexa skill for your app or website, Alexa interprets the user's speech and sends the user to a deep link in your app or website. Slots represent variables within the user's speech. Slot types convert the user's utterance into data types such as numbers and dates.

When you create an App/Website skill with the developer console, the default date and duration formats for the slot type might not match the date and duration formats for deep links to your app or website. To transform the slot formats into formats that work with your URLs, you use slot transformations when you configure your skill. You select which slots you want to convert to a different format, and map the resulting transformed values to URL parameters in your template.

Where you transform slots

You transform slots when you link a date or duration parameter to a slot by using the developer console.

Going to the slot link dialog box

Toward the bottom of the parameter-link dialog box, you have the option to create a slot transformation.

Parameter link dialog box

Default formats

If you don't use slot transformations for AMAZON.DATE or AMAZON.DURATION, Alexa provides the values to your URLs in the following formats.

  • AMAZON.DATE – By default, this slot type converts words that represent dates into a date format and then provides the dates to your skill by using ISO-8601 date format. For details, see AMAZON.DATE.
  • AMAZON.DURATION – By default, this slot type converts words that indicate durations into a numeric duration and then provides the duration to your skill in a format based on the ISO-8601 duration format. For details, see AMAZON.DURATION.

Example slot transformations

This section contains examples of slot transformations for AMAZON.DATE and AMAZON.DURATION.

Date example

An Alexa app user might say to a trip-planning skill, "Book a hotel for next weekend." In this case, the slot value is next weekend. If the skill is configured such that this slot is of built-in slot type AMAZON.DATE, the trip-planning skill sends the user to a deep link such as the following URL: https://www.example.com/hotel?date=2022-W09-WE.

As shown in the previous URL, Alexa represents "next weekend" as a single AMAZON.DATE value in the default format. However, your app or website might need to split the date into a start date and an end date. If you set up a slot transformation, you can have Alexa send the user to deep links such as https://www.example.com/book?start=2022-02-26&end=2022-02-27.

Duration example

An Alexa app user might say to a workout skill, "Start a 30-minute workout." In this case, the slot value is 30 minutes. If the skill is configured such that this slot is of built-in slot type AMAZON.DURATION, the workout skill sends the user to a deep link such as the following URL: https://www.example.com/workout?duration=PT30M. If you set up a slot transformation, you can have Alexa send the user to deep links such as the formats shown in the following table.

Deep link format Example

https://www.example.com/workout{?duration}

https://www.example.com/workout?duration=30m

https://www.example.com/workout{?dur,units}

https://www.example.com/workout?dur=30&units=mins

https://www.example.com/workout{?start,dur}

https://www.example.com/workout?start=2021-12-14T00:00&dur=30min

https://www.example.com/workout{?start,end}

https://www.example.com/workout?start=2021-12-14T00:00&end=2021-12-14T00:30

https://www.example.com/workout{?start,end,dur}

https://www.example.com/workout?start=2022-02-24T10:58&end=2022-02-24T11:28&dur=30min

Available transformations

You can transform a single value into two values, or you can transform a single value into a single value of another format.

Transform a single value into two values

You can transform AMAZON.DURATION and AMAZON.DATE into two values, START and END. You pick either the START or the END time as follows:

  • For AMAZON.DATE, START and END can be any variant of alphanumeric characters plus MM, DD, YY, or YYYY.
  • For AMAZON.DURATION, START and END can be a mix of alphanumeric characters along with units in seconds, minutes, hours, weeks, months, or years.

Transform a single value into a single value of another format

You can keep AMAZON.DURATION and AMAZON.DATE as single values, but transform the values as follows:

  • For AMAZON.DATE, the single value defaults to the first day of the time period in question. For example, "weekend" transforms to Saturday and "next week" transforms to Sunday.
  • For AMAZON.DURATION, the single value is configurable.

In the case of a single value, there are still START and END dates under the hood. The START and END dates are set to the following values:

User says START value END value

A specific date

12:00 AM on the specified date

12:00 AM on the specified date

"This week"

12:00 AM today

12:00 AM of the same day next week

"Next week"

Sunday 12:00 AM

Saturday 12:00 AM

"This weekend"

Saturday 12:00 AM

Sunday 12:00 AM

Time and date format

The following table shows you the letters you can use to transform AMAZON.DATE and AMAZON.DURATION into a format that works for your use case.

Letter Date or Time Component Presentation Examples

G

Era designator

Text

AD

y

Year

Year

1996; 96

Y

Week year

Year

2009; 09

M

Month in year (context sensitive)

Month

July; Jul; 07

L

Month in year (standalone form)

Month

July; Jul; 07

w

Week in year

Number

27

W

Week in month

Number

2

D

Day in year

Number

189

d

Day in month

Number

10

F

Day of week in month

Number

2

E

Day name in week

Text

Tuesday; Tue

u

Day number of week (1 = Monday, …, 7 = Sunday)

Number

1

a

AM/PM marker

Text

PM

H

Hour in day (0-23)

Number

0

k

Hour in day (1-24)

Number

24

K

Hour in AM/PM (0-11)

Number

0

h

Hour in AM/PM (1-12)

Number

12

m

Minute in hour

Number

30

s

Second in minute

Number

55

S

Millisecond

Number

978

z

Time zone

General time zone

Pacific Standard Time; PST; GMT-08:00

Z

Time zone

RFC 822 time zone

-800

X

Time zone

ISO 8601 time zone

-08; -0800; -08:00

Slot transformation presentation rules

Certain rules apply to the presentation of text, numbers, months, years, general time zones, RFC 822 time zones, and ISO 8601 time zones.

Rules for text

The following rules apply to the presentation of text:

  • You can place an unlimited number of the same character together, but the result is only one output. In other words, placing multiples of the same letter in a row doesn't do anything. For example, G, GG, GGG, and GGGG all result in AD.

Rules for numbers

The following rules apply to the presentation of numbers:

  • If you provide more characters then needed to represent a number, all unneeded characters become 0. For example, DDD on the first day of the year is 001, on the 25th day of the year is 025, on the 300th day of the year 300, and so on. Similarly, DDDD on the 300th day of the year becomes 0300.
  • The characters that appear will be the minimum number required to show the number. For example, M in December becomes 12, and M in January becomes 1.

Rules for months

The following rules apply to the use of month characters (M and L):

  • Two or fewer month characters in a row act as a number. For example, M in January results in 1, MM in January results in 01, and so on.
  • Three month characters in a row produces the shortened version of the month's spelling. For example, MMM in January results in Jan.
  • Greater than or equal to four month characters in a row always results in spelling the full month name. For example, MMMM and MMMMM in January produces January.

Rules for years

The following rules apply to the presentation of years:

  • If you provide a pattern of two letters, the year is truncated to two digits. Otherwise, the year is interpreted as a number. For example, y becomes 2012, yy becomes 12, and yyy becomes 2012.

Rules for general time zones

The following rules apply to the presentation of general time zones:

  • If the time zone has a name, the time zone name is interpreted as text.
  • For time zones that represent a GMT offset value, use the syntax GMT Sign Hours : Minutes, where:
    • Sign is + or -.
    • Hours is Digit or Digit Digit, where Digit is a number between 0 and 9, inclusive.
    • Minutes is Digit Digit, where Digit is a number between 0 and 9, inclusive.
  • Hours must be between 0 and 23, and minutes must be between 00 and 59.
  • The format is locale-independent and digits are taken from the basic Latin block of the Unicode standard.
  • RFC 822 time zones are also accepted.

Rules for RFC 822 time zones

The following rules apply to the presentation of RFC 822 time zones:

  • Use the syntax Sign TwoDigitHours Minutes, where:
    • Sign is + or -.
    • TwoDigitHours is Digit Digit. TwoDigitHours must be between 00 and 23.
  • General time zones are also accepted.

Rules for ISO 8601 time zones

The following rules apply to the presentation of ISO 8601 time zones:

  • You can use one of the following formats:
    • OneLetterISO8601TimeZone, which is Sign TwoDigitHours Z
    • TwoLetterISO8601TimeZone, which is Sign TwoDigitHours Minutes Z
    • ThreeLetterISO8601TimeZone, which is Sign TwoDigitHours : Minutes Z
  • Z is parsed as the UTC time zone designator. General time zones are not accepted.
  • If the offset value from GMT is 0, Z is produced. If the number of pattern letters is one, any fraction of an hour is ignored. For example, if the pattern is X and the time zone is GMT+05:30, the output is +05.