Skip to main content
POST
/
api
/
v1
/
message
/
get-ad
Get Sponsored Message
curl --request POST \
  --url https://dev.thrads.ai/api/v1/message/get-ad/ \
  --header 'Content-Type: application/json' \
  --header 'thrads-api-key: <api-key>' \
  --data '
{
  "userId": "<string>",
  "chatId": "<string>",
  "content": {
    "user": "<string>",
    "chatbot": "<string>"
  },
  "userRegion": "<string>",
  "metaData": {},
  "force": true,
  "conversationOffset": 2,
  "adFrequencyLimit": 5,
  "production": false
}
'
{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "success",
  "message": "<string>",
  "data": {
    "creative": "<string>",
    "prod_name": "<string>",
    "img_url": "<string>",
    "prod_url": "<string>"
  }
}

Authorizations

​
thrads-api-key
string
header
required

API key for authenticating requests to the Thrads API. You can obtain your API key from the Thrads Platform dashboard.

Body

application/json

Request model for sponsored chatbot messages with required conversation context and targeting options

​
userId
string
required

Unique identifier for the user requesting the sponsored message. Must be the same for the same user across all conversations.

Maximum string length: 100
​
chatId
string
required

Unique identifier for the chat session or conversation. Must be the same across the same conversation.

Maximum string length: 100
​
content
Content · object
required

Required conversation context MUST contain exactly two fields: 'user' and 'chatbot', both populated with strings representing the latest message exchange

​
userRegion
string | null

Geographic region of the user for localized ad targeting. Should be an ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE', 'JP')

​
metaData
Metadata · object

Additional context about user interests, conversation topic, or targeting preferences

​
force
boolean | null

If set to true it forces the ad generation regardless of frequency limits or other constraints. If set to false it inhibits the ad generation. Default is set to null which does not affect the ad generation

​
conversationOffset
integer
default:2

Number of conversation turns to wait before showing the first ad

Required range: 0 <= x <= 20
​
adFrequencyLimit
integer
default:5

Number of turns to wait before showing the next ad

Required range: 0 <= x <= 20
​
production
boolean
default:false

Whether this is a production request (true) or sandbox/testing (false). Only production requests count for monetization.

Response

​
apiVersion
string
required

Version of the Thrads API being used

​
requestId
string
required

Unique identifier for this API request for tracking and debugging

​
timestamp
string<date-time>
required

ISO 8601 timestamp when the response was generated

​
docsUrl
string
required

URL to the API documentation for reference

​
totalTime
number
required

Total processing time for the request in seconds

​
status
enum<string>
required

Always 'success' for successful requests

Available options:
success
​
message
string
required

Human-readable message describing the successful response

​
data
SponsoredMessageData · object
required