Amazon Bedrock AI Connector Setup Guide

Supported models

The Amazon Bedrock AI connector supports a wide range of foundation models. For the current list of supported models, see Amazon Bedrock: Supported foundation models in Amazon Bedrock.

Some Bedrock models require provisioned throughput and cannot be invoked using on-demand inference. If you encounter an on-demand throughput error, use a model that supports ON_DEMAND inference or provide a provisioned throughput or inference profile ARN in the configuration list.

Create IAM roles and permissions

Tealium requires IAM roles and permissions in your AWS account to connect to Amazon Bedrock from your server-side connector. You have two options for authenticating the connection:

• Provide an Access Key and Access Secret.
• Provide STS credentials.

Access key and secret credentials

To create your AWS access key and secret:

1. Log in to the AWS Management Console and go to the IAM (Identity and Access Management) service.
2. Click Users and then click Add user.
3. Enter a username. For example, TealiumBedrockUser.
4. Attach policies to the user. For more information, see Attach policies.
5. Create the keys.
   • Go to the Security credentials tab and click Create Access Key.
   • Copy the Access Key ID and Secret Access Key, and save them securely.

STS credentials

To create your STS credentials:

1. Log in to the AWS Management Console and go to the IAM (Identity and Access Management) service.
2. Click Roles, and then click Create role.
3. Under Trusted entity type, select the AWS account.
4. Select Another AWS account and enter the Tealium account ID: 757913464184.
5. (Optional) Select the Require external ID checkbox and specify the external ID that you want to use. External IDs can be up to 256 characters long and can include alphanumeric characters (A-Z, a-z, 0-9) and symbols, such as hyphens (-), underscores (_), and periods (.).
6. Enter a name for the role. The role name must start with TealiumBedrock. For example: TealiumBedrock-RoleName.
7. Attach policies to the role. For more information, see Attach policies.
8. Create a trust policy.
   • Go to the Trust relationships tab and click Edit trust relationship.
   • Ensure that the trust policy allows the specific external ID to use the role you created and that the Tealium production account ID is 757913464184.
   • Set the EXTERNAL_ID value for the connection to Tealium. The ID can be up to 256 characters long and can include alphanumeric characters (A-Z, a-z, 0-9) and symbols, such as hyphens (-), underscores (_), and periods (.).

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::757913464184:root"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "EXTERNAL_ID"
            }
          }
        }
      ]
    }

Attach policies

In the AWS Management Console, enter the necessary policies for the connector actions you are using. The following policies are required for each connector action:

We recommend that you limit permissions to the specific ARNs of flows and Lambda functions you require.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListModels",
      "Effect": "Allow",
      "Action": [
        "bedrock:ListFoundationModels"
      ],
      "Resource": "*"
    },
    {
      "Sid": "InvokeModel",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RenderManagedPrompt",
      "Effect": "Allow",
      "Action": [
        "bedrock:RenderPrompt"
      ],
      "Resource": "*"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockFlowInvoke",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeFlow"
      ],
      "Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:flow/<flow_id>/alias/<alias_name>"
    },
    {
      "Sid": "LambdaInvokeFunction",
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeFunction"
      ],
      "Resource": "arn:aws:lambda:<REGION>:<ACCOUNT_ID>:function:<FUNCTION_NAME>"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockFlowInvoke",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeFlow"
      ],
      "Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:flow/<flow_id>/alias/<alias_name>"
    }
  ]
}

To enter and attach the policies:

1. In the AWS console, go to IAM > Policies.
2. Click Create policy.
3. In the policy editor, select the JSON tab.
4. Paste the policy for your connector action into the editor.
5. Resolve any validation warnings, then click Next.
6. Give it a policy name (for example, TealiumCustomAccessPolicy) and optional description.
7. Click Create policy.
8. Go to Roles.
9. Click the role name you want to modify.
10. On the Permissions tab, click Add permissions > Attach policies
11. In the search box, enter the name of your new custom policy.
12. Select the box next to that policy.
13. Click Attach policies.

