Introduction

The ProbeDots API offers developers a comprehensive platform to integrate conversational AI capabilities and service and product recommendations into their applications. This documentation aims to help you understand how to set up and use this API effectively.

Step-by-step guide for new users

1. Registration and obtaining API keys:

   • Visit the ProbeDots website and create an account to obtain your unique API key. This key is necessary to authenticate your application when making requests to the API.

2. Basic configuration:

   • Whenever possible, store your API keys securely in your environment (avoid direct exposure in client-side code). Example configuration in Node.js with environment variables:

   // .env file
   PROBEDOTS_API_KEY=your_unique_api_key
   
   // Accessing the environment variable in your application
   const apiKey = process.env.PROBEDOTS_API_KEY;
   

3. Making API calls:

   • Start with a simple API call. For example, to create a token:

   fetch('<https://app.probedots.com/api/v1/tokens/>', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${apiKey}`,
     },
   })
   .then(response => response.json())
   .then(data => console.log(data))
   .catch(error => console.error('Error:', error));
   

   • Make sure to handle responses and errors appropriately.

Detailed API Reference

Overview

This section provides a detailed reference for all available endpoints, including request methods, parameters, and response objects. Use it as your main resource for understanding how to interact with the ProbeDots API.

API Endpoints

1. Create a token

   • Endpoint: /api/v1/tokens
   • Method: POST
   • Request headers:
     • Content-Type: application/json
     • Authorization: Bearer <API-KEY>
   • Response object:

   {
     "token": "eyJhbGciOiJIUzI1NiJ9.eyJjb21wYW55X2lkIjoxLCJleHAiOjE3MjkxMTkxMTl9.dK0ERi5uTJXQwl2uqdrrFaEDI3qSReKbLgBClCgwk7U"
   }
   

2. Create a chat session

   • Endpoint: /api/v1/chats
   • Method: POST
   • Request headers:
     • Content-Type: application/json
     • Authorization: Bearer <token>
   • Request parameters:

   {
     "chatter_info": "string", // optional
     "chatter_external_id": "string" // optional
   }
   

   • Response object:

   {
     "chat_id": "string",
     "greeting": "Greetings! How can I help you today?",
     "suggestions": {
         "suggestion_1": "I'm looking for a smartphone",
         "suggestion_2": "I'm looking for a laptop",
         // ... up to 5 suggestions from company settings
     }
   }
   

3. Send a message to a chat

   • Endpoint: /api/v1/chats/{chatId}/messages
   • Method: POST
   • Request headers:
     • Content-Type: application/json
     • Authorization: Bearer <token>
   • Request parameters:

   {
     "message": {
       "content": "string",
       "role": "20" // user message
     }
   }
   

   • Response object:

   {
     "content": "string", // message answer
     "no_products_available": true, // if no products returned after AI product query
     "product1_name": "string", // if product1 provided by AI
       "product1_link": "string",
       "product1_image": "string",
       "product1_details": {
           "brand": "Dell",
           "price": "1641.16",
           // ... all other product details available in Probedots
       },
      "product2_name": "string", // if product2 provided by AI
      // ... product 3
   }
   

4. Retrieve an AI post-recommendation comment

   • Get a comment from AI to let users know why the provided recommendations are great
   • Endpoint: /api/v1/chats/{chatId}/messages
   • Method: POST
   • Request headers:
     • Content-Type: application/json
     • Authorization: Bearer <token>
   • Request parameters:

   {
     "message": {
       "content": "run_ai_comment", //must use this exact string
       "role": "0" // system message
     }
   }
   

   • Response object:

   {
     "content": "string", // message answer
   }
   

5. Retrieve chat history

   • Endpoint: /api/v1/chats/{chatId}/load_chat
   • Method: GET
   • Request headers:
     • Authorization: Bearer <token>
   • Response object:

   {
       "chat_id": {chatId},
       "items": [
           {
               "type": "message",
               "role": "assistant",
               "content": "You're here! Let's make your wallet (and the planet) happy with some killer deals",
               "created_at": "2024-10-16T21:13:25.568Z"
           },
           {
               "type": "message",
               "role": "user",
               "content": "I'm looking for a smartphone",
               "created_at": "2024-10-16T21:13:28.613Z"
           },
           {
               "type": "message",
               "role": "assistant",
               "content": "",
               "created_at": "2024-10-16T21:13:47.106Z"
           },
           {
               "type": "recommendation",
               "product_name": "iPhone 14 Plus",
               "product_link": "product_link",
               "product_image": "product_image",
               "product_details": {
                   "brand": "Apple",
                   /// product details
               },
               "original_prompt": "user need summed up by the AI",
               "created_at": "2024-10-16T21:13:52.326Z"
           }
           /// other messages and product/content recommendations
       ]
   }
   

6. Retrieve a chatter's conversation

   • Endpoint: /api/v1/chatters/load_chat?external_id={chatter_id}&chat_id={chat_id}
   • Note: chat_id is optional, the default will return the chatter's last chat
   • Method: GET
   • Request headers:
     • Authorization: Bearer <token>
   • Response object:

   {
       "chat_id": {chatId},
       "items": [
           {
               "type": "message",
               "role": "assistant",
               "content": "You're here! Let's make your wallet (and the planet) happy with some killer deals",
               "created_at": "2024-10-16T21:13:25.568Z"
           },
           {
               "type": "message",
               "role": "user",
               "content": "I'm looking for a smartphone",
               "created_at": "2024-10-16T21:13:28.613Z"
           },
           {
               "type": "message",
               "role": "assistant",
               "content": "",
               "created_at": "2024-10-16T21:13:47.106Z"
           },
           {
               "type": "recommendation",
               "product_name": "iPhone 14 Plus",
               "product_link": "product_link",
               "product_image": "product_image",
               "product_details": {
                   "brand": "Apple",
                   /// product details
               },
               "original_prompt": "user need summed up by the AI",
               "created_at": "2024-10-16T21:13:52.326Z"
           }
           /// other messages and product/content recommendations
       ]
   }