AdsOverAI GPT Integration Documentation

Overview

AdsOverAI provides contextual product recommendations through a safe, read-only API designed specifically for GPT integration. The API is marked as non-consequential, meaning it's safe for automatic invocation without requiring user confirmation. This allows your custom GPT to naturally recommend products within conversations without interrupting the user experience.

Prerequisites

• ChatGPT Plus or ChatGPT Enterprise account
• AdsOverAI developer account (we'll create this in Step 1)
• Basic understanding of API authentication
• Access to create custom GPTs in ChatGPT

Complete Setup Guide

Step 1: Create Your AdsOverAI Developer Account

1. Visit www.adsoverai.com
2. Navigate to the Developers section or go directly to /developers
3. Click on "Sign Up for Developers" or "Join as AI Builder"
4. Complete the developer registration form:
   • Enter your full name
   • Provide your email address
   • Create a secure password
   • Select "AI Builder" or "Developer" as your account type
5. Agree to the Terms of Service and Privacy Policy
6. Click "Create Developer Account"
7. Check your email inbox for a verification email
8. Click the verification link in the email to activate your account
9. Log in to your new developer account

Note: The developer account gives you access to:

• API key generation and management
• Developer dashboard with analytics
• Integration documentation
• Usage analytics and monitoring
• Sandbox environment for testing

Step 2: Generate Your Developer API Key

Once logged in to your developer account:

1. Go to your Developer Dashboard
2. Navigate to Settings → API Keys (or Developer section)
3. Click the "Generate New API Key" button
4. Give your API key a name (e.g., "My GPT Integration" or "Product Recommender Bot")
5. Copy your API key immediately - it will look something like: ak_1234567890abcdefghijklmnop
6. Store it securely in a password manager or secure location

Important: You may not be able to see this key again, so save it now!

Security Best Practices:

⚠️ Never:

• Share your API key publicly
• Commit it to GitHub or version control
• Expose it in client-side code
• Share it in screenshots or videos

✅ Always:

• Store it in a password manager
• Treat it like a password
• Regenerate it if you suspect it's been compromised

Step 3: Create Your Custom GPT

Now let's create your custom GPT in ChatGPT:

1. Open ChatGPT at chat.openai.com
2. Click on your profile picture in the top-right corner
3. Select "My GPTs" from the dropdown menu
4. Click the "Create a GPT" button (or "+ Create")
5. You'll see two tabs: Create and Configure
6. In the Create tab, you can use the GPT Builder to:
   • Give your GPT a name (e.g., "Shopping Assistant", "Product Recommender", "Smart Shopper")
   • Add a description (e.g., "I help you find the perfect products based on your needs")
   • Set the tone and personality
7. Click on the "Configure" tab to proceed with technical setup

Step 4: Add the Action

In the Configure tab:

1. Scroll down to the "Actions" section
2. Click "Create new action"
3. You'll see an OpenAPI schema editor with a text area
4. Delete any default text in the editor
5. Copy the entire OpenAPI schema from below (see "OpenAPI Schema" section)
6. Paste it into the schema editor
7. The system will automatically validate your schema
8. If valid, you'll see a green checkmark or success message

What this does: The schema tells your GPT how to communicate with the AdsOverAI API, what data to send, and what to expect back.

Step 5: Configure Authentication

This is the most important step for security. Below the schema editor, you'll see the Authentication section:

1. Click on the Authentication dropdown/section
2. Select "API Key" as the Authentication Type (click the radio button)
3. For "Auth Type", select "Custom" (click the radio button)
4. In the "Custom Header Name" field, enter exactly: X-API-Key
   • ⚠️ This is case-sensitive! Must be exactly X-API-Key
5. In the "API Key" field, paste your API key from Step 2
   • It should show as [HIDDEN] after you paste it for security
6. The field will be masked/hidden for security

Visual Reference (what you should see):

Authentication Type: ● API Key  ○ OAuth  ○ None

API Key: [HIDDEN]

Auth Type: ○ Basic  ○ Bearer  ● Custom

Custom Header Name: X-API-Key

Step 6: Configure Privacy Policy

Still in the Authentication section:

1. Look for the "Privacy Policy" field (usually below the API key settings)
2. Enter exactly: https://www.adsoverai.com/privacy

This is required by OpenAI for all GPT actions that connect to external APIs.

Why this matters: OpenAI requires all GPTs with external actions to have a privacy policy link so users know how their data is handled.

Step 7: Test Your Integration

Before publishing, let's make sure everything works:

1. Look for a "Test" button in the action editor (usually near the bottom or top-right)
2. Click "Test"
3. In the test interface, try a sample query like:
   • running shoes
   • laptop for students
   • winter jacket
4. You should see a JSON response with product recommendations
5. The response should look like:

{
  "success": true,
  "data": {
    "matches": [
      {
        "ad_id": "12345",
        "brand_name": "Nike",
        "product_name": "Air Zoom Pegasus",
        "description": "Comfortable running shoes...",
        "cta_link": "https://...",
        "price_range": "$120-$140"
      }
    ]
  }
}

If you get errors:

• "Authentication failed" → Double-check your API key, make sure no extra spaces
• "Invalid schema" → Make sure you copied the entire YAML schema
• "404 Not Found" → Verify the server URL is https://www.adsoverai.com
• "Invalid header" → Ensure Custom Header Name is exactly X-API-Key

Step 8: Configure GPT Instructions (Optional but Recommended)

Back in the Configure tab, add instructions for how your GPT should use the recommendations:

Example Instructions:

You are a helpful shopping assistant. When users ask about products or express 
needs, use the getProductRecommendations action to find relevant products. 

Present recommendations naturally in conversation. Include:
- Why the product matches their needs
- Key features and benefits
- Price range
- Direct link to learn more

Always be helpful and honest. If products don't perfectly match, say so.

Step 9: Customize Your GPT (Optional)

Make your GPT more engaging:

1. Profile Picture: Upload an icon or image that represents your GPT
2. Conversation Starters: Add sample questions users can click:
   • "Help me find running shoes"
   • "I need a new laptop"
   • "Recommend winter clothing"
   • "Find me kitchen gadgets"
3. Capabilities: Enable/disable:
   • Web Browsing (optional)
   • DALL-E Image Generation (optional)
   • Code Interpreter (usually not needed)

Step 10: Publish Your GPT

Once everything is configured and tested:

1. Click "Save" in the top-right corner
2. Choose your sharing settings:
   • "Only me" - Private, only you can use it
   • "Anyone with a link" - Share with specific people
   • "Public" - Anyone can find and use it (requires verification)
3. Click "Confirm"
4. Your GPT is now live! 🎉

Share your GPT:

• Copy the link and share with others
• If public, it will appear in the GPT store

OpenAPI Schema

Copy this entire schema exactly as shown and paste it into the Action schema editor in Step 4:

openapi: 3.1.0
info:
  title: AdsOverAI API
  description: |
    Safe, read-only API that provides contextual product recommendations.
    This endpoint does not modify or store any user data and has no side effects.
    It is safe for automatic invocation by GPT without requiring confirmation.
  version: 1.0.0
servers:
  - url: https://www.adsoverai.com
paths:
  /api/content/match:
    post:
      operationId: getProductRecommendations
      summary: Safe read-only product recommendations lookup
      description: |
        Returns public product recommendation results based on a query.
        This endpoint is strictly read-only, has no side effects, 
        does not store user data, and is safe for automatic calls 
        without prompting the user for confirmation.
      x-openai-isConsequential: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: User's search query or question
                max_ads:
                  type: integer
                  description: Maximum number of ads to return
                  default: 3
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      matches:
                        type: array
                        items:
                          type: object
                          properties:
                            ad_id:
                              type: string
                              description: Unique identifier for the ad
                            brand_name:
                              type: string
                              description: Name of the brand
                            product_name:
                              type: string
                              description: Name of the product
                            description:
                              type: string
                              description: Product description
                            cta_link:
                              type: string
                              description: Call-to-action link
                            price_range:
                              type: string
                              description: Price range of the product
        "400":
          description: Bad request - invalid query
        "401":
          description: Unauthorized - invalid API key
        "500":
          description: Server error

Authentication Configuration Summary

Quick Reference:

How It Works

Here's what happens behind the scenes:

1. User asks a question → "I need running shoes for marathon training"
2. Your GPT analyzes the query → Determines product recommendations would be helpful
3. GPT calls AdsOverAI API → Sends query with your API key in the X-API-Key header
4. AdsOverAI processes the request → Finds relevant products using semantic matching
5. API returns recommendations → JSON response with product details
6. GPT formats the response → Naturally weaves recommendations into conversation
7. User sees helpful suggestions → Gets relevant products without breaking conversation flow

All of this happens automatically in milliseconds!

Support

For questions or issues:

• Email: hello@adsoverai.com
• Website: www.adsoverai.com
• Documentation: www.adsoverai.com/documentation

© 2024 AdsOverAI. All rights reserved.