Skip to main content

​
Integrating Sponsored Prompts

This guide provides comprehensive instructions on integrating sponsored prompts within your conversational AI. It covers essential aspects such as environment modes, tracking and more.

​
Production vs. Sandbox Mode

Important: When integrating sponsored prompts, it’s crucial to distinguish between production and sandbox (non-production) environments. - In sandbox mode (production=False), ads are returned for testing purposes but are not counted for monetization. - In production mode (production=True), ads are live and contribute to monetization. Always ensure production=True is used only in your live production environment. For all testing and development, set production=False.

​
Using Sponsored Prompts

Sponsored prompts can be incorporated into your AI conversations in two primary ways: as an initial opener or as contextual follow-up questions.

​
Handling Click Tracking

To ensure accurate monetization and analytics, you must track user clicks on sponsored messages.
1

Receive the Token

The sponsored prompts endpoint (for both openers and follow-ups) returns a unique token along with the sponsored question. Store this token.
2

Detect User Interaction

When a user clicks or taps on the displayed sponsored question.
3

Send Click Confirmation

Immediately send a POST request to the /api/v1/prompt/click/ endpoint. Include the token (received in Step 1) in the JSON body of your request.
{
  "token": "THE_UNIQUE_TOKEN_RECEIVED"
}
4

Receive Reward Confirmation

A successful POST request to the click tracking endpoint will record the click and associate the reward.
Code Example for Click Tracking: 
import requests

url = "https://api.thrads.ai/api/v1/prompt/click/"

payload = {"token": "<string>"}
headers = {"Content-Type": "application/json"}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

​
Best Practices

​
1. Use Metadata for Better Targeting

payload = {
    "userId": "user123",
    "chatId": "chat456",
    "content": content,
    "metaData": {
        "topic": "outdoor gear",
        "user_interests": "camping, hiking, outdoor",
        "conversation_stage": "gear_selection"
    },
    "production": True
}

​
2. Control Ad Frequency (Only for follow-up)

Use adFrequencyLimit and conversationOffset to prevent ad fatigue: 
payload = {
    "userId": "user123",
    "chatId": "chat456",
    "content": content,
    "adFrequencyLimit": 2,  # Maximum of 1 ad every 2 turns
    "conversationOffset": 5,  # Wait for 5 turns before showing ads
    "production": True
}

​
3. Managing Response Delays

In rare cases, the Thrads API response might be delayed (typically between 0.5-0.8 seconds). During this time, the user may begin typing a new question. We recommend to have some logic in place to suppress the ad render if that arrives late. For detailed API specifications, please refer to the API Reference for Sponsored Prompts.