Skip to main content
POST
/
v1
/
chatads
/
messages
curl -X POST 'https://api.getchatads.com/v1/chatads/messages' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "message": "What are the best noise-cancelling headphones?"
  }'

{
  "data": {
    "status": "filled",
    "offers": [
      {
        "link_text": "Bose QuietComfort Ultra earbuds",
        "url": "https://amazon.com/dp/B0CD2FSRDD/?tag=yourtag-20",
        "product": {
          "title": "Bose QuietComfort Ultra Bluetooth Earbuds...",
          "stars": 3.8,
          "reviews": 9765,
          "price": 199.0,
          "image": "https://m.media-amazon.com/images/I/51example.jpg",
          "brand_name": "Bose",
          "is_prime": true
        }
      }
    ],
    "requested": 1,
    "returned": 1,
    "billed": true
  },
  "error": null,
  "meta": {
    "request_id": "0f04eb2e-820a-460a-8427-ccc1a6233b6a",
    "timestamp": "2026-03-11T13:57:42.074Z",
    "version": "1.0.0",
    "usage": {
      "monthly_requests": 13,
      "daily_requests": 3,
      "daily_limit": 10000,
      "is_free_tier": false
    }
  }
}
Analyzes a user message to extract product keywords and return relevant affiliate links.
Using the API Explorer: Click “Try It” on the right to test this endpoint interactively. Enter your API key from app.getchatads.com/api/keys in the Authorization header field.

​
Request Body

​
message
string
required
The user message to analyze. Required, max 10,000 characters. Min 10 words.
​
ip
string
IPv4 address for country detection. Anything identified as non-US will be skipped.
​
country
string
Country code (e.g., ‘US’). If provided, skips IP-based country detection.
​
extraction_mode
string
default:"standard"
Controls how product keywords are extracted from the message:
  • none — skips product extraction and all filters (country, language, keyword, IP); finds an offer on the provided string
  • fast — fastest extraction, less accurate
  • standard — default full extraction
​
resolution_mode
string
default:"standard"
Controls how extracted keywords are resolved to affiliate URLs:
  • none — doesn’t look for offers; returns extracted product only
  • standard — default full resolution
​
input_type
string
default:"text"
Content type of the input message: text (default), image_url (analyze an image from a URL), or image_file (analyze an uploaded image). Image inputs are 3x the CPM.For image_url: URLs without a scheme (e.g., example.com/image.jpg) automatically get https:// prepended. The URL must have a valid host or a 400 error is returned.For image_file: Value must be a base64-encoded JPEG/PNG/WebP, max 10MB. Auto-resized if longest dimension exceeds 1500px.
​
image_title_filter
string
Filter image search results by title keyword. Used with input_type=image_url when an image contains multiple products (e.g. a desk setup) — passing image_title_filter: "desk" ensures only desk results are returned.
​
metadata
JSON object
Arbitrary JSON key-value pairs to attach to the request. Passed through and returned in the response for your own tracking purposes. Example: {"session_id": "abc123", "user_id": "u_456"}.

​
Response

​
data
object
​
error
object
Error details when request fails. Null for successful requests. Check error == null to determine success.
​
meta
object
curl -X POST 'https://api.getchatads.com/v1/chatads/messages' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "message": "What are the best noise-cancelling headphones?"
  }'

{
  "data": {
    "status": "filled",
    "offers": [
      {
        "link_text": "Bose QuietComfort Ultra earbuds",
        "url": "https://amazon.com/dp/B0CD2FSRDD/?tag=yourtag-20",
        "product": {
          "title": "Bose QuietComfort Ultra Bluetooth Earbuds...",
          "stars": 3.8,
          "reviews": 9765,
          "price": 199.0,
          "image": "https://m.media-amazon.com/images/I/51example.jpg",
          "brand_name": "Bose",
          "is_prime": true
        }
      }
    ],
    "requested": 1,
    "returned": 1,
    "billed": true
  },
  "error": null,
  "meta": {
    "request_id": "0f04eb2e-820a-460a-8427-ccc1a6233b6a",
    "timestamp": "2026-03-11T13:57:42.074Z",
    "version": "1.0.0",
    "usage": {
      "monthly_requests": 13,
      "daily_requests": 3,
      "daily_limit": 10000,
      "is_free_tier": false
    }
  }
}