How to use API Failure with Conversations

Question

question

matthewp asked · Jul 28, 2020 at 11:55 AM

How to use API Failure with Conversations

None of the example apps use API Failure and it's unclear to me what it's for or how to use it.

These docs suggest that you can use it when your API is unable to process a request, for example when there is no weather data for a city.

But how do you do it? Do you have an API Success and API Failure in the same dialog? Or do you create separate dialogs for these? If separate how does it know when to trigger the successful dialog vs the failed dialog?

It would be nice if one of the example apps used API Failure so we can see how to use it. The weather example doesn't use API Failure, but rather uses APL in the success response to fallback to a message when there is no weather data.

dialog model alexa-conversations

0 · Show 1

10 |2000 characters needed characters left characters exceeded

Attachments: Up to 2 attachments (including images) can be used with a maximum of 524.3 kB each and 1.0 MB total.

swarajs933 · Jul 28, 2020 at 01:31 PM

Thanks for sharing it

0 · Share ·

3 Answers

Answer 1 · 2020-08-11T23:46:27Z

KirkC@Amazon answered · Aug 11, 2020 at 11:46 PM · ACCEPTED ANSWER

Hi matthewp. Thanks for your patience, I asked around and it turns out that you should use "API Failure" in conjunction with a "Response Condition". Response conditions use APL Data-Binding syntax:

https://developer.amazon.com/en-US/docs/alexa/alexa-presentation-language/apl-data-binding-syntax.html

Let's say this is my dialog, note that on my last Alexa turn my "Dialog Act" is "API Failure", my response condition is "${null}" and my response is "return_weather_fail"

Now, you might be asking, what does "${null}" really mean in this context? It means that the "response.apiResponse" object returned by my skill's back-end is null (not that the skill didn't respond at all). Such a response might look like:

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "apiResponse": {}
  }
}

Therefore, if I receive a response like this from my skill's back-end, Alexa Conversations will pick a response from my "return_weather_fail" template here:

A user interaction with my skill in this scenario might thus be:

Me: Alexa, launch weather skill
Alexa: Welcome
Me: What's the weather
Alexa: For what city?
Me: Seattle
Alexa: Sorry, weather is currently unavailable

Where "Sorry, weather is currently unavailable" is a response defined in my "return_weather_fail" response template.

To be clear, you could get a bit more creative with your skill's responses and "response conditions." For example, if you added a key to your returned "response.apiResponse" of "status" with possible values of "SUCCESS" or "FAILURE":

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "apiResponse": {
      "city": "seattle",
      "temperature": "73",
      "status": "FAILURE"
    }
  }
}

You could use a "response condition" like the following to check that "status" key value:

${returnedWeather0.status == 'FAILURE'}

1-ac-forum-response-condition.png (112.7 kB)

2-ac-forum-response-template.png (103.0 kB)

1 · Show 1 · Share

10 |2000 characters needed characters left characters exceeded

Attachments: Up to 2 attachments (including images) can be used with a maximum of 524.3 kB each and 1.0 MB total.

GuilhermeFerreira.ME · Aug 25, 2020 at 09:47 AM

That example is #GOLD! Thanks a lot!

1 · Share ·

Answer 2 · 2020-08-24T23:39:41Z

Tradelast answered · Aug 24, 2020 at 11:39 PM

@KirkC@Amazon - thanks, I just ran into this question today. In addition to what you answered, you also have to edit the GetWeather API Definition to add the new return_weather_fail response to the "Responses associated with this API Definition"

1 · Share

10 |2000 characters needed characters left characters exceeded

Attachments: Up to 2 attachments (including images) can be used with a maximum of 524.3 kB each and 1.0 MB total.

Answer 3 · 2020-08-01T01:01:11Z

KirkC@Amazon answered · Aug 01, 2020 at 01:01 AM

Hi matthewp. To try and answer this I created an Alexa Conversations skill which calls a real weather service API. Now, since the Alexa Conversations API succeeding vs failing seemed like two distinct scenarios, I created two separate dialogs.

The second dialog, representing a failed API call, end with Alexa telling the user "Sorry, weather is currently unavailable." This turn is associated with the "API Failure" dialog act and a new "return_weather_fail" response that I also created.

The skill's interaction model built and I sought to replicate a "failed" API call by commenting out the bit of my code that returns an Alexa Conversations response. Here was the interaction:

Me: Alexa, launch 'weather skill'
Alexa: For what city?
Me: Seattle
Alexa: Something went wrong

The problem here though is that I didn't define "something went wrong" in my "return_weather_fail" response. I have therefore escalated this question internally to the appropriate engineering team.

0 · Share

10 |2000 characters needed characters left characters exceeded

Attachments: Up to 2 attachments (including images) can be used with a maximum of 524.3 kB each and 1.0 MB total.

How to use API Failure with Conversations

question details

Related Questions