Get Sponsored Message

POST

api

message

get-ad

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
}
'

import requests

url = "https://dev.thrads.ai/api/v1/message/get-ad/"

payload = {
    "userId": "<string>",
    "chatId": "<string>",
    "content": {
        "user": "<string>",
        "chatbot": "<string>"
    },
    "userRegion": "<string>",
    "metaData": {},
    "force": True,
    "conversationOffset": 2,
    "adFrequencyLimit": 5,
    "production": False
}
headers = {
    "thrads-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'thrads-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    userId: '<string>',
    chatId: '<string>',
    content: {user: '<string>', chatbot: '<string>'},
    userRegion: '<string>',
    metaData: {},
    force: true,
    conversationOffset: 2,
    adFrequencyLimit: 5,
    production: false
  })
};

fetch('https://dev.thrads.ai/api/v1/message/get-ad/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dev.thrads.ai/api/v1/message/get-ad/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '<string>',
    'chatId' => '<string>',
    'content' => [
        'user' => '<string>',
        'chatbot' => '<string>'
    ],
    'userRegion' => '<string>',
    'metaData' => [
        
    ],
    'force' => true,
    'conversationOffset' => 2,
    'adFrequencyLimit' => 5,
    'production' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "thrads-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://dev.thrads.ai/api/v1/message/get-ad/"

	payload := strings.NewReader("{\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"userRegion\": \"<string>\",\n  \"metaData\": {},\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("thrads-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://dev.thrads.ai/api/v1/message/get-ad/")
  .header("thrads-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"userRegion\": \"<string>\",\n  \"metaData\": {},\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.thrads.ai/api/v1/message/get-ad/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["thrads-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"userRegion\": \"<string>\",\n  \"metaData\": {},\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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>"
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "detail": [
      {
        "loc": [
          "<string>"
        ],
        "msg": "<string>",
        "type": "<string>"
      }
    ]
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

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

Show child attributes

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 | null

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

Show child attributes

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

Show child attributes

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
}
'

import requests

url = "https://dev.thrads.ai/api/v1/message/get-ad/"

payload = {
    "userId": "<string>",
    "chatId": "<string>",
    "content": {
        "user": "<string>",
        "chatbot": "<string>"
    },
    "userRegion": "<string>",
    "metaData": {},
    "force": True,
    "conversationOffset": 2,
    "adFrequencyLimit": 5,
    "production": False
}
headers = {
    "thrads-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'thrads-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    userId: '<string>',
    chatId: '<string>',
    content: {user: '<string>', chatbot: '<string>'},
    userRegion: '<string>',
    metaData: {},
    force: true,
    conversationOffset: 2,
    adFrequencyLimit: 5,
    production: false
  })
};

fetch('https://dev.thrads.ai/api/v1/message/get-ad/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dev.thrads.ai/api/v1/message/get-ad/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '<string>',
    'chatId' => '<string>',
    'content' => [
        'user' => '<string>',
        'chatbot' => '<string>'
    ],
    'userRegion' => '<string>',
    'metaData' => [
        
    ],
    'force' => true,
    'conversationOffset' => 2,
    'adFrequencyLimit' => 5,
    'production' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "thrads-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://dev.thrads.ai/api/v1/message/get-ad/"

	payload := strings.NewReader("{\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"userRegion\": \"<string>\",\n  \"metaData\": {},\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("thrads-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://dev.thrads.ai/api/v1/message/get-ad/")
  .header("thrads-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"userRegion\": \"<string>\",\n  \"metaData\": {},\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.thrads.ai/api/v1/message/get-ad/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["thrads-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userId\": \"<string>\",\n  \"chatId\": \"<string>\",\n  \"content\": {\n    \"user\": \"<string>\",\n    \"chatbot\": \"<string>\"\n  },\n  \"userRegion\": \"<string>\",\n  \"metaData\": {},\n  \"force\": true,\n  \"conversationOffset\": 2,\n  \"adFrequencyLimit\": 5,\n  \"production\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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>"
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "detail": [
      {
        "loc": [
          "<string>"
        ],
        "msg": "<string>",
        "type": "<string>"
      }
    ]
  }
}

{
  "apiVersion": "<string>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "docsUrl": "<string>",
  "totalTime": 123,
  "status": "error",
  "message": "<string>",
  "data": {},
  "error": {
    "type": "<string>",
    "code": 123
  }
}

Introduction

Sponsored Messages

Sponsored Prompts

Authorizations

Body

Response