Implement CanFulfillIntentRequest for Name-free Interactions

Note: The use of CanFulfillIntentRequest in Alexa skills is offered as a public beta for English (en-US locale only) and may improve or change as we receive feedback and iterate on the feature. Please provide feedback by creating a post and tagging the post with canfulfillintentrequest on the Alexa Skills Kit developer forum. This feature is available in private beta for other English locales (en-GB, en-IN, en-AU, en-CA). To sign up for preview, send an email to cfir-help@amazon.com

To help ensure that requests are suitable for your skill, consider implementing the CanFulfillIntentRequest interface.

Implement canFulfillIntent

The CanFulfillIntentRequest interface is backward-compatible with existing Alexa skills, so you can add an implementation to fulfill CanFulfillIntentRequest without affecting how your skill works.

A CanFulfillIntentRequest request is made to a skill to query whether the skill can understand and fulfill the intent request with detected slots, before actually asking the skill to take action. The canFulfillIntent response that the skill provides should indicate whether or not the skill can fulfill the request, but the skill must not cause any observable interactions or make any changes in state outside of its scope except to return a value indicating whether the skill can fulfill the request. For example, the skill should not play sound, turn lights on or off, give the customer any feedback, or commit a transaction or a charge.

Suppose the request that the customer makes is "Alexa, play relaxing sounds with crickets." A CanFulfillIntentRequest would then take the following form. The request parameters in this response are the same as for other request types. In this example, Alexa recognizes the PlaySound intent, and the "crickets" value for the Sound slot.

{
  "request": {
    "type": "CanFulfillIntentRequest",
    "requestId": "...",
    "intent": {
      "name": "PlaySound",
      "slots": {
        "Sound": {
          "name": "Sound",
          "value": "crickets"
        }
      },
    },
    "locale": "en-US",
    "timestamp": "..."
  },
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.<skill-id-value>"
      },
      "user": {
        "userId": "<user-id-value>"
      },
      "device": {
        "supportedInterfaces": {}
      }
    }
  },
  "version": "1.0"
}

Response to CanFulfillIntentRequest

When your skill receives a CanFulfillIntentRequest, it is expected to respond with a canFulfillIntent object that contains the mandatory field canFulfill for the intent, and two optional fields per slot–canUnderstand and canFulfill.

Guidelines for canFulfillIntent

Here are guidelines for which option to choose in response to various scenarios. These are suggestions, rather than strict rules, and are meant to ensure your skill gets those requests that it can handle.

Set canFulfill = "YES" if your skill understands all slots, can fulfill all slots, and can fulfill the request in its entirety.
Set canFulfill = NO if your skill cannot understand the intent, and/or cannot understand any of the slots, and/or cannot fulfill any of the slots.
Set canFulfill = MAYBE if your skill can understand the intent, can partially or fully understand the slots, and can partially or fully fulfill the slots. The only cases where your skill should respond with MAYBE is when your skill can potentially complete the request if your skill get more data through a multi-turn conversation with the user. For example, if the skill understands the intent, such as orderCabIntent, but needs the customer to link their account before being able to fulfill the request. Another example is travelBookingIntent, where the skill understands a subset of all identified slots and needs more information before it can determine whether it can fulfill the intent for each slot value.

Note: You must implement Canfulfillintentrequest for all intents in your interaction model.

Guidelines for slot response values

For each slot, a skill is optionally expected to return values for the canUnderstand and canFulfill fields. While skills are expected to have proprietary logic to determine response for each field, general guidelines are provided below.

canUnderstand management

canUnderstand - Indicates whether your skill understands the slot value. Your skill logic needs to determine whether there is a match and the quality of the match. For example, the skill might look up values from a list that you maintain.

Set canUnderstand = "YES" if your skill has a perfect match or a high-confidence match, for example a synonym.
Set canUnderstand = "MAYBE" if your skill has a partial match, for example if the exact slot value does not exist but a variation or a fuzzy match exists.
Set canUnderstand = "NO" if your skill cannot resolve the slot value.

Default values using the entity resolution implementation from the Alexa Skills Kit

The Alexa Skills Kit provides entity resolution. If your skill uses the entity resolution data to understand slot values, the default value for canUnderstand is as follows.

Set canUnderstand = "YES" if entity resolution successfully resolves slot value.
Set canUnderstand = "NO" if entity resolution does not resolve slot value.

If you want, you can overwrite the default.

Values for canUnderstand if your skill does not use lists and do not use the entity resolution implementation

If your skill does not maintain a list of slot values and does not use the entity resolution data, your skill needs some other way of determining how to respond to canUnderstand. Choose the logic while considering your skill and the scenarios that it handles.

