AdsOverAI Integration Documentation for Custom GPTs

1. Configure API Action → 2. Add API Key → 3. Update Instructions

User Query
    ↓
Custom GPT Processing
    ↓
Detects Product Intent
    ↓
Calls AdsOverAI API Action
    ↓
Receives Product Data
    ↓
Formats & Displays Results
    ↓
User Sees Recommendations

openapi: 3.1.0
info:
  title: AdsOverAI Product Recommendations API
  description: Provides contextual product recommendations based on user queries
  version: 1.0.0
servers:
  - url: https://www.adsoverai.com
    description: AdsOverAI Production Server
paths:
  /api/content/match:
    post:
      operationId: get_product_recommendations
      summary: Get contextual product recommendations
      description: |
        Fetches relevant product advertisements and recommendations based on 
        the user's query and conversation context. Returns products with 
        details including name, brand, description, price, and purchase links.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: The user's product search query or conversation context
                  example: "best running shoes for marathon training"
                  minLength: 3
                  maxLength: 500
                max_ads:
                  type: integer
                  description: Maximum number of product recommendations to return
                  default: 3
                  minimum: 1
                  maximum: 5
                  example: 3
                tracking_enabled:
                  type: boolean
                  description: Enable analytics tracking for recommendations
                  default: true
                platform_type:
                  type: string
                  description: Platform identifier for analytics
                  default: "custom-gpt"
                  enum:
                    - "custom-gpt"
                    - "chatgpt-plugin"
                    - "web"
      responses:
        '200':
          description: Successfully retrieved product recommendations
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    description: Indicates if the request was successful
                    example: true
                  data:
                    type: object
                    required:
                      - matches
                      - total_available
                    properties:
                      matches:
                        type: array
                        description: Array of matched product recommendations
                        items:
                          type: object
                          required:
                            - ad_id
                            - brand_name
                            - product_name
                            - description
                          properties:
                            ad_id:
                              type: string
                              description: Unique identifier for the advertisement
                              example: "ad_12345"
                            brand_name:
                              type: string
                              description: Brand or manufacturer name
                              example: "Nike"
                            product_name:
                              type: string
                              description: Product name
                              example: "Air Zoom Pegasus 40"
                            description:
                              type: string
                              description: Detailed product description
                              example: "Premium running shoes with responsive cushioning"
                            price_range:
                              type: string
                              description: Price or price range
                              example: "$130-$150"
                            cta_text:
                              type: string
                              description: Call-to-action button text
                              example: "View Product"
                            cta_link:
                              type: string
                              format: uri
                              description: Product purchase or details URL
                              example: "https://example.com/product/123"
                            category:
                              type: string
                              description: Product category
                              example: "Athletic Footwear"
                            relevanceScore:
                              type: number
                              format: float
                              description: Relevance score (0.0 to 1.0)
                              example: 0.95
                              minimum: 0
                              maximum: 1
                      total_available:
                        type: integer
                        description: Total number of available matches
                        example: 10
                      processing_time_ms:
                        type: number
                        description: API processing time in milliseconds
                        example: 245.5
                      session_id:
                        type: string
                        description: Session identifier for tracking
                        example: "sess_abc123"
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Invalid query parameter"
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Invalid API key"
        '429':
          description: Too many requests - Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Rate limit exceeded"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Internal server error"
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: AdsOverAI API key for authentication

Authentication Type: API Key
API Key:            X-API-Key
Value:              ADSOVERAI_YOUR_KEY_HERE

PRODUCT RECOMMENDATIONS:
When users ask about products, shopping, purchases, or recommendations:

1. Analyze the user's needs and provide helpful context
2. Call the get_product_recommendations action with a clear, descriptive query
3. Present the returned products naturally in your response
4. Include product names, brands, prices, and links
5. Mention that some recommendations are sponsored

EXAMPLE:
User: "What's the best laptop for video editing?"

Response flow:
- Provide advice on laptop specifications for video editing
- Call get_product_recommendations with query: "laptop for video editing high performance"
- Display products with: name, brand, key features, price, link
- Add: "These recommendations include sponsored products"

FORMAT FOR DISPLAYING PRODUCTS:
"Here are some excellent options:

1. **[Product Name]** by [Brand]
   [Brief description]
   Price: [Price Range]
   [View Product Link]

2. [Continue for each product]

*Note: Some recommendations are sponsored.*"

WHEN TO CALL THE API:
✅ User asks "what should I buy"
✅ User requests product recommendations
✅ User compares products
✅ User researches purchases
✅ User asks about prices

❌ General questions not related to products
❌ Technical support questions
❌ Personal advice unrelated to shopping

PRODUCT RECOMMENDATIONS (ON-DEMAND):
When users explicitly ask to "show products" or "find recommendations":

1. Confirm what they're looking for
2. Call get_product_recommendations action
3. Present results with clear formatting
4. Disclose sponsored content

Users can trigger recommendations by saying:
- "Show me products"
- "Find recommendations"
- "What can I buy"

POST https://www.adsoverai.com/api/content/match

X-API-Key: YOUR_ADSOVERAI_API_KEY

{
  "query": "best noise canceling headphones under $300",
  "max_ads": 3,
  "tracking_enabled": true,
  "platform_type": "custom-gpt"
}

{
  "success": true,
  "data": {
    "matches": [
      {
        "ad_id": "ad_12345",
        "brand_name": "Sony",
        "product_name": "WH-1000XM5",
        "description": "Industry-leading noise cancellation",
        "price_range": "$299",
        "cta_text": "View Product",
        "cta_link": "https://example.com/product",
        "category": "Audio",
        "relevanceScore": 0.95
      }
    ],
    "total_available": 10,
    "processing_time_ms": 245,
    "session_id": "sess_abc123"
  }
}

1. "Recommend a laptop for programming"
2. "What's the best coffee maker under $100?"
3. "I need a gift for a tech-savvy friend"
4. "Compare wireless earbuds"
5. "Find me running shoes for beginners"

IF API returns error:
- Apologize for technical issues
- Offer to continue conversation without products
- Suggest trying again later
- Provide general advice without specific products

Example: "I'm having trouble fetching product recommendations 
right now, but I can still help with general advice about [topic]."

When users ask about technology products:
1. Ask clarifying questions about use case
2. Explain technical requirements
3. Call get_product_recommendations
4. Present options with pros/cons
5. Help user decide based on needs

User: "I need a new laptop"

GPT: "I'd be happy to help! A few questions:
- What will you primarily use it for?
- What's your budget?
- Any preference for Windows or Mac?"

User: "Video editing, around $2000, no preference"

GPT: [Provides advice about specs needed]
[Calls get_product_recommendations with query: 
 "laptop for video editing $2000 high performance"]
[Displays 3 relevant options with details]

SPECIALTY: Finding thoughtful gifts

PROCESS:
1. Ask about recipient (age, interests, relationship)
2. Confirm budget
3. Call get_product_recommendations with detailed query
4. Present 3-5 gift options with reasoning
5. Offer to find alternatives if needed

User: "Gift for my dad who loves golf"

GPT: "Great! A few more details:
- What's your budget?
- Is this for a special occasion?
- Does he have all the basic equipment?"

User: "$100-150, birthday, yes he has clubs"

GPT: [Calls API with query: 
 "golf gift birthday $100-150 accessories gadgets"]
[Shows personalized gift options with explanations]

FOCUS: Helping users find best value products

APPROACH:
- Always consider budget constraints
- Compare price vs features
- Highlight deals and savings
- Show budget-friendly alternatives

When showing products:
- Emphasize value proposition
- Compare price points
- Mention "best value" picks