Configuration

Go to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.

After adding the connector, configure the following settings:

• Authentication Type: (Required) The type of authentication to use.
  • Access Key
    • Access Key: (Required) Provide your IAM user’s access key. The associated IAM policy (for either IAM user or Assumed Role) must grant bedrock:PutRecord permission along with streams you want to send data to.
    • Secret Key: (Required) Provide your IAM user’s secret key.
  • STS
    • STS - Assume Role: ARN: (Required) An Amazon Resource Name assigned to the role to assume. For more information, see: AWS: Switching to an IAM Role.
    • STS - Assume Role: Session Name: (Required) A unique identifier of the assumed role session.
    • STS - Assume Role: External ID: (Optional) A unique identifier used by third parties when assuming roles in their customers’ accounts. For more information, see: AWS: Access to AWS accounts owned by third parties.
• Region: (Required) Select a region.

Prompt information

A Bedrock AI prompt, whether sent from Tealium, managed within Amazon Bedrock, or used in a flow, must be authored to return only valid JSON for Tealium to correctly process the response. Use the following guidelines:

• Use double curly braces to reference mapped parameters, for example: {{tealium_account}}, {{tealium_profile}}, {{tealium_visitor_id}}, {{visitor_json}}.
• Clearly instruct the model to return only valid JSON with no explanations, no markdown, no code fences, and no extra text before or after the JSON.
• Define the exact JSON structure you expect (field names, required keys, and value types) so the output can be parsed safely.
• Instruct the model to return Tealium fields explicitly (for example, tealium_account, tealium_profile, tealium_visitor_id, tealium_event).
• If you need to reference a specific attribute in the prompt, map that attribute to a vendor parameter. For example, map Last product viewed to last_product_viewed and reference it in the prompt as {{last_product_viewed}}.
• Avoid vague instructions. Write deterministic prompts so that repeated calls produce the same JSON schema.
• For best results, include a line such as: “Return a single JSON object only, with no prose, no backticks, and no additional formatting.”

Prompt example

You are an AI assistant that must return only valid JSON.
Do not include explanations, markdown, code fences, or any text outside the JSON object.

Using the visitor data below, calculate a numeric score between 0 and 100 that represents
the visitor's likelihood to convert in this session.

Return a single JSON object only, with this exact structure:

{
  "tealium_account": "{{tealium_account}}",
  "tealium_profile": "{{tealium_profile}}",
  "tealium_visitor_id": "{{tealium_visitor_id}}",
  "tealium_event": "bedrock_ai_insight",
  "visitor_score": <integer between 0 and 100>
}

Visitor data:
{{visitor_json}}

Pay particular attention to the value of {{last_product_viewed}}.

The response will resemble the following:

{
    "metrics": {
        "latencyMs": 1272
    },
    "output": {
        "message": {
            "content": [
                {
                    "text": "{\"tealium_account\":\"your-account\",\"tealium_profile\":\"main\",\"tealium_visitor_id\":\"__your-account_main__5574_438850__\",\"tealium_event\":\"bedrock_ai_insight\",\"visitor_score\":85}"
                }
            ],
            "role": "assistant"
        }
    },
    "stopReason": "end_turn",
    "usage": {
        "inputTokens": 8811,
        "outputTokens": 65,
        "serverToolUsage": {},
        "totalTokens": 8876
    }
}

The connector accepts the response and sends the JSON event object to the Tealium Collect API endpoint.

Amazon Bedrock Flows

Amazon Bedrock Flows are multi-step AI orchestrations that combine prompts, knowledge bases, Lambda functions, conditional logic, and external data into a single reusable workflow. A flow defines how input data moves through prompts, enrichment steps, business logic, and final output to turn complex AI decisioning into a single API endpoint.

To use the Send Data to Bedrock Flow action, create a flow in Amazon Bedrock that accepts input from Tealium, processes it through your AI steps, and sends the results back to Tealium through a Lambda function.