The following examples show how a skill might respond to canUnderstand.

Example: [Slot value: canUnderstand]

For catalogued slot values = {New York, Paris, London, Munich}

In this example, the skill sets canUnderstand = "YES" for the slot values "New York", "Paris", and "Munich" because they are exact matches with the catalog, "YES" to "München" because it recognizes the local term for "Munich", and "MAYBE" to "Landon" because it determines the skill user might have meant "London", but would want to confirm with the user before proceeding.

Example: For catalogued slot value = {hyenas}

[hyenas : YES] | pack of hyenas : YES | aardwolf : MAYBE | aardvarks : NO]

Example: For catalogued slot values = {IBM, HP}

Example: For catalogued slot values = {US ARMY, US NAVY, US AIR FORCE}

[The US Army : YES] | US Army : YES | Army : MAYBE | The US Navy : YES | Marines : NO]

Example: For the catalogued slot value = {3457 Hillsborough Road Durham NC Ph: (919 333-4444)}

[Hillsborough Road Starbucks Durham : YES] | [3457 Hillsborough Road Durham NC : YES| Bucks Hillsborough Road Durham : MAYBE]

Example: For catalogued slot value = {iPad 2 16GB White}

[iPad two 16GB White : YES] | iPad 2nd generation 16GB White : YES | I Pad 2 16GB White : MAYBE | iPhone 16GB White : NO]

canFulfill management

Note: You must implement Canfulfillintentrequest for all intents in your interaction model.

canFulfill - This field indicates whether your skill can fulfill the relevant action for the slot that has been partially or fully identified. The definition of fulfilling the slot is dependent on your skill, and your skill service is required to have logic in place to determine whether a slot value can be fulfilled in the context of your skill or not.

Set canFulfill = "YES" if your skill can certainly fulfill the relevant action for this slot value.
Set canFulfill = "NO" if your skill cannot fulfill the relevant action for this slot value.

These examples listed below should clarify how to respond to canFulfill.

Example: A skill that provides animal sounds in response to the name of animal as stated by an Alexa customer

If the skill recognizes the name of animal provided in utterance (that is, canUnderstand = YES), but is unable to play back the sound of the recognized animal because the audio file is not available at the moment, it should return canFulfill = "NO".

Example: A skill that delivers food

If the skill recognizes both the type of food ordered and delivery address, but if the food delivery service backing the skill is unable to deliver food in expected time window, it should return canFulfill = "NO".

Example: A travel booking skill responding to a multi-stop trip query

If the skill recognizes both slot values provided (destinations), but can only provide booking options for the first destination, and not for the second, the skill should return canFulfill = "YES" for the first slot and canFulfill = "NO" for the second slot.

Sample intent response

{
    "version":"1.0",
    "response":{
        "canFulfillIntent": {
            "canFulfill": "YES",
            "slots":{
                "slotName1": {
                    "canUnderstand": "YES",
                    "canFulfill": "YES"
                },
               "slotName2": {
                    "canUnderstand": "YES",
                    "canFulfill": "YES"
                }
            }
        }
    }
}

Update the SDK used by your skill if applicable

If you have used the ASK SDK for Node.js or the ASK SDK for Java in your skill development, and you want to add support for the CanFulfillIntentRequest interface to your Alexa skill, you must update to the ASK SDK for Node.js, ASK SDK for Java, or the ASK SDK for Python as appropriate.

These steps may now be completed through ASK CLI, or through the developer console.

Implement CanFulfillIntentRequest with ASK CLI

To set up ASK CLI, see Quick Start Alexa Skills Kit Command Line Interface. Create a new skill if desired.

If you have set up ASK CLI and are now updating an existing skill, obtain the skill manifest file with this command:

$ ask api get-skill --skill-id amzn1.ask.skill.[unique-value-here] > skill.json

To add support to your skill for CanFulfillIntentRequest, edit the skill.json file, which contains the skill manifest.

Edit the skill information file to include "CAN_FULFILL_INTENT_REQUEST" as a new interface type entry. In the following sample manifest, refer to the interfaces values. Thus, "CAN_FULFILL_INTENT_REQUEST" is another interface which you as a skill developer can choose to support or not.

