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 their contact information, which includes their name, email address and phone number, if the customer has consented. You can then 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 query the Alexa Customer Profile API. The Alexa Customer Profile API obtains 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 device 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.

Before you begin

To protect customer data, any skill that uses customer contact information must meet the requirements listed here. If Amazon determines that your skill violates any of these requirements, we will reject or suspend your submission and notify you using 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. That is, 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 Alexa Customer Profile 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. As such, your skill code should handle missing information gracefully.

How to request customer contact information

To request customer contact information within your skill, follow these steps:

  1. Configure your skill in the developer console to indicate that the skill requires customer contact information. When the customer enables the skill, the customer is prompted, in the Alexa app, to consent to provide the contact information. If the customer chooses to not grant these permissions when enabling your skill, you may request this information, when needed, during invocation by using a permissions card. Ensure your skill handles the situation gracefully if the customer refuses to grant permission to access this information.
  2. Obtain the apiAccessToken from the LaunchRequest that Alexa sends your skill when a customer invokes the skill. Don't store the apiAccessToken, because it expires. Instead, obtain the apiAccessToken fresh from each subsequent request.
  3. Make a request to the correct endpoint that includes the apiAccessToken, as described in Get customer contact information.

Configure the skill to request customer permissions

If you are using the developer console to manage your skill, configure your skill as follows:

  1. Edit your skill in the developer console.
  2. Navigate to the Build > Permissions page in the console.

    Select one or more of the following 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

If you select Full Name, you cannot select Given Name, and vice versa.

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 desired permissions.

Get the API access token

Each request sent to your skill includes an API access token (apiAccessToken) that encapsulates the permissions granted to your skill. You need to retrieve this token and include it in requests for the customer's contact information.

The apiAccessToken is nested in the System object, which is nested in the context object. To see the full body of the request, see Request Format.

{
  "context": {
    "System": {
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.amazonalexa.com",
	  ...
    }
  }
}

Thus: accessToken = this.event.context.System.apiAccessToken

When making the request for the data, include the access token in an Authorization header in this format:

Bearer < ACCESS_TOKEN >

Here, < ACCESS_TOKEN > is the value of the apiAccessToken field from the Alexa request message, as shown in this example:

Authorization: Bearer AxThk...6fnLok

The apiAccessToken is included in all requests to your skill, regardless of whether the user granted your skill the permissions needed to fulfill the request. Therefore, the token might not contain the right set of permissions for your skill to fulfill the request. Your skill can display a special permissions card to ask customers for consent dynamically.

New CardAskForPermissionsConsentCard
InterfaceCardRenderer
Definition{ "type": "AskForPermissionsConsent", "permissions": << list of scope strings >> }
Attributespermissions: this contains a list of scope strings that maps to Alexa permissions. Include only those Alexa permissions that are both needed by your skill and that are declared in your skill metadata in the developer console.

Because apiAccessToken is included in all skill requests, you cannot use the presence of apiAccessToken to determine whether or not you have the needed permissions. Instead, call the API and check the response code. A 403 Forbidden response indicates that your skill doesn't have the permissions. If your skill got a 403 response from the API, then your skill can include the AskForPermissionsConsent card in its response to Alexa. Alexa speaks to the customer, informs them about the card in the Alexa app, and the customer can then decide whether to grant the permissions.

Sample response with permissions card

An in-session interaction can return a response that includes the new AskForPermissionsConsent card.

The permissions values can be as shown in the following table:

Full Namealexa::profile:name:read
Given Name (First Name)alexa::profile:given_name:read
Email Addressalexa::profile:email:read
Phone Numberalexa::profile:mobile_number:read

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"
      ]
    }
  }
}

The permissions value always matches the scope that you declared for the skill on the Build > Permissions page in the developer console.

Use Skill Permission Accepted events in your skill

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

Test the API as you develop your skill

You can do limited testing on the Test page in the developer console, using yourself as the skill user. When you test your skill with the Alexa Simulator, your skill can call the Alexa Customer Profile API and get back 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, open skill_name"), Alexa sends a LaunchRequest to your skill. If the customer has granted the permissions, you can obtain the apiAccessToken from the request.

