Driver Amazon Alexa Laravel Package

Getting Started

• Install both layers: composer require botman/botman botman/driver-amazon-alexa. Pin versions and commit composer.lock — the Alexa driver's last release was 2018, so Composer resolution against a current BotMan 2.x is the first thing to validate in a throwaway branch.
• Look first at vendor/botman/driver-amazon-alexa/src/. There is effectively no documentation; the driver class, its service provider, and the code that builds the response envelope are the spec. Read matchesRequest(), getMessages(), and reply()/sendRequest() to learn exactly what Alexa JSON becomes a BotMan message and what your reply() becomes.
• Register the driver: modern Laravel auto-discovers the package service provider. On older setups, add BotMan\Drivers\AmazonAlexa\AmazonAlexaServiceProvider::class to config/app.php (verify the exact class name in src/) and publish BotMan's own config if you haven't.
• Expose a POST endpoint the skill can reach. routes/api.php is the cleanest option (remember the /api prefix when you paste the URL into the Alexa console), or a plain route added to VerifyCsrfToken::$except. The handler is thin:

Route::post('/alexa', function () {
    app('botman')->listen();
});

• Point the skill's custom endpoint at that HTTPS URL. Alexa requires port 443 with a publicly trusted certificate; use ngrok or similar for local development, then test from the Alexa Developer Console "Test" tab.
• First use case — a single HelloIntent end to end. The driver converts an IntentRequest into a BotMan message keyed by the intent name (confirm with a payload dump before writing many handlers), so:

$bot->hears('HelloIntent', function (BotMan $bot) {
    $bot->reply('Hello from Alexa.');
});

• Before calling it working, add handlers for AMAZON.HelpIntent, AMAZON.StopIntent, AMAZON.CancelIntent, and a $bot->fallback(), and send a hand-written sample request with curl so you can see the exact JSON envelope the driver returns.

Implementation Patterns

• One handler per intent, with names mirrored from the interaction model in the Alexa console. Treat the console's intent schema as the source of truth; keep intent names in a constants file so PHP and the model can't drift.
• Slots do not arrive in the message text. Read them from the payload:

$payload = $bot->getMessage()->getPayload();
$city = $payload['request']['intent']['slots']['city']['value'] ?? null;

Wrap extraction in one helper — every handler otherwise ends up littered with null checks.

• Multi-turn dialogs: BotMan ask() and Conversations do work, but conversation state lives in BotMan's cache, not in Alexa's session.attributes. Configure a shared cache (Redis or database) and confirm the conversation key is stable across separate Alexa invocations. This is the single most important thing for slot-filling-style flows.
• Launch and lifecycle requests: handle LaunchRequest and SessionEndedRequest by checking request.type in the payload rather than assuming they become hears()-able messages. Always register the built-in intents — unhandled ones drop into fallback, which is rarely what you want.
• Keep handlers thin. BotMan middleware ($bot->middleware(...)) is the right place for logging the raw request, validating the app ID, and normalizing slots. Intent handlers should contain business logic and reply()/ask() only.
• Channel reuse is the main payoff. Write conversations once and let the driver adapt them; where behavior must differ, branch on $bot->getDriver()->getName() or on payload keys rather than splitting the whole conversation.
• Richer Alexa responses: the default output is plain-text outputSpeech. SSML, cards, reprompts, and directives require overriding the response-building code or post-processing the returned JSON, including setting shouldEndSession and reprompt yourself. Put that shaping behind a small helper so handlers stay readable.
• Testing: keep a fixture directory of real requests (Launch, Intent with slots, Help, SessionEnded) and exercise the route with them in feature tests. Given the package's age, this is the fastest regression net you'll have.
• Escape hatch: if the driver blocks you, replace it with a plain controller that parses the Alexa JSON, calls BotMan, and builds the response manually. It is a small amount of code and removes the dependency risk entirely.

Gotchas and Tips

• Stale package: last release 2018, 15 stars, no real docs. Treat it as unmaintained. Pin versions, re-read the source before any BotMan upgrade, and budget for forking if BotMan 2.x changes break it. New Alexa features will not arrive for free.
• Response deadline: Alexa expects a response in roughly 8 seconds. Slow database or API calls inside a handler surface as "the skill returned an invalid response". Keep handlers fast and push heavy work off the request path.
• Signature verification is your job. Amazon signs requests and expects validation of SignatureCertChainUrl, Signature, the timestamp, and the skill's app ID from session.application.applicationId. The driver does not do this; add middleware. It is mandatory for a published skill.
• CSRF and paths: Laravel 419s the Alexa POST unless the route is CSRF-exempt or in the API group. Double-check the exact public path (/api/alexa versus /alexa) before pasting it into the console.
• HTTPS only, port 443, trusted certificate. No self-signed certs; the console fails quietly on a misconfigured endpoint.
• hears() is regex-based. Intent names containing . (such as AMAZON.HelpIntent) and other regex metacharacters should be escaped (AMAZON\\.HelpIntent) or matched deliberately, otherwise you get loose or surprising matches. Always register a fallback.
• Session state is the classic failure mode. If BotMan's cache is not shared, or the conversation key changes between requests, ask() conversations restart and users hear the same prompt forever. Reproduce by sending two IntentRequests with the same sessionId/userId.
• shouldEndSession and reprompts: an "ask" reply that returns shouldEndSession: true closes the microphone. Inspect the returned JSON for ask-style replies and add a reprompt whenever you keep the session open.
• Slots may be absent, empty, or carry a confirmation status. Null-check and validate every value; never assume intent.slots exists.
• Debugging: log the raw body before BotMan sees it, and log $bot->getMessage()->getPayload() in middleware. The Alexa console's JSON Editor plus ask simulate/ask dialog show exactly what was sent and what your endpoint returned.
• Don't conflate Alexa session.attributes with BotMan session state. If you need data across turns, store it in BotMan's cache (or your own store keyed by the Alexa userId) and copy values in and out — the driver will not round-trip attributes for you.
• Locale and timezone come from request.locale and request.timestamp; parse them yourself if your responses depend on them.
• Extension points worth knowing: the driver class (register your own for custom response shaping), BotMan middleware (verification, logging, slot normalization), and the conversation cache config. Those three cover most day-to-day needs without forking.
• Account linking: the OAuth token is at context.System.user.accessToken in the payload. Extract it in middleware and hand it to your auth layer rather than digging through payload arrays in handlers.