Lex via SDK Best Practices

Q: How should I manage sessions across a long conversation?

One sessionId per conversation, a deliberately chosen idleSessionTTLInSeconds, and explicit re-inclusion of sessionAttributes whenever you send a sessionState yourself.

Q: How do I safely ship a bot change to production?

Change DRAFT, rebuild the locale, test against TSTALIASID, then publish a new version and move your prod alias to point at it - never edit a published version in place.

Intent design and fallback-handling for production bots.

This is the checklist to run before shipping a Lex V2 bot built through the SDK. Each item is a rule stated positively with a one-line rationale, grouped from intent/slot design outward through build/publish hygiene, code-hook reliability, session/cost management, and security. Work top to bottom - early groups keep the bot's conversations correct; later ones keep it fast, cheap, and safe.

How to Use This List

Treat each box as an audit question against your own Lex bot and its Lambdas.
Groups run roughly foundation-first: get intent/slot design right, then build/publish discipline, then hook reliability, then session/cost, then security.
Revisit the list whenever you add an intent, a slot type, or a new code hook.
Most rules apply to both text and voice channels; a few (voice-specific TTS/ASR settings) are called out separately.

A - Intent & Slot Design

Design intents around genuinely distinct user goals. Don't cram multiple goals into one intent with branching logic in fulfillment - split them so sample utterances stay unambiguous.
Give each intent varied, realistic sample utterances. A handful of near-identical phrasings under-trains the NLU; include the different ways real users actually phrase the request.
Let AMAZON.FallbackIntent catch the rest. Don't try to enumerate every possible input as an intent - handle the fallback deliberately (clarify, escalate, or hand off) instead of ignoring it.
Prefer built-in slot types before building custom ones. AMAZON.Date, AMAZON.Number, AMAZON.City, and others already handle common data shapes with locale-aware parsing.
Use TopResolution for slot values your code branches on. Normalizing synonyms to a canonical value avoids fragile string matching against raw user text later.
Write clear elicitation prompts for every Required slot. A vague prompt (or none) increases retries and abandonment; tell the user exactly what format you expect.

B - Build & Publish Hygiene

Rebuild the locale after every intent, slot, or slot-type change. BuildBotLocale only ever compiles DRAFT - changes are not testable or live until you rebuild.
Treat published versions as immutable. Ship changes by building a new DRAFT, publishing a new version, and moving the alias - never assume an existing version can change under you.
Move the alias, not client code, to release. Point your channel/application at a stable alias name (like prod) and repoint the alias's botVersion to promote a new release.
Use TSTALIASID for pre-publish testing. It always tracks the current DRAFT, so you can validate changes before cutting a version.
Keep locale, intent, slot, and slot-type identifiers consistent across environments. Drift between dev/staging/prod bot definitions is a common source of "works in one, not the other" bugs.

C - Dialog & Fulfillment Reliability

Keep code hooks well under the 30-second non-streaming ceiling. Lex enforces this regardless of the Lambda's own configured timeout - slow downstream calls will time out the turn.
Set tight timeouts on anything a hook calls. A hook is only as fast as its slowest dependency; don't let one slow API call blow the whole conversation turn.
Start from the incoming sessionState, don't reconstruct it. Modify only what you mean to change in the response; wholesale rebuilding risks silently dropping slots or attributes.
Clear an invalid slot before re-eliciting it. Returning ElicitSlot without nulling the bad value can cause Lex to re-offer it instead of prompting cleanly.
Set intent.state explicitly on every fulfillment path. Distinguish Fulfilled from Failed so your channel and any downstream logging can tell success from failure.
Confirm the Lambda resource-based permission is in place. A missing lambda:InvokeFunction grant for principal lexv2.amazonaws.com scoped to the bot alias is the most common "code hook doesn't fire" cause.

D - Session & Cost Management

Generate one sessionId per conversation and reuse it for every turn. A new sessionId per call resets context and breaks multi-turn dialog.
Always echo back sessionAttributes you want kept. They aren't merged automatically if you send an explicit sessionState - omitted attributes are dropped for the next turn.
Set idleSessionTTLInSeconds deliberately. Too short abandons legitimate slow-paced conversations; too long holds session state (and any PII in it) longer than needed.
Monitor NLU confidence and fallback rate. A rising fallback rate signals missing intents, weak sample utterances, or users asking for something out of scope.
Right-size sample-utterance volume, not intent count, for cost. Lex pricing is driven by request volume, not the number of intents or slot types defined - optimize for reducing wasted/retry requests.

