ISP Plugin

In-skill purchasing (ISP) allows you to sell premium content directly from the Alexa Skills you created.

To make in-skill purchasing handling easier, BotTalk introduces a new ISP Plugin.

You can see the overview of public BotTalk plugins in the Plugins Tab from the BotTalk dashboard.

Note: We’ve created a complete step-by-step tutorial on using Alexa in-skill purchasing (ISP) with BotTalk.

Actions

ISP Plugin adds five new actions. ISP plugin is available to all BotTalk users, so you are not required to activate the plugin to use those actions:

• isp.getProducts
• isp.getProduct
• isp.buy
• isp.upsell
• isp.cancell

The results of the requests fired by these actions are stored in the internal isp_response variable.

Events

Additionally, Amazon sends you several special events after certain transactions, which you can handle similarly to the way you handle user intents - by connecting them with the corresponding steps.

These events are:

• ISP.OnBuy
• ISP.OnUpsell
• ISP.OnCancel

isp.getProducts

isp.getProducts action delivers an array of in-skill products that are available for purchase for this particular skill.

One parameter is required:

• input: true: Always set this parameter to true.

The result of this action is stored in isp_response variable and looks something like that:

{
   "inSkillProducts":[
      {
         "productId":"amzn1.adg.product.01321b13-7bcf-4e1b-81cb-31658fd009bb",
         "referenceName":"apple_pie",
         "type":"CONSUMABLE",
         "name":"Apple Pie",
         "summary":"Apple Pie",
         "entitled":"NOT_ENTITLED",
         "entitlementReason":"NOT_PURCHASED",
         "purchasable":"PURCHASABLE",
         "activeEntitlementCount":0,
         "purchaseMode":"TEST"
      },
      {
         "productId":"amzn1.adg.product.a4115c2d-7794-486d-9d03-61115575d1da",
         "referenceName":"apple_basket",
         "type":"ENTITLEMENT",
         "name":"Apple Basket",
         "summary":"Great apples in the basket",
         "entitled":"NOT_ENTITLED",
         "entitlementReason":"NOT_PURCHASED",
         "purchasable":"PURCHASABLE",
         "activeEntitlementCount":0,
         "purchaseMode":"TEST"
      }
   ],
   "nextToken":null,
   "truncated":false
}

isp.getProduct

isp.getProduct action allows you to get an individual in-skill product by its reference name.

Three parameters are required:

• input: true: Always set this parameter to true.
• reference: The reference name of the product you created.

The result of this action is stored in isp_response variable and contains a JSON object similar to this one:

{
   "productId":"amzn1.adg.product.01321b13-7bcf-4e1b-81cb-31658fd009bb",
   "referenceName":"apple_pie",
   "type":"CONSUMABLE",
   "name":"Apple Pie",
   "summary":"Apple Pie",
   "entitled":"NOT_ENTITLED",
   "entitlementReason":"NOT_PURCHASED",
   "purchasable":"PURCHASABLE",
   "activeEntitlementCount":0,
   "purchaseMode":"TEST"
}

isp.buy

isp.buy action makes a purchase request for the particular in-skill product by its id.

Three parameters are required:

• output: true: Always set this parameter to true.
• productId: A unique product identifier.
• productToken: A token to identify this message exchange and store skill information.

This action results in a special event that is sent by Alexa: ISP.OnBuy

isp.upsell

isp.upsell action asks a question and, when answered positively, makes a purchase request for the particular in-skill product by its id.

Four parameters are required:

• output: true: Always set this parameter to true.
• message: A product suggestion that fits the current user context. Should always end with an explicit confirmation question.
• productId: A unique product identifier.
• productToken: A token to identify this message exchange and store skill information.

This action results in a special event that is sent by Alexa: ISP.OnUpsell

isp.cancel

isp.cancel action makes a refund request for the in-skill product that was already bought by a user.

Three parameters are required:

• output: true: Always set this parameter to true.
• productId: A unique product identifier.
• productToken: A token to identify this message exchange and store skill information.

This action results in a special event that is sent by Alexa: ISP.OnUpsell

ISP Events

ISP events are triggered, when one of the corresponding actions action is fired.

ISP Events are:

• ISP.OnBuy
• ISP.OnUpsell
• ISP.OnCancel

You can put them in your Inital step close to your buil-in Alexa Intents:

    - name: Initial step
      actions:
        - sendText: >
            Welcome to Apple Game! 
            The world's largest virtual bio apple store! 
            Here's what we have today to offer: 
        - isp.getProducts:
            input: true
        - sendText: >
            {% for product in isp_response.inSkillProducts %}
                {{ product.name }}. 
            {% endfor %}
        - sendText: 'What would you like to buy?'
        - getInput:
      next:
        buy_isp_intent: Buy Product Step
        cancel_isp_intent: Cancel Product Step
        ISP.OnUpsell: Upsell Success Check
        ISP.OnBuy: Buy Success Check
        ISP.OnCancel: Cancel Success Check
        AMAZON.CancelIntent: Exit
        AMAZON.StopIntent: Exit
        AMAZON.HelpIntent: Help

These events create a variable purchaseResult that can have one of the following values:

• ACCEPTED
• DECLINED
• ALREADY_PURCHASED
• ERROR

You can use these status codes to make logic decisions in your BotTalk scenarios:

    - name: Buy Success Check
      when: 'purchaseResult != "ACCEPTED"'
      entrypoint: true
      actions:
        - sendText: >
            {% if purchaseResult == 'ACCEPTED' %}
              The transaction was accepted.
            {% elseif purchaseResult == 'DECLINED' %}
              The transaction was declined.
            {% elseif purchaseResult == 'ALREADY_PURCHASED' %}
              You already purchased {{ product_name }}.
            {% elseif purchaseResult == 'ERROR' %}
              There was an error.
            {% else %}
              This should never happen actually.
            {% endif %}
      next:
        else: Upsell Apple Pie

Next Steps

Check out our Tutorials section and learn more about API Calls using BotTalk HTTP Plugin.