Request Customer Contact Information for Use in Your Skill

When a customer enables your Alexa skill, your skill can request the customer's permission to access their contact information, such as their name, email address and phone number. If the customer consents, your skill can use this data to support personalized intents to enhance the customer experience without account linking. For example, your skill might use customer contact information to make a reservation at a nearby restaurant and send a confirmation to the customer.

To use this feature, you use the Alexa Customer Profile API to get this information from the active default Alexa profile, which might or might not represent who is speaking to Alexa. To ask for consent to access the contact information of the recognized speaker, use the Person Profile API. For details, see Request Recognized Speaker Contact Information for Use in Your Skill.

For details on how to request address information, see Enhance Your Skill With Address Information.

If you want to enable the user to verbally consent to share their contact information with your skill, see Use Voice-Forward Consent in Your Alexa Skill.

Prerequisites

To protect customer data, any skill that uses customer contact information must meet the following requirements. If Amazon determines that your skill violates any of these requirements, Amazon will reject or suspend your submission and notify you at the email address associated with your developer account.

  • You must include a link to the Privacy Policy that applies to your skill on the Distribution page of the developer console.
  • Your skill must not be a child-directed skill. For details on child-directed skills, see Child-Directed Alexa skills.
  • You must request permission to receive customer contact information only when required to support the features and services provided by your skill. You must use any personal information you request only as permitted by the user and in accordance with your privacy notice and applicable law.
  • You must not use customer information (name, email address, phone number) to link the customer's account in the background. You must not associate an Alexa customer to a customer in your account pool with the same contact information. A customer's Amazon account information is not verified and may be outdated.
  • The skill must call the Customer Profile REST API to get the latest customer information every time the customer invokes the skill with a request that needs this information.

Any of the requested information, such as customer name, email address, or phone number, might not be available to your skill when requested. Your skill code should handle missing information gracefully.

Steps to request customer contact information

To request customer contact information within your skill, perform the following steps:

  1. Configure permissions for contact information.
  2. Request customer contact information.
  3. Request consent for contact information (Optional).
  4. Test as you develop your skill.

Step 1: Configure permissions for contact information

Follow these steps to configure skill permissions in the Alexa developer console.

If you use SMAPI or the Alexa Skills Kit Command Line Interface (ASK CLI) instead of the developer console to manage your skill, edit the skill manifest to request the customer contact permissions. For details about setting permissions in the skill manifest, see permissions.

To configure permission for customer contact information in the Alexa developer console

  1. Navigate back to your skill in the Alexa developer console.
    Or, if you closed the skill page, follow these steps to find your skill.
    1. Sign in to the Alexa developer console.
    2. On the Skills tab, under SKILL NAME, find your skill.
    3. Under ACTIONS, from the drop-down menu in your skill's row, select Edit.
  2. Navigate to Build > TOOLS > Permissions.
  3. Select one or more of the following permissions depending on which customer resources you require for your skill:
    • Customer Name > Full Name
    • Customer Name > Given Name (the customer's first name)
    • Customer Email Address
    • Customer Phone Number

    You can select Full Name or Given Name, but not both.

Step 2: Request contact information

Use the Customer Profile REST API to get the requested customer contact information.

Alexa includes the context.System.apiAccessToken on all requests to your skill, regardless of whether the user granted your skill the permissions needed to fulfill the request for customer contact information. Therefore, you can't use the presence of apiAccessToken to determine whether you have the necessary permissions to obtain the contact information. Instead, include the apiAccessToken value in the API request and check the response code. An HTTP 403 Forbidden response indicates that your skill doesn't have the necessary permissions. Make sure that your skill handles the situation gracefully if the customer refuses to grant permission to access contact information.

Step 3: Request customer consent for contact information (Optional)

When a customer enables a skill that requires customer permissions, the Alexa app prompts the customer to consent to provide the requested permissions. If the customer chooses not to grant these permissions during skill enablement, your skill can send prompt the customer during the skill session for the permissions required for the skill.

You request customer consent by sending a permissions card in the response to Alexa. When you include the AskForPermissionsConsent card in the response, Alexa speaks to the customer to tell them to view the card in the Alexa app or on an Alexa-enabled device with a screen. The voice prompt that your skill provides should describe why the skill needs these permissions. The customer can decide whether to grant the requested permissions.

If possible, you should develop your skill so that some functionality is available without the requested permission and prompt the customer for permissions when needed to fulfill a customer request.

Permission scope

Include the requested permission scope for customer contact information in the permissions card. The permissions value always matches the scope that you declared for the skill on the Build > Permissions page in the developer console.

For details about the permissions card, see Send a card to ask for customer permission.

Permission scope Description

alexa::profile:name:read

Allows your skill to get the full name of the customer.

alexa::profile:given_name:read

Allows your skill to get the given first name of the customer.

alexa::profile:email:read

Allows your skill to get the email address of the customer.

alexa::profile:mobile_number:read

Allows your skill to get the mobile phone number of the customer.

Permissions card example

The following is a sample response for a card with a request for name and phone number.

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
        "alexa::profile:name:read",
        "alexa::profile:mobile_number:read"
      ]
    }
  }
}

Permission events

Use Skill Permission Accepted events in your skill so that your skill is notified when the customer has granted permissions to the skill.

If you want Alexa to notify your skill when the customer grants or revokes permissions, you can subscribe to the following skill events:

  • Skill permission accepted event – Your skill receives this event when a customer accepts permissions the first time, or grants permissions after revoking all the permissions.
  • Skill permission changed event – Your skill receives this event when a customer grants additional permissions to a skill, or revokes the existing permissions from a skill.