The sections below describe the required and optional components of a flow.

Step 1 - Define the flow input

Every flow begins with an input node. This node represents the JSON document Tealium sends to the flow.

Tealium sends your mapped attributes in the following format similar to the following example:

"document": {
    "tealium_account": "services-example",
    "tealium_profile": "ai",
    "tealium_visitor_id": "1234567890abc",
    "visitor_profile": {
        "lifetime_value": "1200",
        "total_orders": 5,
        ...
        }
}

Inside your flow, reference fields using $.data.attribute_name. Based on the previous example:

Step 2 - Map data into a prompt node (Required)

Next, add a prompt node to generate AI output (such as a score, recommendation, or decision).

Inside the prompt node:

1. Set your prompt text.
2. Insert variables using the {{fieldname}} format. For example, {{tealium_account}}.
3. Choose a Bedrock model.
4. Return valid JSON as the output of the prompt.

For an example, see the Prompt example section above.

Step 3 - (Optional) Add knowledge base retrieval

Amazon Bedrock Knowledge Bases let you connect your AI workflows to external data sources, such as Amazon S3, Amazon Redshift, or Amazon OpenSearch Service. A knowledge base stores and indexes your documents, making them available for retrieval and grounding during prompt execution. When you add a knowledge base node to your flow, the model can use relevant information from your data to generate more accurate and context-aware responses. This step is optional, but it is valuable for personalization, recommendations, or contextual decisioning.

After you connect the knowledge base, you can pass knowledge base results into your prompt using fields like {{$.kbResults}}.

For more information on knowledge bases, see Amazon Bedrock: Retrieve data and generate AI responses with Amazon Bedrock Knowledge Bases.

For more information on creating a knowledge base, see Amazon Bedrock: Create a knowledge base by connecting to a data source in Amazon Bedrock Knowledge Bases.

Step 4 - Add a Lambda node to send results back to Tealium (Required for Tealium Integration)

After your prompt produces structured JSON, you must send that result back into Tealium for profile enrichment.

Add a Lambda node that:

• Receives the prompt output ($.data from your prompt node).
• Parses the JSON.
• Posts it to Tealium Collect: POST https://collect.tealiumiq.com/event.
• Includes the following:
  • tealium_account
  • tealium_profile
  • tealium_visitor_id
  • tealium_event (user-defined)
  • Your AI output fields (for example, visitor_score)

Use our provided Lambda example or build your own.

Step 5 - Add a flow output node

Although Tealium does not process the flow’s API response, an output node is required to complete the flow.

Connecting your Lambda output to the FlowOutputNode doesn’t affect Tealium processing, but helps you verify that the flow works with the following tools:

• Debug in the Bedrock console.
• View errors from the Lambda function.
• Inspect final JSON results for validation.
• View output in Tealium using Trace.

Lambda example

The following is a Lambda example for accepting prompt output, parsing the JSON, and sending that data to the Tealium Collect endpoint for enrichment and activation in Tealium. It includes fallbacks to account for various data structures. Rewrite yours as needed.

The account and profile must be configured to accept server-side events with the specified data source.

This example requires Node.js version 18.x or later as the runtime environment.