E - Security & IAM

Scope the bot's roleArn to least privilege. Grant only what the bot needs (conversation logging, invoking its specific fulfillment Lambdas), not broad service access.
Grant Lex's Lambda invoke permission per-alias, not account-wide. Scope the resource-based Lambda permission's source ARN to the specific bot alias that should be able to invoke it.
Avoid logging raw user utterances and slot values by default. Conversation content can carry PII; log intent names, slot names, and confidence scores instead unless you have a clear data-handling policy.
Enable conversation logs deliberately, with retention in mind. Text/audio logging is opt-in and useful for debugging NLU quality, but treat the log destination with the same care as any PII store.
Separate build-time and runtime IAM permissions. lexv2-models (managing bots) and lexv2-runtime (running conversations) are different permission sets - don't grant runtime callers management access they don't need.

FAQs

What's the single most common reason a code hook doesn't fire?

A missing resource-based Lambda permission - Lex needs explicit lambda:InvokeFunction access for principal lexv2.amazonaws.com scoped to the bot alias, separate from wiring the ARN into botAliasLocaleSettings.

How do I keep fulfillment fast and reliable?

Keep the hook well under the 30-second non-streaming ceiling, set tight timeouts on anything it calls, and always set intent.state explicitly so success and failure are distinguishable downstream.

Why is my bot falling back to AMAZON.FallbackIntent too often?

Usually thin or narrow sample utterances, or genuinely out-of-scope requests. Add more varied phrasing to existing intents first, and treat a persistently high fallback rate as a signal to review intent coverage.

How should I manage sessions across a long conversation?

One sessionId per conversation, a deliberately chosen idleSessionTTLInSeconds, and explicit re-inclusion of sessionAttributes whenever you send a sessionState yourself.

Should I log full user utterances?

Be careful - they can contain PII. Log intent names, slot names, and confidence scores by default; enable full conversation logging only deliberately, with retention and access controls in mind.

How do I safely ship a bot change to production?

Change DRAFT, rebuild the locale, test against TSTALIASID, then publish a new version and move your prod alias to point at it - never edit a published version in place.

What's the biggest design mistake to avoid?

Cramming multiple distinct user goals into one intent with internal branching. Split them into separate intents with their own sample utterances - it keeps NLU matching accurate and fulfillment logic simple.

Lex's Intent-and-Slot Conversation Model - the design principles behind group A.
Intents, Slots & Slot Types - the schema details behind groups A and B.
Lambda Fulfillment & Dialog Hooks - the reliability rules in group C.
Runtime Conversation Handling - the session mechanics behind group D.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Lex via SDK Best Practices

Intent design and fallback-handling for production bots.

How to Use This List

Treat each box as an audit question against your own Lex bot and its Lambdas.
Groups run roughly foundation-first: get intent/slot design right, then build/publish discipline, then hook reliability, then session/cost, then security.
Revisit the list whenever you add an intent, a slot type, or a new code hook.
Most rules apply to both text and voice channels; a few (voice-specific TTS/ASR settings) are called out separately.

A - Intent & Slot Design

Design intents around genuinely distinct user goals. Don't cram multiple goals into one intent with branching logic in fulfillment - split them so sample utterances stay unambiguous.
Give each intent varied, realistic sample utterances. A handful of near-identical phrasings under-trains the NLU; include the different ways real users actually phrase the request.
Let AMAZON.FallbackIntent catch the rest. Don't try to enumerate every possible input as an intent - handle the fallback deliberately (clarify, escalate, or hand off) instead of ignoring it.
Prefer built-in slot types before building custom ones. AMAZON.Date, AMAZON.Number, AMAZON.City, and others already handle common data shapes with locale-aware parsing.
Use TopResolution for slot values your code branches on. Normalizing synonyms to a canonical value avoids fragile string matching against raw user text later.
Write clear elicitation prompts for every Required slot. A vague prompt (or none) increases retries and abandonment; tell the user exactly what format you expect.

B - Build & Publish Hygiene