To test what happens when a customer hasn't provided permissions to your skill, make sure you have not granted, or that you have revoked, contact permissions for your skill in the Alexa app. When you open the skill ("Alexa, open skill_name"), Alexa sends a LaunchRequest to your skill. This request contains the apiAccessToken value, but the apiAccessToken doesn't specify the correct permissions. If your skill passes this token to the Alexa Customer Profile API, the API returns a 403 Forbidden response code.

When a customer enables your skill, this customer is prompted to go to the Alexa app to grant permissions. The voice prompt that your skill provides should describe why the skill needs these permissions. If the customer doesn't consent, your skill can send a Permissions card to the Alexa app (or to the screen if the customer is using an Alexa-enabled device with a screen), to prompt the customer for the permissions required for the intent. Your skill should include a graceful fallback message, if needed, in your code.

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

Sample message to prompt customer to grant permissions through permissions card

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.

Fallback message when customer contact information is not available

When your skill requests the customer's contact information, and the customer grants it, this information might still be unavailable, such as if a customer hasn't provided phone number to Amazon. If the requested customer information is unavailable, the API returns a 204 (no content) response.

In this situation, if your skill cannot fulfill the request without some piece of information, you may prompt the user to enter this information in their Amazon.com account.

Sample message if resource_name is unavailable

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.

Suggested best practices when customer contact information is unavailable

As a skill developer, you can determine the appropriate response when the customer hasn't set up contact information.

You can provide a graceful fallback message that indicates the skill cannot 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 compared to having the requested information.

For a good customer experience, ensure that you consider the skill workflow for all the scenarios in which you fail to get the desired information.

Base URIs and geographic location of the skill

The endpoint for the Alexa Customer Profile API varies depending on the geographic location of your skill. As shown in this JSON snippet, you can get the correct base URL to use from the apiEndpoint value in the System object: context.System.apiEndpoint.

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.<skill-id>"
      },
      "user": {},
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {}
}

The examples in this document use the US endpoint api.amazonalexa.com.

For more about configuring your skill for multiple languages, see Develop Skills in Multiple Languages.

Get customer contact information

Use the following endpoints to get the customer contact information (note that these are literal strings). The endpoints are case-sensitive.

Full Name/v2/accounts/~current/settings/Profile.name
Given Name/v2/accounts/~current/settings/Profile.givenName
Email Address/v2/accounts/~current/settings/Profile.email
Phone Number/v2/accounts/~current/settings/Profile.mobileNumber

Request example

Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer MQEWY...6fnLok
GET https://api.amazonalexa.com/v2/accounts/~current/settings/Profile.name
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer MQEWY...6fnLok
GET https://api.amazonalexa.com/v2/accounts/~current/settings/Profile.mobileNumber

Request headers

Header Description Type Required
Authorization A current access token in the format: Bearer your access token string yes

Response example

Header

Host: api.amazonalexa.com
X-Amzn-RequestId: xxxx-xxx-xxx
Content-Type: application/json

Body

{
  "countryCode" : "+1",
  "phoneNumber" : "999-999-9999"
}

The following is a list of return types (all JSON values).

Full Name"string"
Given Name"string"
Email Address"string"
Phone Number{ "countryCode": "string", "phoneNumber": "string" }

The (mobile) phone number is a combination of countryCode and phoneNumber. The phoneNumber might additionally contain the countryCode, and is not guaranteed to be just the local part of the phone number. By itself, the phoneNumber value should be a valid number for dialing.

Thus, the phone number may be in one of a variety of different formats. Some examples include: +917799827710, 7799827710, +91 7799 82 77 11, +91 7799-82-77-11. For just the country code, some possible formats include: +1, 001, 1.

Response headers

Header Description
Content-Type application/json
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

Possible responses

Response Description
200 OK Successfully retrieved the requested information.
204 No Content The query did not return any results.
401 Unauthorized The authentication token is malformed or invalid.
403 Unauthorized The authentication token doesn't have access to the resource.
429 Too Many Requests The skill has been throttled due to an excessive number of requests.
500 Internal Error An unexpected error occurred.

Was this page helpful?

Last updated: Jan 26, 2024