{
  "manifest":{
    "manifestVersion":"1.0",
    "publishingInformation":{
      "locales":{
        "en-US":{
          "name":"MySkill",
          "summary":"Sample Short Description",
          "description":"Sample Full Description",
          "examplePhrases": [
            "Alexa open hello world",
            "Alexa tell hello world I am Jeff",
            "Alexa tell hello world my name is Peter"
          ]
        }
      },
      "distributionCountries":[
        "US"
      ],
      "isAvailableWorldwide":false,
      "testingInstructions":"Sample Testing Instructions",
      "category":"EDUCATION_AND_REFERENCE"
    },
    "apis":{
      "custom":{
        "endpoint":{
          "uri":"https://customapi-eu.example.com",
          "sslCertificateType":"TRUSTED"
        },
        "regions":{
          "NA":{
            "endpoint":{
              "uri":"https://customapi-na.example.com",
              "sslCertificateType":"TRUSTED"
            }
          }
        },
        "interfaces":[
          {
            "type":"VIDEO_APP"
          },
          {
            "type":"RENDER_TEMPLATE"
          },
          {
            "type":"AUDIO_PLAYER"
          },
          {
            "type":"CAN_FULFILL_INTENT_REQUEST"
          }
        ]
      }
    }
  }
}

Update or create your skill in ASK CLI

You can now use the command-line interface to update or create the new skill definition.

If you are updating an existing skill, use:

$ ask api update-skill --skill-id amzn1.ask.skill.[unique-value-here] --file /path/to/skill/information/file

If you are creating a new skill, use:

$ ask api create-skill --file /path/to/skill/information/file

Implement CanFulfillIntentRequest through the developer console

Open your skill in the developer console. Go to the Build > Custom > Interfaces page, and enable the CanFulfillIntentRequest interface.

Select the CanFulfillIntentRequest interface

Scroll to the top of the panel, and then click Save Interfaces. In the bottom right, a message should appear indicating that the skill manifest saved successfully.

Note: If the skill has been published, implement the CanFulfillIntentRequest interface by making changes in the development version, and then submit the skill for certification once your changes are complete.

Add logic in your skill service to fulfill responses to CanFulfillIntentRequest

Whether you have implemented CanFulfillIntentRequest with ASK CLI or through the developer console, the steps to implement the logic in your skill are the same.

See Understand Name-free Interaction for Custom Skills.

Invoke and test the skill

After you've updated your skill manifest and updated the code for your skill service, you can invoke the skill from ASK CLI or the developer console to test your skill's response.

Create the JSON for testing your skill

Create a new .json file containing the input JSON with the request type set to CanFulfillIntentRequest.

The following is a sample .json file for the request. Substitute the appropriate values for your skill. Because you cannot test CanFulfillIntentRequest with an Alexa-enabled device, the purpose of this file is to duplicate the content of an actual CanfulfillIntentRequest from Alexa for testing with ASK CLI, or in the Alexa Simulator, as described in the next section.

{
  "session":{
    "new": true,
    "sessionId":"SessionId.[unique-value-here]",
    "application":{
      "applicationId":"amzn1.ask.skill.[unique-value-here]"
    },
    "attributes":{
      "key": "string value"
    },
    "user":{
      "userId":"amzn1.ask.account.[unique-value-here]"
    }
  },
  "request":{
    "type":"CanFulfillIntentRequest",
    "requestId":"EdwRequestId.[unique-value-here]",
    "intent":{
      "name":"MyNameIsIntent",
      "slots":{
        "name":{
          "name":"name",
          "value":"Jeff"
        }
      }
    },
    "locale":"en-US",
    "timestamp":"2017-10-03T22:02:29Z"
  },
  "context":{
    "AudioPlayer":{
      "playerActivity":"IDLE"
    },
    "System":{
      "application":{
        "applicationId":"amzn1.ask.skill.[unique-value-here]"
      },
      "user":{
        "userId":"amzn1.ask.account.[unique-value-here]"
      },
      "device":{
        "supportedInterfaces":{

        }
      }
    }
  },
  "version":"1.0"
}

Prepare and test your skill for certification

Whether you are testing in ASK CLI or in the developer console, make sure to test across the following scenarios:

Verify that your skill handles a CanFulfillIntentRequest call with no userId present.
Verify that your skill handles a CanFulfillIntentRequest call with no session information present.
Verify that your skill handles a CanFulfillIntentRequest call for every intent included in your interaction model.

Test the skill using ASK CLI

To invoke the skill from ASK CLI, use the following command:

$ ask api invoke-skill --skill-id amzn1.ask.skill.[unique-value-here] --file /path/to/input/json --endpoint-region [endpoint-region-here]

This command writes your skill's response to the CanFulfillIntentRequest to standard output. To properly test your skill's response, the .json file you created must match the CanFulfillIntentRequest that Alexa would send to your skill.

Test the skill using the developer console

In the developer console, click the Test tab.
Click Manual JSON.
In the text box, enter the JSON for a CanFulfillIntentRequest that invokes the endpoint for your skill.

For aa sample .json file, see create the JSON for testing your skill.

Implement CanFulfillIntentRequest for Name-free Interactions