const COLLECT_URL = process.env.COLLECT_URL || "https://collect.tealiumiq.com/event";
function extractInputByName(event, name) {
  const arr = event?.node?.inputs;
  if (Array.isArray(arr)) {
    const hit = arr.find(i => i?.name === name);
    if (hit && typeof hit.value === "string") return hit.value;
    if (hit && typeof hit.value === "object") return JSON.stringify(hit.value);
  }
  return undefined;
}
function extractJsonStringFromEvent(event) {
  const fromStandardPin = extractInputByName(event, "codeHookInput");
  if (typeof fromStandardPin === "string") return fromStandardPin;
  const anyString = event?.node?.inputs?.find?.(i => typeof i?.value === "string")?.value;
  if (typeof anyString === "string") return anyString;
  if (typeof event?.codeHookInput === "string") return event.codeHookInput;
  if (typeof event?.document === "string") return event.document;
  const doc = event?.fields?.[0]?.content?.document;
  if (typeof doc === "string") return doc;
  if (typeof event === "string") return event;
  throw new Error("Could not find JSON string in event");
}
export const handler = async (event) => {
  try {
    const jsonStr = extractJsonStringFromEvent(event);
    const obj = JSON.parse(jsonStr);  // Fixed: store parsed result
    const required = ["tealium_account", "tealium_profile", "tealium_visitor_id"];
    for (const key of required) {
      if (!Object.prototype.hasOwnProperty.call(obj, key)) {
        throw new Error(`Missing required field '${key}' in model output`);
      }
    }
    const r = await fetch(COLLECT_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: jsonStr
    });
    if (!r.ok) {
      const txt = await r.text().catch(() => "");
      throw new Error(`Collect failed ${r.status}: ${txt}`);
    }
    return jsonStr;
  } catch (err) {
    console.error("Shim error:", err);
    return JSON.stringify({ ok: false, error: String(err.message || err) });
  }
};

Actions

The following section describes how to set up parameters and options for each action.

Send Prompt to Bedrock AI Model

Parameters

Send Data to Bedrock AI Managed Prompt

Send Data to Bedrock AI Flow

Common errors and troubleshooting

The following are common error codes and resolutions:

Common AWS error codes:

• AccessDeniedException or NotAuthorized
  Your IAM user or role doesn’t have the required permissions (for example, bedrock:InvokeModel, bedrock:RenderPrompt, bedrock:InvokeFlow, bedrock:ListFoundationModels).
  To solve this, update the IAM policy attached to the role or access keys to include the needed Bedrock actions on the correct resources.

• InvalidClientTokenId, UnrecognizedClientException, or ExpiredTokenException
  The configured access keys or STS session are invalid or expired.
  To solve this, rotate and re‑enter credentials in the connector, or verify the STS role and external ID are correct and not expired.

• OptInRequired or FTUFormNotFilled
  The AWS account is not fully enabled for Bedrock or for a specific model (for example, Anthropic).
  To solve this, complete the required Bedrock enablement steps and any model‑specific forms or Marketplace subscriptions in the AWS console.

If you see any of these errors, resolve the IAM or account setup in AWS first. Retrying the connector action alone will not succeed until permissions are corrected.

Common errors from Bedrock API calls

The following errors mean the request reached Bedrock, but the service or model could not complete it successfully.

• ValidationException or ValidationError
  The request body or parameters are invalid for the target model or API (for example, wrong model ID, unsupported parameters, input too large).
  To solve this, verify the model ID / prompt ARN / flow ARN, ensure the request body matches the model’s expected schema, and reduce prompt size or max tokens if needed.

• ResourceNotFound or ResourceNotFoundException
  The specified model, prompt version, or Flow alias ARN does not exist or is not available in that region.
  To solve this, double‑check ARNs and region in the connector configuration against the values shown in the Bedrock console.

• ThrottlingException or ServiceQuotaExceededException
  Your calls exceed Bedrock quotas (for example, TPS or token limits).
  To solve this, reduce call frequency or request a quota increase in AWS.

• ServiceUnavailable, InternalFailure, or InternalServerException
  Temporary or internal errors within Bedrock.
  To solve this, if errors persist, check the AWS Service Health Dashboard or open an AWS Support case.

• ModelErrorException, ModelNotReadyException, or ModelTimeoutException (prompt or managed prompt flows)
  The model failed, is still warming up, or took too long to respond.
  To solve this, wait and retry, simplify the prompt or reduce token usage, and confirm the model or provisioned throughput is fully active.

For all of these errors, Tealium displays the original AWS error message from Bedrock so you can match it against AWS documentation when you are troubleshooting.