Alexa Skill (Dispenser)

This page gives a short, practical overview of the Alexa Skill related to Albicchiere dispensers. It is intended for new hires who need to know that the integration exists, what it does at a high level, and where it lives, without diving into implementation details.

What it is

• The Albicchiere Alexa Skill allows users to interact with a dispenser via voice commands on Alexa-enabled devices.
• Typical intents include: checking dispenser status, starting or stopping a pour, and querying errors or maintenance states.

Why it matters

• Provides a hands-free user experience for the dispenser.
• Acts as an additional client of the dispenser backend APIs and device shadows, which means changes in API contracts or event semantics can affect the skill.

Where it lives (current state)

• The skill is hosted and configured in the Alexa Developer Console under the Albicchiere organization account.
• The codebase is maintained in the organizational GitHub account under the repository albicchiere-alexa-skill.
• The skill calls our backend APIs to reach dispenser services.

Note: Access to the Alexa Developer Console and relevant AWS accounts is restricted. Request access via the platform team if needed.

How it connects (high level)

• Alexa receives a voice intent from the user and sends a request to the skill endpoint.
• The skill translates intents to backend calls (e.g., dispenser status, start pour).
• Responses are rendered back to the user as Alexa voice prompts and, where supported, simple visual cards.

Authentication and account linking

• Users link their Alexa account to Albicchiere via Account Linking (OAuth 2.0) integrated with Amazon Cognito.
• On each request, Alexa includes an accessToken; if it is missing or invalid the skill prompts the user to complete linking.
• The skill uses this token to call our APIs on behalf of the user.

Tech stack (high level)

• Alexa SDKs: ask-sdk-core, ask-sdk-model.
• HTTP client: axios for calling Albicchiere APIs.
• i18n: i18next with speech strings in code; current published locale is it-IT. An en catalog exists for development/testing.
• Time handling: dayjs.
• Hosting/infrastructure: ASK Hosted Skill with AWS Lambda endpoints configured per region (EU/NA/FE).

Operational notes

• Environments: There are distinct development and production configurations in the Alexa Developer Console.
• Versioning/Publishing: Skill changes go through Alexa certification before they are public. Internal testing can be done in dev accounts or via beta testing.
• Monitoring: Check CloudWatch (or configured logging) for skill-side errors; application-side issues appear in our backend observability stack.

Pointers

• Repository: organizational GitHub → albicchiere-alexa-skill.
• Backend interfaces: refer to this docs/dispensers section for APIs, events, and device shadows used by the skill.
• Credentials & access: follow internal onboarding docs or ask the platform team.

If you need more detail (intent schema, utterances, endpoint configs), reach out to the maintainers or check the Alexa repo README.