Rebuild the locale after every intent, slot, or slot-type change. BuildBotLocale only ever compiles DRAFT - changes are not testable or live until you rebuild.
Treat published versions as immutable. Ship changes by building a new DRAFT, publishing a new version, and moving the alias - never assume an existing version can change under you.
Move the alias, not client code, to release. Point your channel/application at a stable alias name (like prod) and repoint the alias's botVersion to promote a new release.
Use TSTALIASID for pre-publish testing. It always tracks the current DRAFT, so you can validate changes before cutting a version.
Keep locale, intent, slot, and slot-type identifiers consistent across environments. Drift between dev/staging/prod bot definitions is a common source of "works in one, not the other" bugs.

C - Dialog & Fulfillment Reliability

Keep code hooks well under the 30-second non-streaming ceiling. Lex enforces this regardless of the Lambda's own configured timeout - slow downstream calls will time out the turn.
Set tight timeouts on anything a hook calls. A hook is only as fast as its slowest dependency; don't let one slow API call blow the whole conversation turn.
Start from the incoming sessionState, don't reconstruct it. Modify only what you mean to change in the response; wholesale rebuilding risks silently dropping slots or attributes.
Clear an invalid slot before re-eliciting it. Returning ElicitSlot without nulling the bad value can cause Lex to re-offer it instead of prompting cleanly.
Set intent.state explicitly on every fulfillment path. Distinguish Fulfilled from Failed so your channel and any downstream logging can tell success from failure.
Confirm the Lambda resource-based permission is in place. A missing lambda:InvokeFunction grant for principal lexv2.amazonaws.com scoped to the bot alias is the most common "code hook doesn't fire" cause.

D - Session & Cost Management

Generate one sessionId per conversation and reuse it for every turn. A new sessionId per call resets context and breaks multi-turn dialog.
Always echo back sessionAttributes you want kept. They aren't merged automatically if you send an explicit sessionState - omitted attributes are dropped for the next turn.
Set idleSessionTTLInSeconds deliberately. Too short abandons legitimate slow-paced conversations; too long holds session state (and any PII in it) longer than needed.
Monitor NLU confidence and fallback rate. A rising fallback rate signals missing intents, weak sample utterances, or users asking for something out of scope.
Right-size sample-utterance volume, not intent count, for cost. Lex pricing is driven by request volume, not the number of intents or slot types defined - optimize for reducing wasted/retry requests.

E - Security & IAM

Scope the bot's roleArn to least privilege. Grant only what the bot needs (conversation logging, invoking its specific fulfillment Lambdas), not broad service access.
Grant Lex's Lambda invoke permission per-alias, not account-wide. Scope the resource-based Lambda permission's source ARN to the specific bot alias that should be able to invoke it.
Avoid logging raw user utterances and slot values by default. Conversation content can carry PII; log intent names, slot names, and confidence scores instead unless you have a clear data-handling policy.
Enable conversation logs deliberately, with retention in mind. Text/audio logging is opt-in and useful for debugging NLU quality, but treat the log destination with the same care as any PII store.
Separate build-time and runtime IAM permissions. lexv2-models (managing bots) and lexv2-runtime (running conversations) are different permission sets - don't grant runtime callers management access they don't need.

FAQs

What's the single most common reason a code hook doesn't fire?

How do I keep fulfillment fast and reliable?

Keep the hook well under the 30-second non-streaming ceiling, set tight timeouts on anything it calls, and always set intent.state explicitly so success and failure are distinguishable downstream.

Why is my bot falling back to AMAZON.FallbackIntent too often?

How should I manage sessions across a long conversation?

One sessionId per conversation, a deliberately chosen idleSessionTTLInSeconds, and explicit re-inclusion of sessionAttributes whenever you send a sessionState yourself.

Should I log full user utterances?

Be careful - they can contain PII. Log intent names, slot names, and confidence scores by default; enable full conversation logging only deliberately, with retention and access controls in mind.

How do I safely ship a bot change to production?

Change DRAFT, rebuild the locale, test against TSTALIASID, then publish a new version and move your prod alias to point at it - never edit a published version in place.

What's the biggest design mistake to avoid?

Lex's Intent-and-Slot Conversation Model - the design principles behind group A.
Intents, Slots & Slot Types - the schema details behind groups A and B.
Lambda Fulfillment & Dialog Hooks - the reliability rules in group C.
Runtime Conversation Handling - the session mechanics behind group D.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Lex via SDK Best Practices

Search Documentation

Lex via SDK Best Practices