fetchAd() Fetches and renders an ad based on the provided parameters and callbacks.
fetchAd ( fetchAdParams , callbacks ) Parameters Configuration options for fetching ads
Token provided during onboarding
Placement code provided during onboarding
Persistent user identifier (UUID, hashed email, etc.)
Identifier for the current conversation
Log verbosity level: “debug” | “info” | “log” | “warn” | “error” | “silent”
Default: “silent”
List of conversation messages.
DOM element where the ad will be rendered.
Optional event handlers for the ad fetching process
Called before the server request starts
onStart : function onStart () { console . log ( "Fetching ad started..." ); showLoadingSpinner (); } Called when ad content is fully fetched
onComplete : function onComplete ( content , metadata ) { console . log ( "Ad fetching complete" , content , metadata ); hideLoadingSpinner (); renderAd ( content ); } Called after each token is streamed
onToken : function onToken ( token ) { console . log ( "Received token:" , token ); appendToAdContainer ( token ); // Dynamically render the content } Called when streaming encounters an error
onError : function onError ( error ) { console . error ( "Error while fetching ad:" , error ); showErrorMessage ( "An error occurred. Please try again later." ); } Called when user clicks the ad
onAdClick : function onAdClick ({ id , content }) { console . log ( "Ad clicked:" , id , content ); trackClickEvent ( id , content ); } Called when ad enters viewport
onAdView : function onAdView ({ id , content }) { console . log ( "Ad viewed:" , id , content ); trackViewEvent ( id ); } Called with value which represents the bid amount (in $ CPM) for showing an ad in the ad slot. If value is null, this means we don’t have an ad matching your conversation or we could not submit a bid (possible reasons are that you are outside of contracted geography or you are over the rate limit for your token).
Return true if you want to render the ad or false if you want to skip filling the ad slot with an ad.
onBid : function onBid ( value ) { console . log ( "Ad can be filled with value:" , value ); return true ; // Return true if you want to render the ad. You can also return a Promise<boolean> } markAdAsViewed() Marks an ad as viewed when it becomes visible in the viewport.
markAdAsViewed ( impressionId , serverUrl ? ) Parameters The ID of the impression to be marked as viewed
Messages object The Message object represents a single message in the conversation context. Each message must have:
Unique identifier for the message
Timestamp when message was created (ISO 8601 string or Date object)
Who sent the message: “user” | “assistant”
The text content of the message
Example message array const messages = [ { id: "message-uuid-1" , createdAt: "2024-12-31T12:00:00.000Z" , role: "user" , content: "I am looking for a frying pan." }, { id: "message-uuid-2" , createdAt: "2024-12-31T12:00:05.000Z" , role: "assistant" , content: "For a versatile frying pan, consider an all-clad stainless steel..." } ]; Error handling The SDK provides robust error handling with:
Request timeout after 16 seconds by default
Automatic retry up to 3 times for retriable errors
Unretriable errors include HTTP 403, 429, and 404
Example error handling:
fetchAd ( fetchAdParams , { onError : ( error ) => console . error ( "Ad fetch failed:" , error ) }); Best practices
Chronological Order : Ensure messages are listed in chronological orderContext Completeness : Include sufficient prior messages for contextUnique IDs : Use unique, immutable identifiers for each message 
