What the lookup returns

The one Lambda call the pattern rests on — its parameters, its response, and the three mistakes that cost people an afternoon.

Every DFC read is the same Lambda invocation with a different path. Learn this one block and you can read any DFC-driven flow.

The call

The AWS Lambda function block needs three things set.

Setting Value Why
Function The DFC lookup function for the instance Named per account, so it differs between environments
Parameter path The path to read The only input that matters
Response validation JSON Without it, nothing past the first level of the response is readable

The lookup module builds its path out of the number the caller dialled:

The path parameter, as the module sets itText
/Contact Source/$.Attributes.dfcSource

Amazon Connect substitutes attribute references inside a literal string, so that resolves to /Contact Source/+15550100 before the function sees it. That is worth knowing because it is what lets one flow serve every number you own: the flow does not enumerate them, it asks about whichever one rang.

Chat has no dialled number

A chat contact has no system endpoint, so the module takes a different branch and reads the entry point from an attribute passed in when the chat started. Same lookup, different way of working out the key.

The response

You get back a data object: the item’s fields, with every reference followed and inlined, and every boolean turned into text.

A trimmed responseJSON
{
  "data": {
    "address": "+15550100",
    "enabled": "true",
    "experienceConfig": {
      "name": "US Main Line",
      "enableLanguageSelection": "true",
      "promptSet": {
        "welcome": { "kind": "SSML", "content": "<speak>Thanks for calling.</speak>" }
      },
      "routing": {
        "name": "NA General",
        "queue": {
          "connect_resource": {
            "name": "Demo NA General",
            "arn": "arn:aws:connect:us-west-2:111122223333:instance/a1b2c3/queue/d4e5f6"
          }
        }
      }
    }
  }
}

A flow reads into that with a path expression:

To get Read
The greeting $.External.data.experienceConfig.promptSet.welcome.content
Whether the line is on $.External.data.enabled
The queue to route to $.External.data.experienceConfig.routing.queue.connect_resource.arn
The experience’s name $.External.data.experienceConfig.name

The three mistakes

These are the ones that actually happen.

A miss is not an error

Ask for a path that does not exist and the function returns successfully, with an error code in the body instead of data:

What a miss looks likeJSON
{ "error": "ITEM_NOT_FOUND", "message": "The requested item could not be found." }

The block’s own error branch does not fire, because the invocation succeeded. If the flow does not test for this explicitly it carries on and reads blanks out of a failed lookup, then takes whichever branch a blank leads to. Both provided modules check $.External.error immediately after the call for exactly this reason.

This is the one to remember

A caller hitting an unmapped number should hear “we cannot take your call” and be disconnected politely. Without an error check they get the “this line is switched off” branch instead, or silence, and the flow logs look completely healthy.

Response type left on string map

The response is deeply nested. If the block’s response validation is not set to JSON, everything past the first level reads as empty and the flow behaves as though the configuration were blank. There is no error to see.

A prompt that Amazon Polly rejects

Prompt fields hold SSML, and the voice engine matters. The neural engine does not support every SSML tag — <emphasis> is the common one — and when synthesis fails, Connect plays silence and moves on. No error, no failed branch.

The tell is in the flow log: the prompt block’s start and end share a timestamp, because nothing was actually spoken. Use <prosody> for stress instead, and check a new prompt by listening to it rather than by reading it.

Read the flow log, it tells you everything

Turn on flow logging and every block records what it resolved: the path the Lambda was asked for, the whole response, the exact text of every prompt and the voice used. When a DFC-driven call misbehaves, that log answers the question faster than any amount of staring at the flow.

Try any path yourself

You do not need AWS access or the CLI for this. The Path Tester in DFC calls the same lookup and shows you the same response.

  1. Open the test-tube icon in the DFC toolbar, at the top right of the browser.

  2. Type a path, in the shape the placeholder shows: /entity/sub-entity/item-1.

  3. Run it, and read the response.

That is the fastest way to answer “what will the flow actually get”, and the only way that does not involve either a phone call or a deployment. Use it whenever a field is not arriving in the flow and you want to know whether the problem is the lookup or the flow reading it.

If you do have AWS access

The same thing from a terminal, which is occasionally handy in a script:

aws lambda invoke --function-name <LOOKUP_FUNCTION_NAME> \
  --payload '{"Details":{"Parameters":{"path":"/Contact Source/<NUMBER>","debug":"false"}}}' \
  response.json && python3 -m json.tool response.json

Set debug to true and the response also carries the entity’s schema and the raw item alongside the resolved values.