Skill permissions events for changing or granting permissions always include the most recently accepted permissions in the payload. For details about using skill events, see Skill Events in Alexa Skills.

Step 4: Test as you develop your skill

Before you test your skill, read Test and Troubleshoot Personalization.

You can do limited testing on the Test page in the Alexa developer console, using yourself as the skill user. When you test your skill with the Alexa Simulator, your skill can call the Customer Profile API and receive a non-error response that contains your own information. You can also test the flow in which the user doesn't grant permissions.

To test what happens when a customer has provided permissions to your skill, make sure that you have granted the contact permissions for your skill in the Alexa app. When you open the skill, Alexa sends a LaunchRequest with the apiAccessToken that includes the permission.

To test what happens when a customer hasn't provided permissions to your skill, make sure you haven't granted, or that you have revoked, contact permissions for your skill in the Alexa app. When you open the skill, Alexa sends a LaunchRequest with the apiAccessToken value that doesn't specify the correct permissions. If your skill passes this token to the Customer Profile API, the API returns a HTTP 403 Forbidden status code.

Best practices when contact information is unavailable

As a developer, you can determine the appropriate response when your customer doesn't grant permission or doesn't provide customer contact information. You can provide a graceful fallback message that indicates that the skill can't function without this information, and then end the session. Or, you can provide a message that indicates that the skill continues to work, but with reduced functionality.

Keep in mind the following best practices when customer contact information isn't available:

  • If possible, develop your skill so that some functionality is available without the requested permissions.
  • Prompt the customer for permissions only when needed to fulfill a user request. The prompt that your skill provides should describe why the skill needs these permissions.
  • If the customer doesn't consent to share the information and your skill can't continue without it, provide a graceful fallback message that indicates the skill can't function without this information, and end the session. Alternatively, you can provide a message that indicates that the skill will continue to work, but with reduced functionality.
  • Prepare for the situation in which the customer grants consent, but the required information is still unavailable. For example, the customer hasn't provided their mobile number to Amazon. If the requested user information is unavailable, the API returns a HTTP 204 No Content status. In this situation, if your skill can't fulfill the request without some piece of information, you might prompt the user to enter this information.
  • For a good user experience, make sure that you consider the skill workflow for all the scenarios in which you fail to get the desired information.

Sample fallback message when customer doesn't grant requested permissions

The following example shows a prompt to the customer to grant consent to use contact information.

In order to complete this request, {Skill_name} needs access to your {full name/given name/email address/phone number}. Go to the home screen in your Alexa app and grant the permissions to continue.

Afin de répondre à cette demande, {Skill_name} a besoin d'accéder à votre {nom et prénom/prénom/adresse e-mail/numéro de téléphone}. Allez à l'écran d'accueil de votre application Alexa et accordez les autorisations pour continuer.

Um diese Anfrage abzuschließen, benötigt {Skill_name} Zugriff auf {(deinen Vollen Namen/Vornamen) / (deine E-Mail-Adresse/Telefonnummer)}. Um fortzufahren, gehe zum Startbildschirm deiner Alexa-App und gewähre die Berechtigungen.

इस अनुरोध को पूरा करने के लिए, {Skill_name} को आपके {पूर्ण नाम/दिए गए नाम/ईमेल पते/फोन नंबर} तक पहुंच की आवश्यकता है। अपने एलेक्सा ऐप में होम स्क्रीन पर जाएं और जारी रखने की अनुमति दें।

Per completare questa richiesta, {Skill_name} deve accedere al tuo {nome completo/nome/indirizzo email/numero di telefono}. Vai alla schermata iniziale della tua app Alexa e concedi le autorizzazioni per continuare.

このリクエストを完了するには、{スキル名}が{姓名、名前、Eメールアドレス、電話番号}にアクセスする必要があります。続行するにはAlexaアプリのホーム画面でスキルに権限を付与してください。

Para completar esta solicitação, {Skill_name} precisa ter acesso a seu {nome completo/nome próprio/endereço de e-mail/número de telefone}. Vá para a tela inicial em seu aplicativo Alexa e conceda as permissões para continuar.

Para completar esta solicitud, {Skill_name} necesita acceso a tu {nombre completo/nombre de pila/dirección de correo electrónico/número de teléfono}. Ve a la pantalla de inicio en tu aplicación Alexa y otorga los permisos para continuar.

Sample fallback message when customer contact information isn't available

If a customer grants permission but hasn't provided contact information to Amazon, you can prompt the user to enter this information in their Amazon.com account.

The following example shows a prompt to the customer to add information to their account.

Your resource_name was not set. You can enter these details in your Amazon account, and then invoke the skill again.

Votre nom_de_ressource n'a pas été défini. Vous pouvez saisir ces détails dans votre compte Amazon, puis lancer la skill à nouveau.

Dein resource_name wurde nicht festgelegt. Du kannst diese Details in deinem Amazon-Konto eingeben und den Skill dann erneut aufrufen.

आपका resource_name सेट नहीं किया गया था। आप इन विवरणों को अपने Amazon खाते में दर्ज कर सकते हैं, और फिर skill को शुरू कर सकते हैं।

Il tuo resource_name non è stato impostato. Puoi inserire questi dettagli nel tuo account Amazon, quindi invocare nuovamente la skill.

resource_nameが設定されていません。Amazonアカウントでこれらの詳細を入力してから、スキルをもう一度呼び出してください

Seu resource_name não foi definido. Você pode inserir estes detalhes em sua conta Amazon, e depois invocar sua skill novamente.

Su resource_name no está configurado. Puede ingresar estos detalles en su cuenta de Amazon y luego invocar la skill nuevamente.

Was this page helpful?

Last updated: Mar 20, 2024