![\"AI](\"/images/guides/ai-connectors-flow.png\" "\\"AI")
\n \nThis guide explains how to integrate external AI models with Tealium functions for real-time activation. Connect securely to model endpoints, invoke AI predictions using event and visitor data, and enrich visitor profiles with model outputs. It also covers asynchronous responses and common integration issues.
\nFor information on when to use Tealium functions or AI connectors for your use case, see AI connectors and Tealium functions.
\nUse functions to call external AI models for tasks such as churn risk, fraud detection, propensity scoring, or next-best-action recommendations. The function collects event data and visitor profile attributes, builds a payload, sends it to your model endpoint, receives a prediction, and updates the visitor profile for activation.
\nThe data flow for real-time model inference and activation includes the following steps:
\ntrack() method.Because functions cannot directly modify visitor profiles, predictions must flow through Tealium Collect and be written to profiles through enrichments.
\nThe track() method sends events to Tealium Collect. You must configure enrichments to write these event attribute values to visitor profile attributes.
| Function type | \nTrigger | \nSignature | \nUse case | \n
|---|---|---|---|
| Event Function | \nFires after a specific event is processed | \n{ event, helper } | \nScore based on immediate event context (for example, product recommendation on product view) | \n
| Visitor Function | \nFires after a visitor profile is updated | \n{ visitor, visit, helper } | \nScore based on accumulated profile data (for example, churn prediction based on engagement history) | \n
Using functions to call external AI models for real-time inference and activation provides several benefits, such as:
\nBefore you create a function to invoke your AI model, ensure that you have the following:
\nData transformation function
\nEvaluates incoming event data and applies regular expressions to identify behaviors relevant to churn risk.
Derived attribute
\nCalculates a churn risk score from event data. The function sets this value for each event.
AudienceStream event filter
\nFilters events using the churn risk score. Only high-risk events enrich visitor profiles.
Event feed
\nStreams flagged high-risk events for further processing by connectors, storage, or other functions.
External model invocation function
\nSends enriched event or profile data to an external AI model endpoint for advanced churn prediction.
Enrichment
\nWrites AI model predictions to visitor profile attributes for activation and segmentation.
To implement this solution, you need:
\ntrack() eventsYou can implement your AI activation logic using either an event function or a visitor function. Choose the function type that best matches your use case and the data available at the time of scoring.
\n| Object/Method | \nDescription | \n
|---|---|
event.data.udo.* | \nEvent attributes from the triggering event | \n
visitor.properties.* | \nVisitor profile string attributes | \n
visitor.metrics.* | \nVisitor profile numeric attributes | \n
visitor.audiences | \nVisitor audience membership | \n
visitor.current_visit.* | \nVisit attributes from the visitor’s current session | \n
helper.getAuth('name') | \nRetrieve stored authentication token | \n
helper.getGlobalVariable('name') | \nRetrieve stored global variable | \n
track(data, config) | \nSend event to Tealium Collect (max 6 calls per invocation) | \n
The following code examples show a generic REST API pattern. Actual implementations vary by platform:
\n| Platform | \nNotes | \n
|---|---|
| Snowflake Cortex | \nCortex functions are called through SQL statements using the Snowflake SQL API. Requires JWT authentication. | \n
| Databricks Model Serving | \nMLflow models are exposed as REST endpoints. Uses personal access token (PAT) authentication. Supports asynchronous inference through jobs API. | \n
| AWS SageMaker | \nEndpoints require AWS Signature V4 authentication. Consider using a Lambda proxy for simplified authentication. Supports async inference endpoints for long-running jobs. | \n
| Hugging Face | \nInference Endpoints use bearer token authentication. Response format depends on the model type. | \n
| GCP Vertex | \nVertex AI endpoints use OAuth 2.0 or service account authentication. | \n
| Azure | \nAzure ML managed endpoints use API key or Azure AD token authentication. | \n
Refer to your platform’s API documentation for request/response formats and authentication requirements.
\nThe following example shows how to call an external model API from an event function. Adapt the payload structure and response parsing to match your model’s API.
\n\nVisitor functions can access accumulated profile data for scoring. However, visitor functions do not have access to the event object, so you must use global variables for account, profile, and datasource values.
When model inference takes longer than 10 seconds, use an asynchronous pattern. The function sends a request and exits immediately. The model calls back to Tealium when processing completes.
\nCreate an HTTP API data source for receiving model callbacks. For more information, see Create a data source.
\nUse the following function code:
\n\nYour model endpoint should POST to the Tealium HTTP API when inference completes:
\nPOST https://collect.tealiumiq.com/event?tealium_account={account}&tealium_profile={profile}&tealium_datasource={datasource_key}\n\n{\n "tealium_event": "model_prediction_complete",\n "tealium_visitor_id": "original_visitor_id_from_request",\n "churn_score": 0.82,\n "churn_risk_tier": "high",\n "model_version": "v2.1"\n}\nIncluding tealium_visitor_id ensures the prediction stitches to the correct visitor profile. Configure enrichments as described in Step 3 to write these attributes to the profile.
Store your model API credentials and configuration in Tealium functions for secure access.
\nTo store API credentials for a function on the Tealium platform, add an authentication token. In this example, you will store the API key or token endpoint URL as model_api_token. For more information, see Add authentication.
Retrieve the token in your function with the following code:
\n {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer ' + helper.getAuth('model_api_token'),\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify(payload)\n }\nAuthentication tokens can only be referenced by a function within an HTTP request. If you try to reference the token outside of an HTTP request, the token is replaced by a UUID placeholder.
\nStore configuration information for a function such as the model endpoint URL and name as global variables. In this example, you will store the model endpoint URL as MODEL_ENDPOINT_URL. For more information, see Manage global variables.
Retrieve the variable in your function with the following code:
\n const response = await fetch(\n helper.getGlobalVariable('MODEL_ENDPOINT_URL'),\n {\n...\n }\n );\nBefore you can activate predictions in downstream systems, you must configure attributes and enrichments to store and process model outputs in visitor profiles.
\nCreate an attribute to store model predictions in visitor profiles. In this example, create a churn_score number attribute.
For more information, see Create an attribute.
\nEnrich the attribute you created to write model predictions from events to visitor profiles. Without an enrichment, predictions do not appear on visitor profiles. In this example, create an enrichment to write the prediction_score event attribute from your track() call to the churn_score visitor attribute when tealium_event equals model_prediction (or your event name).
For more information, see Add enrichment.
\nUse your prediction attributes to build audiences and trigger actions to activate on churn risk.
\nCreate an audience based on prediction attributes. In this example, create a High Churn Risk audience for visitors with a churn_score greater than 0.7.
For more information, see Create an audience.
\nAttach connector actions to audiences to activate on prediction values. In this example, you can trigger retention emails for high churn risk or add users to remarketing audiences based on purchase intent.
\nFor more information, see Add connector.
\nUse console.log() for debugging:
console.log('Payload:', JSON.stringify(payload));\nconsole.log('Response status:', response.status);\nconsole.log('Result:', JSON.stringify(result));\nTo view logs, click the Logs tab in the functions editor.
\n| Issue | \nSolution | \n
|---|---|
| Function times out | \nEnsure model responds within 10 seconds. Use dedicated or provisioned endpoints. Consider asynchronous model invocation depending on average model response time. | \n
| Predictions not on profiles | \nVerify enrichments are configured. Check tealium_datasource value. | \n
| Authentication errors | \nVerify token value in Auth Tokens. Check token expiration. | \n
track() not executing | \nCheck for errors before track(). Verify data source is active. | \n
Tealium supports two approaches for integrating AI models into real-time data workflows:
\nUse this guide to understand how each approach works and when to use each one.
\nAI connectors integrate with hosted LLM APIs from supported providers and require prompt-based interactions that return structured JSON. They follow a consistent prompt, response, and activation pattern across all supported providers.
\nTo use an AI connector, you need authentication credentials for your provider and at least one configured action that defines a prompt and the Tealium data to send to the AI model.
\nAI connectors are designed for LLM activation only. They are not intended for invoking traditional machine learning models that return numeric scores or tabular predictions. For those use cases, use Tealium functions.
\n\n \nThe prompt instructs the model about the context data to evaluate, asks a specific question, and defines the expected response. Depending on the vendor connector, you may or may not need to include specific instructions about the response output. See the specific connector instructions for details.
\nYou can include specific attributes or the entire event or visitor data object as context in the prompt.
\nTo include specific attributes, map them in the connector action then reference them in the prompt. For example, if you map product_review, you can reference {{product_review}} in your prompt.
To include entire data objects in the prompt, enable Add Event Payload or Add Visitor Profile in the connector action settings, then reference {{event_payload}} or {{visitor_profile}} in your prompt.
For audience actions, you can also enable Add Current Visit to include current visit data within the visitor profile object.
\nImportant
\nIf the connector requires prompt instructions about the context data, include it as the first line of your prompt. For example:
You receive a JSON object describing a customer event:\r\n{{event_payload}}\nIf the connector requires prompt instructions about the response format, include it at the end of the prompt. For example:
\nReturn only a single JSON object on one line with the following structure: \r\n{\r\n "tealium_account": "{{tealium_account}}",\r\n "tealium_profile": "{{tealium_profile}}",\r\n "tealium_visitor_id": "{{tealium_visitor_id}}",\r\n "tealium_event": "ai_response",\r\n "ai_review_sentiment": "<customer review sentiment>"\r\n}\nYour prompt tells the model how to evaluate the data and asks to generate one or more specific values.
\nFor example, this prompt asks to generate a text value representing the sentiment of the customer’s review:
\nBased on the provided product review event, classify the customer's sentiment as one of: "dissatisfied", "neutral", or "satisfied".\nThe connector parses the AI response and extracts a JSON object, which is sent back to Tealium Collect as an event.
\nExample response event:
\n{\n "tealium_account": "acme",\n "tealium_profile": "main",\n "tealium_visitor_id": "383...05d",\n "tealium_event": "ai_response",\n "ai_review_sentiment": "satisfied"\n}\nIn this example, the customer has just submitted a product review and the prompt asks the model to evaluate the sentiment.
\nExample prompt:
\nYou receive a JSON object describing a customer's product review:\r\n{{event_payload}}\r\n\r\nBased on the provided product review event, classify the customer's sentiment as one of: "dissatisfied", "neutral", or "satisfied".\r\n\r\nReturn only a single JSON object on one line with the following structure: \r\n{\r\n "tealium_account": "{{tealium_account}}",\r\n "tealium_profile": "{{tealium_profile}}",\r\n "tealium_visitor_id": "{{tealium_visitor_id}}",\r\n "tealium_event": "ai_response",\r\n "ai_review_sentiment": "<customer review sentiment>"\r\n}\nExample response event:
\n{\n "tealium_account": "acme",\n "tealium_profile": "main",\n "tealium_visitor_id": "383...05d",\n "tealium_event": "ai_response",\n "ai_review_sentiment": "satisfied"\n}\nIn this example, the customer joined an audience named “Frequent Browser, No Purchases” and the prompt asks the model to evaluate the customer’s intent.
\nExample prompt:
\nYou receive a JSON object describing a retail visitor:\r\n{{visitor_profile}}\r\n\r\nBased on the customer data provided, classify their likely shopping intent as: "bargain hunting", "product comparison", "researching for later", or "not interested". If data is missing, make a best effort guess.\r\n\r\nReturn only a single JSON object on one line with the following structure: \r\n{\r\n "tealium_account": "{{tealium_account}}",\r\n "tealium_profile": "{{tealium_profile}}",\r\n "tealium_visitor_id": "{{tealium_visitor_id}}",\r\n "tealium_event": "ai_response",\r\n "ai_shopping_intent": "<customer shopping intent>"\r\n}\nExample response event:
\n{\n "tealium_account": "acme",\n "tealium_profile": "main",\n "tealium_visitor_id": "383...05d",\n "tealium_event": "ai_response",\n "ai_shopping_intent": "bargain hunting"\n}\nIf the model returns a valid JSON object, the connector forwards it to Tealium Collect as an inbound event. Enrichment rules then write the response values to visitor profile attributes. From there, audiences and downstream connectors activate based on the enriched profile.
\nSetting a value for tealium_event that’s unique to the connector and naming the response attribute specific to the use case makes it easy to create event feeds or rules that match these events.
Example rule for AI response event activation:
\nBefore activating an AI connector in production, enable Debug Mode in the connector mappings and test your setup with trace to validate your configuration and prompt behavior. Using debug mode helps catch errors and optimize prompts before incurring production costs or affecting live data.
\nIn debug mode, the connector executes the AI request but logs the result without sending the response event back to your account. Use the trace tool to inspect the full request and response, verify the generated output, and ensure that the trigger conditions and attribute mappings are working as expected.
\nConfiguration details such as authentication, model selection, prompt requirements, and action parameters are specific to each connector.
\nThe following AI connectors are available:
\n\n\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n\n\n\n| Connector | \nDescription | \n
|---|---|
| Amazon Bedrock AI | \nSet up the Amazon Bedrock AI connector to send Tealium event and visitor data to foundation models, managed prompts, or multi-step Bedrock workflows for real-time enrichment. | \n
| Anthropic | \nSet up the Anthropic connector to send a prompt with Tealium event or visitor data and return model responses for real-time enrichment. | \n
| Google Vertex AI | \nSet up the Google Vertex AI connector to invoke Vertex AI models with Tealium event data and return model responses for real-time visitor enrichment. | \n
| Google Vertex AI Search | \nSet up this connector to send Tealium event data to Google Vertex AI Search for personalized and intuitive shopping experiences. | \n
| OpenAI | \nSet up the OpenAI connector to send a prompt with Tealium event or visitor data and return model responses for real-time enrichment. | \n
| OpenAI Events | \nThis article describes how to set up the OpenAI Events connector. | \n
Tealium functions provide a code-based approach for invoking your own model (IYOM). Instead of using a preconfigured connector, you write JavaScript to call any model endpoint directly from an event or visitor function. Use cases include traditional machine learning models returning numeric scores, LLMs hosted on platforms without a dedicated AI connector, and endpoints on data platforms such as Snowflake Cortex, Databricks Model Serving, or Amazon SageMaker.
\nTealium functions support both event functions (triggered after an event is processed) and visitor functions (triggered after a visitor profile updates), allowing you to score either immediate event context or accumulated visitor history.
\nWhen a function fires, it follows these steps:
\nfetch().track().Because functions cannot directly modify visitor profiles, predictions must flow through Tealium Collect and be written to the profile through enrichments.
\nFunctions support both synchronous and asynchronous model invocation. For models that respond within 10 seconds, use a standard await pattern. For slower models, use a fire-and-forget pattern. The function sends the request and exits immediately. The model then POSTs the result to a callback URL when inference completes.
For implementation details, see Create a function for AI activation.
\nAI connectors are designed for use cases that return structured, predictable JSON output, such as classification labels, confidence values, or identifiers from a predefined list. They are not designed for long-form content or media generation. If your use case requires free-form output, align with your organization’s AI governance processes before moving to production.
\nWhen you must remove or tokenize PII before sending data to a model, use Tealium functions to apply custom filtering and send only the approved fields to the endpoint.
\n| Consideration | \nAI connectors | \nTealium functions | \n
|---|---|---|
| Setup | \nConfigure through the UI | \nWrite JavaScript code | \n
| Model types supported | \nLLMs only | \nAny ML or AI model, including traditional ML | \n
| Supported providers | \nSee Supported vendors | \nAny HTTPS endpoint | \n
| Prompt control | \nTemplate-based with variable substitution | \nFully programmable | \n
| Authentication | \nManaged in connector settings | \nStored as authentication tokens in Tealium functions | \n
| Payload structure | \nFixed based on event or visitor data | \nFully customizable | \n
| PII filtering before model call | \nPlatform-level only (consent categories and restricted attributes). No custom pre-processing code inside the connector | \nFully customizable filtering and transformation in JavaScript before calling the model | \n
| Response handling | \nAutomatic JSON parsing and event forwarding | \nCustom parsing in code | \n
| Asynchronous support | \nLimited. The Bedrock AI Workflow action supports asynchronous responses through Lambda callbacks | \nSupported through fire-and-forget pattern and model callbacks to Tealium Collect | \n
The following table lists common AI use cases and the recommended integration approach for each.
\n| Use case | \nDescription | \nRecommended approach | \n
|---|---|---|
| Sentiment analysis | \nClassify customer feedback or review events as positive, neutral, or negative. | \nAI connector | \n
| Intent classification | \nIdentify a customer’s likely intent based on browsing or purchase history. | \nAI connector | \n
| Next-best-action (playbook selection) | \nSelect from a finite set of approved actions or offers based on visitor context. | \nAI connector | \n
| Propensity scoring | \nPredict the likelihood of a conversion, churn, or high-value action using a trained machine learning model. | \nTealium functions | \n
| Next-best-action (score optimization) | \nScore a set of candidate actions using a numeric model and select the highest-scoring one. | \nTealium functions | \n
| Feature store lookup | \nRetrieve pre-calculated scores or features from a data platform for activation. | \nTealium functions | \n
| Custom endpoint inference | \nInvoke a model hosted on a platform without a dedicated AI connector. | \nTealium functions | \n
For an overview of how AI connectors work and guidance on when to use an AI connector or Tealium functions, see AI connectors and Tealium functions.
\nThe 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.
\nSome 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.
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:
\n\nTo create your AWS access key and secret:
\nTealiumBedrockUser.To create your STS credentials:
\n757913464184.A-Z, a-z, 0-9) and symbols, such as hyphens (-), underscores (_), and periods (.).TealiumBedrock. For example: TealiumBedrock-RoleName.757913464184.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 (.). {\n "Version": "2012-10-17",\n "Statement": [\n {\n "Effect": "Allow",\n "Principal": {\n "AWS": "arn:aws:iam::757913464184:root"\n },\n "Action": "sts:AssumeRole",\n "Condition": {\n "StringEquals": {\n "sts:ExternalId": "EXTERNAL_ID"\n }\n }\n }\n ]\n }\nIn the AWS Management Console, enter the necessary policies for the connector actions you are using. The following policies are required for each connector action:
\nWe recommend that you limit permissions to the specific ARNs of flows and Lambda functions you require.
\n\n{\n "Version": "2012-10-17",\n "Statement": [\n {\n "Sid": "ListModels",\n "Effect": "Allow",\n "Action": [\n "bedrock:ListFoundationModels"\n ],\n "Resource": "*"\n },\n {\n "Sid": "InvokeModel",\n "Effect": "Allow",\n "Action": [\n "bedrock:InvokeModel"\n ],\n "Resource": "*"\n }\n ]\n}\n{\n "Version": "2012-10-17",\n "Statement": [\n {\n "Sid": "RenderManagedPrompt",\n "Effect": "Allow",\n "Action": [\n "bedrock:RenderPrompt"\n ],\n "Resource": "*"\n }\n ]\n}\nIf you are using Lambda:
\n{\n "Version": "2012-10-17",\n "Statement": [\n {\n "Sid": "BedrockFlowInvoke",\n "Effect": "Allow",\n "Action": [\n "bedrock:InvokeFlow"\n ],\n "Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:flow/<flow_id>/alias/<alias_name>"\n },\n {\n "Sid": "LambdaInvokeFunction",\n "Effect": "Allow",\n "Action": [\n "lambda:InvokeFunction"\n ],\n "Resource": "arn:aws:lambda:<REGION>:<ACCOUNT_ID>:function:<FUNCTION_NAME>"\n }\n ]\n}\nIf you are not using Lambda:
\n{\n "Version": "2012-10-17",\n "Statement": [\n {\n "Sid": "BedrockFlowInvoke",\n "Effect": "Allow",\n "Action": [\n "bedrock:InvokeFlow"\n ],\n "Resource": "arn:aws:bedrock:<REGION>:<ACCOUNT_ID>:flow/<flow_id>/alias/<alias_name>"\n }\n ]\n}\nTo enter and attach the policies:
\nTealiumCustomAccessPolicy) and optional description, then click Create policy.Go to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.
\nAfter adding the connector, configure the following settings:
\nbedrock:PutRecord permission along with streams you want to send data to.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:
\n{{tealium_account}}, {{tealium_profile}}, {{tealium_visitor_id}}, {{visitor_json}}.tealium_account, tealium_profile, tealium_visitor_id, tealium_event).Last product viewed to last_product_viewed and reference it in the prompt as {{last_product_viewed}}.You are an AI assistant that must return only valid JSON.\nDo not include explanations, markdown, code fences, or any text outside the JSON object.\n\nUsing the visitor data below, calculate a numeric score between 0 and 100 that represents\nthe visitor's likelihood to convert in this session.\n\nReturn a single JSON object only, with this exact structure:\n\n{\n "tealium_account": "{{tealium_account}}",\n "tealium_profile": "{{tealium_profile}}",\n "tealium_visitor_id": "{{tealium_visitor_id}}",\n "tealium_event": "bedrock_ai_insight",\n "visitor_score": <integer between 0 and 100>\n}\n\nVisitor data:\n{{visitor_json}}\n\nPay particular attention to the value of {{last_product_viewed}}.\nThe response will resemble the following:
\n{\n "metrics": {\n "latencyMs": 1272\n },\n "output": {\n "message": {\n "content": [\n {\n "text": "{\\"tealium_account\\":\\"your-account\\",\\"tealium_profile\\":\\"main\\",\\"tealium_visitor_id\\":\\"__your-account_main__5574_438850__\\",\\"tealium_event\\":\\"bedrock_ai_insight\\",\\"visitor_score\\":85}"\n }\n ],\n "role": "assistant"\n }\n },\n "stopReason": "end_turn",\n "usage": {\n "inputTokens": 8811,\n "outputTokens": 65,\n "serverToolUsage": {},\n "totalTokens": 8876\n }\n}\nThe connector accepts the response and sends the JSON event object to the Tealium Collect API endpoint.
\nAmazon 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.
\nTo 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.
\nThe sections below describe the required and optional components of a flow.
\nEvery flow begins with an input node. This node represents the JSON document Tealium sends to the flow.
\nTealium sends your mapped attributes in the following format similar to the following example:
\n"document": {\n "tealium_account": "services-example",\n "tealium_profile": "ai",\n "tealium_visitor_id": "1234567890abc",\n "visitor_profile": {\n "lifetime_value": "1200",\n "total_orders": 5,\n ...\n }\n}\nInside your flow, reference fields using $.data.attribute_name. Based on the previous example:
| Tealium Attribute | \nBedrock Reference | \nExample | \n
|---|---|---|
tealium_account | \n$.data.tealium_account or {{tealium_account}} | \nservices-example | \n
tealium_profile | \n$.data.tealium_profile or {{tealium_profile}} | \nai | \n
tealium_visitor_id | \n$.data.tealium_visitor_id or {{tealium_visitor_id}} | \n1234567890abc | \n
visitor_profile | \n$.data.visitor_profile | \n"visitor_profile": {"lifetime_value": "1200","total_orders": 5,...} | \n
Next, add a prompt node to generate AI output (such as a score, recommendation, or decision).
\nInside the prompt node:
\n{{fieldname}} format. For example, {{tealium_account}}.For an example, see the Prompt example section above.
\nAmazon 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.
\nAfter 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.
\nFor 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.
\nAfter your prompt produces structured JSON, you must send that result back into Tealium for profile enrichment.
\nAdd a Lambda node that:
\n$.data from your prompt node).POST https://collect.tealiumiq.com/event.tealium_accounttealium_profiletealium_visitor_idtealium_event (user-defined)visitor_score)Use our provided Lambda example or build your own.
\nAlthough Tealium does not process the flow’s API response, an output node is required to complete the flow.
\nConnecting your Lambda output to the FlowOutputNode doesn’t affect Tealium processing, but helps you verify that the flow works with the following tools:
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.
\nThe account and profile must be configured to accept server-side events with the specified data source.
\nThis example requires Node.js version 18.x or later as the runtime environment.
\n\n| Action Name | \nAudienceStream | \nEventStream | \n
|---|---|---|
| Send Prompt to Bedrock AI Model | \n✓ | \n✓ | \n
| Send Data to Bedrock AI Managed Prompt | \n✓ | \n✓ | \n
| Send Data to Bedrock AI Workflow | \n✓ | \n✓ | \n
Use Send Prompt to Bedrock AI Model when you need a simple, single-model call that returns a response synchronously through the connector.
\n| Parameter | \nDescription | \n
|---|---|
| Model ID or Inference Profile ARN | \nSelect an Amazon Bedrock model to use on-demand inference, or manually enter a Provisioned Throughput model ARN or inference profile ARN. Only models that support on-demand inference and text input/output are shown. If the model you want does not appear, verify that the model is enabled in your AWS account and region and that it supports on-demand inference. If using Provisioned Throughput, enter the full model ARN (for example: arn:aws:bedrock:region:account-id:provisioned-model/...).Inference profile ARNs may also be used if configured in your AWS account. Model availability and supported inference types are determined by your AWS account permissions and region configuration. | \n
| Prompt Parameters | \nMap parameters to a placeholder to replace in the prompt. By default, the connector has access to {{tealium_account}}, {{tealium_profile}}, and {{tealium_visitor_id}}. These can be overwritten with mapping. | \n
| Add Visitor Profile | \n(Only audience actions) Whether to allow the visitor profile for use in the prompt template as the variable {{visitor_profile}}. | \n
| Add Current Visit | \n(Only audience actions) Whether to include current visit data in the {{visitor_profile}} object. | \n
| Add Event Payload | \n(Only event actions) Whether to allow the event payload for use in the prompt template as the variable {{event_payload}}. | \n
| Prompt | \n
| \n
| Debug Mode | \nWhen debug mode is enabled, the connector accepts the raw Bedrock response without sending it to Tealium Collect. Use Trace to validate the response format before enabling full processing. | \n
For more information, see Amazon Bedrock API Reference: InferenceConfiguration.
\n| Parameter | \nDescription | \n
|---|---|
maxTokens | \nMaximum number of tokens the model may generate in its response. Lower values produce shorter outputs and help reduce latency, cost, and throttling risk. | \n
temperature | \nControls randomness in the output. Lower values (such as 0.2) make responses more deterministic and higher values (such as 0.8) produce more creative and varied results. | \n
topP | \nNucleus sampling parameter that limits token selection to the smallest set whose cumulative probability exceeds this value. Lower values make output more focused; higher values allow more diversity. | \n
stopSequences | \nOne or more strings that cause the model to stop generating when encountered. Useful for truncating responses or enforcing structured output boundaries. | \n
Use Send Data to Bedrock AI Managed Prompt when you want a reusable, versioned call to a prompt that returns a response synchronously through the connector.
\n| Parameter | \nDescription | \n
|---|---|
| Prompt ARN | \n(Required) Provide the ARN of a Bedrock Prompt Management template. The prompt ARN can be found in the Overview section of the prompt details in Bedrock. | \n
| Prompt Data | \n
| \n
| Add Visitor Profile | \n(Only audience actions) Whether to allow the visitor profile for use in the prompt template as the variable {{visitor_profile}}. | \n
| Add Current Visit | \n(Only audience actions) Whether to include current visit data in the {{visitor_profile}} object. | \n
| Add Event Payload | \n(Only event actions) Whether to allow the event payload for use in the prompt template as the variable {{event_payload}}. | \n
| Debug Mode | \nWhen debug mode is enabled, the connector accepts the raw Bedrock response without sending it to Tealium Collect. Use Trace to validate the response format before enabling full processing. | \n
Use Send Data to Bedrock AI Workflow when you need multi-step orchestration or knowledge base retrieval that runs asynchronously through Lambda.
\n| Parameter | \nDescription | \n
|---|---|
| Bedrock Flow Alias ARN | \n(Required) Enter the ARN of the Bedrock Flow Alias you want this action to invoke. We recommend creating an alias such as live and using that ARN here. | \n
| Flow Data | \n
| \n
| Add Visitor Profile | \n(Only audience actions) Whether to include the full visitor profile in the Flow input as a visitor_profile JSON object. | \n
| Add Current Visit | \n(Only audience actions) Whether to include the current visit data in the visitor_profile JSON object. | \n
| Add Event Payload | \n(Only event actions) Whether to include the event payload in the Flow input as the event_payload JSON object. | \n
The following are common error codes and resolutions:
\nAccessDeniedException or NotAuthorized
\nYour IAM user or role doesn’t have the required permissions (for example, bedrock:InvokeModel, bedrock:RenderPrompt, bedrock:InvokeFlow, bedrock:ListFoundationModels).
\nTo 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
\nThe configured access keys or STS session are invalid or expired.
\nTo 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
\nThe AWS account is not fully enabled for Bedrock or for a specific model (for example, Anthropic).
\nTo 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.
\nThe following errors mean the request reached Bedrock, but the service or model could not complete it successfully.
\nValidationException or ValidationError
\nThe request body or parameters are invalid for the target model or API (for example, wrong model ID, unsupported parameters, input too large).
\nTo 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
\nThe specified model, prompt version, or Flow alias ARN does not exist or is not available in that region.
\nTo solve this, double‑check ARNs and region in the connector configuration against the values shown in the Bedrock console.
ThrottlingException or ServiceQuotaExceededException
\nYour calls exceed Bedrock quotas (for example, TPS or token limits).
\nTo solve this, reduce call frequency or request a quota increase in AWS.
ServiceUnavailable, InternalFailure, or InternalServerException
\nTemporary or internal errors within Bedrock.
\nTo 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)
\nThe model failed, is still warming up, or took too long to respond.
\nTo 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.
\n" } , { "weight": "0", "url": "https://docs-preview.tealium.com/server-side-connectors/anthropic-connector/", "title": "Anthropic Connector Setup Guide", "body": "For an overview of how AI connectors work and how to structure your prompts, see our guide to AI connectors.
\nThis connector invokes an Anthropic model with your custom prompt and mapped Tealium data, then sends the response as a JSON event back to Tealium Collect for real-time enrichment.
\nThe connector should be used for targeted, high-value interactions rather than high-volume events. Excessive usage may result in rate limits or increased API costs in your vendor account and add to your inbound Tealium event volume.
\nBefore activating this connector, review your account limits, usage tier, and pricing model. This connector can generate a high volume of requests depending on your event and audience triggers, which may result in unexpected usage or overage costs.
\nFor more information, see Claude API Docs: Rate limits.
\nThis connector uses the following vendor API:
\nhttps://api.anthropic.com/v1Navigate to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.
\nAfter adding the connector, configure the following settings:
\n| Action Name | \nAudienceStream | \nEventStream | \n
|---|---|---|
| Send Prompt to Anthropic | \n✓ | \n✓ | \n
For an overview of how AI connectors work and how to structure your prompts, see our guide to AI connectors.
\n| Parameter | \nDescription | \n
|---|---|
| Model | \nSelect the Anthropic model to use for this prompt. Choose a model that aligns with your performance and cost requirements. | \n
The connector automatically includes important Tealium attributes when invoking the AI model and when returning the structured response.
\nThe following attributes are automatically added to the AI request and included in the structured output JSON: tealium_account, tealium_profile, tealium_visitor_id.
These values are taken from the current event and do not need to be referenced in the prompt. You may override these values using mappings.
\n| Parameter | \nDescription | \n
|---|---|
tealium_event | \n(Required) Enter the tealium_event value to include in the AI response returned to Tealium. | \n
tealium_datasource | \n(Optional) The data source key associated with the response events from this connector. | \n
| Prompt Parameters | \nMap Tealium attributes to placeholder names used in your prompt template. For example, map Lifetime Value to lifetime_val, then reference {{lifetime_val}} in the prompt template. | \n
| Include Event Payload | \n(Available for event actions) Check this box to include the event payload for use in the prompt template as variable {{event_payload}}. | \n
| Include Visitor Profile | \n(Available for audience actions) When enabled, the full visitor profile is made available to the prompt as {{visitor_profile}}. | \n
| Include Current Visit | \n(Available for audience actions) When enabled, current visit attributes are added to the {{visitor_profile}} object (keyed by attribute name). | \n
| Prompt | \nEnter the prompt to send to the selected Anthropic model. Use the guidelines below to ensure consistent and machine-readable output: Use double curly braces for mapped parameters, for example: {{product_id}}, {{event_value}}.For audience connector actions, reference {{visitor_profile}} after enabling Include visitor profile.For event connector actions, reference {{event_payload}} after enabling Include current event payload.Do not include JSON formatting instructions (for example, Return only JSON). The connector enforces the JSON structure automatically. | \n
| Parameter | \nDescription | \n
|---|---|
temperature | \nControls randomness and creativity (lower = more deterministic). | \n
max_tokens | \nMaximum number of tokens the model can generate. If a value is not provided, the connector sets the default to 512. | \n
top_p | \nControls diversity by sampling only from the top-p probability mass. | \n
Define the attributes to include in the AI response. These mappings determine the schema sent to Anthropic using output_config to ensure the response JSON matches the schema.
Do not add JSON formatting instructions to your prompt. The schema derived from these mappings enforces the structure automatically.
\n| Parameter | \nDescription | \n
|---|---|
| Attribute name | \nThe attribute name to include in the AI response event. You must create a matching event attribute for enrichment. | \n
| Required/Optional | \nDetermines if the attribute is required or optional in the response event. | \n
| Data type | \nThe data type of the field (string, number, integer, or boolean). | \n
| Debug Mode | \nWhen enabled, the connector does not send responses to Tealium Collect. Use Trace to inspect the raw Anthropic response and validate that it is valid JSON before enabling full processing. | \n
Tealium offers a data foundation for app-like experiences in browsers, widgets, and custom ChatGPT interfaces. It supports consistent data collection and visitor identity management across platforms.
\nThis solution for ChatGPT uses an MCP-friendly design to achieve the following:
\nThis approach uses the standard Universal Tag (utag.js) installation from a dedicated profile in Tealium iQ. The only difference is that it does not rely on the anonymous ID generated by utag.js, so it generates and persists its own ID using utility functions.
Benefits:
\nThe following sample code demonstrates the following:
\nutag.js, just like you do on a web site.<script>\n // Load Tealium iQ\n (function(a,b,c,d){\n a='https://tags.tiqcdn.com/utag/[ACCOUNT]/[PROFILE]/[ENVIRONMENT]/utag.js';\n b=document;c='script';d=b.createElement(c);d.src=a;\n d.type='text/java'+c;d.async=true;\n a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a);\n })();\n\n // Generate a 32-char lowercase alphanumeric visitor ID\n function generateTealiumVisitorId() {\n const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';\n return Array.from({ length: 32 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');\n }\n\n // Retrieve or create & persist the visitor ID\n let tealium_visitor_id = localStorage.getItem('tealium_visitor_id');\n if (!tealium_visitor_id) {\n tealium_visitor_id = generateTealiumVisitorId();\n localStorage.setItem('tealium_visitor_id', tealium_visitor_id);\n }\n\n // App initialized\n utag.track('event', {\n 'tealium_event': 'interface_loaded',\n 'app_version': '2.1.0',\n 'user_tier': 'enterprise',\n 'tealium_visitor_id': tealium_visitor_id\n });\n\n // PDP view\n function trackViewPdp(product) {\n utag.track('view', {\n 'tealium_event': 'view_pdp',\n 'product_id': product.id,\n 'product_name': product.name,\n 'category': product.category,\n 'price': product.price,\n 'currency': product.currency || 'USD',\n 'tealium_visitor_id': tealium_visitor_id\n });\n }\n\n // Button click\n function trackButtonClick(button) {\n utag.track('link', {\n 'tealium_event': 'button_click',\n 'button_id': button.id,\n 'button_text': button.text,\n 'location': button.location || 'pdp',\n 'app_version': '2.1.0',\n 'tealium_visitor_id': tealium_visitor_id\n });\n }\n</script>\nServer-side tracking sends events directly to Tealium using the HTTP API. Similar to the client-side solution, it generates and persists its own anonymous visitor ID using added utility functions.
\nWe recommend this approach for the following scenarios:
\nThe following server-side tracking solutions are available:
\nThe Node.js solution has client code that generates and persists the anonymous visitor ID and calls wrapper functions for tracked events.
\nFor example, the following sample code generates the visitor ID and sends order tracking requests to the server. The order object comes from your app when a customer completes a purchase.
// Generate a 32-char lowercase alphanumeric visitor ID\nfunction generateTealiumVisitorId() {\n const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';\n return Array.from({ length: 32 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');\n}\n\n// Retrieve or create & persist the visitor ID\nlet tealium_visitor_id = localStorage.getItem('tealium_visitor_id');\nif (!tealium_visitor_id) {\n tealium_visitor_id = generateTealiumVisitorId();\n localStorage.setItem('tealium_visitor_id', tealium_visitor_id);\n}\n\nasync function trackPurchaseServer(order) {\n await fetch('/api/tealium/track', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n 'tealium_event': 'purchase',\n 'tealium_visitor_id': tealium_visitor_id,\n 'order_id': order.id,\n 'order_total': order.total,\n 'currency': order.currency || 'USD',\n 'items': order.items\n })\n });\n}\nThe following sample server-side code sets up an endpoint to accept tracking calls and uses Tealium for Node.js to forward those events on to Tealium Collect.
\n// npm i tealium-collect express\nconst express = require('express');\nconst TealiumCollect = require('tealium-collect');\nconst app = express();\napp.use(express.json());\n\nconst tealium = new TealiumCollect({\n 'account': 'your-account',\n 'profile': 'chatgpt-app',\n 'environment': 'prod'\n});\n\napp.post('/api/tealium/track', async (req, res) => {\n try {\n const tealium_visitor_id = req.body.tealium_visitor_id;\n\n if (!/^[a-z0-9]{32}$/.test(tealium_visitor_id || '')) {\n return res.status(400).json({ error: 'Invalid or missing tealium_visitor_id' });\n }\n\n const allowed = new Set(['interface_loaded','view_pdp','button_click','purchase']);\n if (!allowed.has(req.body.tealium_event)) {\n return res.status(400).json({ error: 'Unsupported event type' });\n }\n\n await tealium.track({\n ...req.body,\n tealium_visitor_id,\n 'timestamp': req.body.timestamp || new Date().toISOString()\n });\n\n res.status(204).end();\n } catch (e) {\n console.error('Tealium track error:', e);\n res.status(500).json({ error: 'Tracking failed' });\n }\n});\n\napp.listen(3000, () => console.log('Tealium server listening on 3000'));\nUse this approach for browser apps where you have access to embed <script> tags. This code uses fetch() and the HTTP API to send events directly to Tealium and uses the same utility methods to generate and persist an anonymous visitor ID.
<script>\n // Generate a 32-char lowercase alphanumeric visitor ID\n function generateTealiumVisitorId() {\n const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';\n return Array.from({ length: 32 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');\n }\n\n // Retrieve or create & persist the visitor ID\n let tealium_visitor_id = localStorage.getItem('tealium_visitor_id');\n if (!tealium_visitor_id) {\n tealium_visitor_id = generateTealiumVisitorId();\n localStorage.setItem('tealium_visitor_id', tealium_visitor_id);\n }\n\n async function sendCollectEvent(payload) {\n const base = {\n 'tealium_account': 'your-account',\n 'tealium_profile': 'chatgpt-app',\n 'tealium_visitor_id': tealium_visitor_id,\n 'timestamp': new Date().toISOString()\n };\n\n await fetch('https://collect.tealiumiq.com/event', {\n 'method': 'POST',\n 'headers': { 'Content-Type': 'application/json' },\n 'body': JSON.stringify({ ...base, ...payload })\n });\n }\n\n function trackViewPdpServer(product) {\n return sendCollectEvent({\n 'tealium_event': 'view_pdp',\n 'product_id': product.id,\n 'product_name': product.name,\n 'product_category': product.category,\n 'product_price': product.price,\n 'product_currency': product.currency || 'USD'\n });\n }\n\n function trackButtonClickServer(button) {\n return sendCollectEvent({\n 'tealium_event': 'button_click',\n 'button_id': button.id,\n 'button_text': button.text,\n 'location': button.location || 'pdp',\n 'app_version': '2.1.0'\n });\n }\n</script>\nA hybrid approach uses the client-side solution to track interaction events, such as interface_loaded, view_pdp, and button_click, and the server-side solution to track authoritative events such as purchase. We recommend this approach to achieve the most complete tracking of your app.
When running the hybrid solution, do not load the Tealium Collect tag in your iQ profile. This prevents duplicate event tracking.
\nTo ensure accurate tracking and a unified visitor profile, always use the same anonymous visitor ID for both client-side and server-side events. This approach maintains a single visitor identity across ChatGPT, web, and mobile, enabling consistent tracking and real-time personalization.
\nWe recommend including known user identifiers as separate parameters when available, for example customer_id or email_address_hash, but do not use these values to replace tealium_visitor_id.
Expose a simple MCP tool from your server for ChatGPT to call. This approach lets ChatGPT handle conversational logic, while your server enforces format, identity, and policy.
\nTool: tealium-track-event
Example schema:
\n{\n "account": "your-account",\n "profile": "chatgpt-app",\n "environment": "prod",\n "event": "view_pdp",\n "visitorId": "abcdefghijklmnopqrstuvwxyz012345",\n "data": {\n "product_id": "widget-123",\n "price": 29.99,\n "currency": "USD"\n }\n}\nValidation:
\nvisitorId must match the regular expression /^[a-z0-9]{32}$/.event must be in list of allowed events (interface_loaded, view_pdp, button_click, purchase).Add the Moments MCP server to your app to enable personalization.
\nExample flow:
\nview_pdp, button_click, and purchase.tealium_visitor_id.This app supports data privacy and compliance through the following features:
\nnpm or pnpmpnpm install\ncd server\npnpm install\ncd ..\npnpm run build \ncd server \npnpm start\nngrok http 8000 \nSession Status online \nAccount Your Account (Plan: Free) \nUpdate update available (version 3.x.x, Ctrl-C to update) \nVersion 3.x.x \nRegion United States (us) \nWeb Interface http://127.0.0.1:4040 \nForwarding https://abc123def456.ngrok-free.app -> http://localhost:8000 \nhttps://abc123def456.ngrok-free.app).server/index.ts on lines 30 and 34, replace https://resolvedly-pouched-nena.ngrok-free.dev with your new ngrok URL.src/tealium/TealiumTracker.tsx on line 134.# Kill the current server (Ctrl+C)\ncd server\npnpm start\ncd .. \npnpm run build\nMake note of the following access points:
\n/mcp/api/tealium/tracktealium-tracker tool.utag.js) loads and tracks events as if in a web app.If third-party libraries are blocked, allow their resources in your CSP.
\nTurning on server-side tracking sends client-side calls to /api/tealium/track, which uses the Tealium Collect NPM module to make tracking requests.
![](\"/images/guides/tealium-chatgpt-tracker-app.png\"){kind=tracking}
\n \nValidate results in Tealium Trace.
\n![](\"/images/guides/tealium-chatgpt-trace.png\")
\n \nFor an overview of how AI connectors work and guidance on when to use an AI connector or Tealium functions, see AI connectors and Tealium functions.
\nThis connector invokes an AI model with your custom prompt and mapped Tealium data, then sends the response as a JSON event back to Tealium Collect for real-time enrichment.
\nThe connector should be used for targeted, high-value interactions rather than high-volume events. Excessive usage may result in rate limits or increased API costs in your vendor account and add to your inbound Tealium event volume.
\nBefore activating the Google Vertex AI connector, review your Google Cloud quotas and limits. The connector can generate a high volume of requests depending on your event and audience triggers, which may result in unexpected usage or overage costs.
\nFor more information, see Google: Vertex AI quotas and limits.
\nKey considerations
\nTo get the most value from this connector, follow these guidelines to build effective solutions:
\n<customer purchase intent> in the prompt where you want that value to appear in the event JSON.tealium_account, write {{tealium_account}} in your prompt.This connector uses the following vendor API:
\nhttps://aiplatform.googleapis.com/v1Go to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.
\nAfter adding the connector, configure the following settings:
\nroles/aiplatform.user) in the project. This role allows the connector to both list available models and invoke the selected model through the Vertex AI Generative APIs.| Action Name | \nAudienceStream | \nEventStream | \n
|---|---|---|
| Send Prompt to Vertex AI | \n✓ | \n✓ | \n
Enter a name for the action and select the action type.
\nThe following section describes how to set up parameters and options for each action.
\nThis action invokes a Vertex AI model with your custom prompt and mapped Tealium data. If the model responds with a valid JSON event object, this event is sent back to your account where you can capture the generated value in a real-time enrichment.
\n| Parameter | \nDescription | \n
|---|---|
| Model | \n
| \n
| Parameter | \nDescription | \n
|---|---|
| Add Event Payload | \n(Available for event actions) Check this box to include the event payload for use in the prompt template as variable {{event_payload}}. | \n
| Add Visitor Profile | \n(Available for audience actions) Check this box to include the visitor profile for use in the prompt template as variable {{visitor_profile}}. | \n
| Add Current Visit | \n(Available for audience actions) Check this box to include the current visit within the variable {{visitor_profile}}. | \n
| Prompt | \n
| \n
| Debug Mode | \nWhen debug mode is enabled, the connector accepts the raw Vertex AI response without sending it to Tealium Collect. Use a trace to validate the response format before enabling full processing. | \n
| Parameter | \nDescription | \n
|---|---|
temperature | \nControls randomness and creativity. A lower value results in a sharper distribution curve with more focused and predictable answers, while a higher value results in a flatter distribution curve and more varied and creative answers. Allowed values are between 0 and 2. | \n
maxOutputTokens | \nThe maximum number of tokens to generate in the response. | \n
topP | \nSpecifies the nucleus sampling threshold. A lower topP value is safer and more focused, while a higher topP value is more varied and creative. Allowed values are between 0 and 1. For example, if topP is set to 0.9, only tokens whose cumulative probability reaches 90% are considered and low‑probability tail tokens are dropped. | \n
topK | \nSpecifies the top-k sampling threshold. A lower topK value is more deterministic and less diverse, while a higher topK value is more diverse but potentially less coherent. For example, if topK is set to 40, the next token is chosen (probabilistically, using temperature) from only the 40 highest‑probability tokens and everything else is ignored. | \n
This connector uses the following vendor API:
\nhttps://retail.googleapis.comGo to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.
\nAfter adding the connector, configure the following settings:
\nretail.userEvents.import. Google recommends using the Retail Editor role.| Action Name | \nAudienceStream | \nEventStream | \n
|---|---|---|
| Write User Event | \n✗ | \n✓ | \n
Enter a name for the action and select the action type.
\nThe following section describes how to set up parameters and options for each action.
\n| Parameter | \nDescription | \n
|---|---|
| Catalog | \nSelect the Vertex AI Search for Commerce catalog where user events are recorded. | \n
| Event Type | \nChoose the type of user event to send to Vertex AI Search for Commerce. This determines how the event is interpreted and which fields are required in the payload.
| \n
| Parameter | \nDescription | \n
|---|---|
| Attributes | \nMap extra user event features to include in the recommendation model | \n
| Template Variables | \n
| \n
| Templates | \n
| \n
For an overview of how AI connectors work and guidance on when to use an AI connector or Tealium functions, see AI connectors and Tealium functions.
\nThis connector invokes an OpenAI model with your custom prompt and mapped Tealium data, then sends the response as a JSON event to Tealium Collect for real-time enrichment.
\nThe OpenAI connector should be used for targeted, high-value interactions rather than high-volume events. Excessive usage may result in rate limits or increased API costs in your OpenAI account and add to your inbound Tealium event volume.
\nBefore activating the OpenAI connector, review your OpenAI account limits, usage tier, and pricing model. The connector can generate a high volume of requests depending on your event and audience triggers, which may result in unexpected usage or overage costs.
\nFor more information, see OpenAI Developers: Rate limits.
\nKey considerations
\nTo get the most value from this connector, follow these guidelines to build effective solutions:
\n<customer purchase intent> in the prompt where you want that value to appear in the event JSON.tealium_account, write {{tealium_account}} in your prompt.This connector uses the following vendor API:
\nhttps://api.openai.com/v1Go to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.
\nAfter adding the connector, configure the following settings:
\n| Action Name | \nAudienceStream | \nEventStream | \n
|---|---|---|
| Send Prompt to OpenAI | \n✓ | \n✓ | \n
This action invokes an OpenAI model with your custom prompt and mapped Tealium data. If the model responds with a valid JSON event object, this event is sent back to your account where you can capture the generated value in a real-time enrichment.
\n| Parameter | \nDescription | \n
|---|---|
| Model | \nSelect the OpenAI model to use for this prompt, for example gpt-4.1-mini or gpt-4.1. We recommend using a model optimized for structured output (JSON) that supports your performance and cost requirements. For more information, see OpenAI Developers: Production best practices. | \n
| Add Event Payload | \n(Available for event actions) Check this box to include the event payload for use in the prompt template as variable {{event_payload}}. | \n
| Add Visitor Profile | \n(Available for audience actions) Check this box to include the visitor profile for use in the prompt template as variable {{visitor_profile}}. | \n
| Add Current Visit | \n(Available for audience actions) Check this box to include the current visit within the variable {{visitor_profile}}. | \n
| Prompt | \nEnter the prompt to send to the selected OpenAI model. Follow these guidelines to ensure consistent and machine-readable output: Use double curly braces ( {{ }}) to reference mapped parameters, for example: {{tealium_account}}, {{tealium_visitor_id}}, {{visitor_profile}}.Use {{event_payload}} to include the event payload in the prompt after first enabling the Add Event Payload checkbox.Avoid ambiguous phrasing; prompts should be deterministic so the output can be parsed reliably. Define a valid Tealium event JSON object to be returned in the response. Explicitly instruct the model to include tealium_account, tealium_profile, and tealium_visitor_id and your output variable in this event JSON so the connector can forward the event to the Tealium Collect endpoint.The connector automatically includes instructions in the prompt to force the model to return JSON. For example prompts, see How it works. | \n
| Parameter | \nDescription | \n
|---|---|
temperature | \nControls randomness and creativity. | \n
max_output_tokens | \nThe maximum number of tokens the model can generate. | \n
max_tool_calls | \nThe maximum number of total calls to built-in tools that can be processed in a response. | \n
top_p | \nControls diversity by sampling only from the top-p probability mass. | \n
parallel_tool_calls | \nWhether to allow the model to run tool calls in parallel. Defaults to true. | \n
prompt_cache_key | \nUsed by OpenAI to cache responses for similar requests to optimize your cache hit rates. | \n
service_tier | \nSpecifies the processing type used for serving the request. | \n
tool_choice | \nHow the model should select which tool or tools to use when generating a response. | \n
| Debug Mode | \nWhen debug mode is enabled, the connector accepts the raw OpenAI response without sending it to Tealium Collect. Use trace to validate the response format before enabling full processing. | \n
This connector uses the following vendor API:
\nhttps://bzr.openai.comGo to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.
\nAfter adding the connector, configure the following settings:
\npid). This value is appended to the API endpoint as a query parameter. Find your Pixel ID in OpenAI Ads > Settings > Conversions. Each conversion event you intend to send (for example, page_viewed, items_added, order_created) must be registered there for the pixel before live events count toward reporting.https://bzr.openai.com. Override only if directed by OpenAI for sandbox or staging environments.| Action Name | \nAudienceStream | \nEventStream | \n
|---|---|---|
| Send Event (Real-Time) | \n✓ | \n✓ | \n
| Send Event (Batched) | \n✓ | \n✓ | \n
| Parameter | \nDescription | \n
|---|---|
| Event Type | \nRequired. Select the type of event to send to OpenAI. Supported event types: Appointment Scheduled, Checkout Started, Contents Viewed, Custom, Items Added, Lead Created, Order Created, Page Viewed, Registration Completed, Subscription Created, Trial Started. | \n
| Custom Event Name | \nRequired when Event Type is Custom. Provide a custom name for the event. This value is ignored for all other event types. | \n
Map Tealium attributes to OpenAI top-level event fields.
\n| Parameter | \nDescription | \n
|---|---|
| Event ID | \nRequired. A unique identifier for the event, used for deduplication. | \n
| Timestamp | \nRequired. The event timestamp in milliseconds. Must be within 7 days in the past or 10 minutes in the future. | \n
| OPPRef | \nThe OpenAI privacy-preserving identifier. | \n
| Source URL | \nRequired when Action Source is web. The URL of the page where the event occurred. | \n
| Action Source | \nThe source of the conversion event. Supported values: web, mobile_app, offline, physical_store, phone_call, email, other. | \n
| Opt Out | \nSet to true to flag the event as opted out from personalization. | \n
Map applicable user identifiers to improve attribution accuracy. You may either pre-hash PII values yourself or let the connector hash them. Hashable fields appear as two columns: (apply SHA256 hash) for raw values the connector normalizes and hashes, and (already SHA256 hashed) for pre-hashed values.
\n| Parameter | \nDescription | \n
|---|---|
| Email address (apply SHA256 hash) | \nProvide a lowercase plain text email address and the connector hashes this value in the format OpenAI expects. Empty or null values are ignored. | \n
| Email address (already SHA256 hashed) | \nProvide an email address which has been SHA256 hashed. | \n
| Phone number (apply SHA256 hash) | \nProvide a lowercase plain text phone number and the connector hashes this value in the format OpenAI expects. Empty or null values are ignored. | \n
| Phone number (already SHA256 hashed) | \nProvide a phone number that has been SHA256 hashed. | \n
| External ID (apply SHA256 hash) | \nProvide a plain text external ID, such as a loyalty card ID or another identifier, and the connector hashes this value in the format OpenAI expects. | \n
| External ID (already SHA256 hashed) | \nProvide an external ID which has been SHA256 hashed. | \n
| Country (apply SHA256 hash) | \nProvide a country associated with the event and the connector hashes this value in the format OpenAI expects. | \n
| Country (already SHA256 hashed) | \nProvide a country value which has been SHA256 hashed. | \n
| City (apply SHA256 hash) | \nProvide a city associated with the conversion in lowercase letters and the connector hashes this value in the format OpenAI expects. | \n
| City (already SHA256 hashed) | \nProvide a city value which has been SHA256 hashed. | \n
| Zip code (apply SHA256 hash) | \nProvide a zip or postal code in lowercase and the connector hashes this value in the format OpenAI expects. | \n
| Zip code (already SHA256 hashed) | \nProvide a zip or postal code which has been SHA256 hashed. | \n
| External ID (raw) | \nA unique ID, such as a loyalty card ID or another identifier. Sent without hashing. | \n
| IP Address | \nThe IP address of the device. | \n
| User Agent | \nThe user agent string of the user’s web browser. | \n
For Customer Action events (Appointment Scheduled, Lead Created, Registration Completed) only the order-summary fields are accepted. OpenAI drops all other e-commerce fields from the outbound payload.
\n| Parameter | \nDescription | \n
|---|---|
| Amount | \nAn integer in minor units (for example, cents). If provided, Currency is required. | \n
| Currency | \nThe currency code in ISO 4217 format (for example, USD). | \n
When checked, disables the default Tealium-to-OpenAI automappings for this action (timestamp, source URL, IP address, user agent, and retail extension attributes _csubtotal, _ccurrency, _csku, _cprodname, _ccat, _cquan, _cprice). Explicit field mappings always take precedence. Unchecking this only fills in the blanks.
When enabled, the connector sends the event with validate_only: true so OpenAI validates the payload and returns any errors without persisting the event. Use this for troubleshooting and dry-runs. Leave disabled for production traffic.
Optional. Override the connector-level Pixel ID for this action. If provided, the connector uses this value instead of the Pixel ID configured in the connector settings.
\nOptional. Override the connector-level API Key for this action. If provided, the connector uses this value instead of the API Key configured in the connector settings.
\nThis action uses batched requests to support high-volume data transfers to the vendor. Parallel processing may result in events reaching the vendor out of sequence. Add a sequence value to events if ordering is important. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:
\nThis action uses the same parameters and mapping options as the Send Event (Real-Time) action. For more information, see Send Event (Real-Time).
\n" } ] }