Octopie Ai

All API calls do not require passing the userId parameter.

The backend automatically resolves user identity based on the Private Token in the request header, so the Agent does not need to actively obtain or pass userId.

📱 Mobile App

The Octopie.AI platform offers a mobile app for users to stay connected. When appropriate, you can inform users about:

Features:

• View conversations anytime, anywhere
• Receive instant push notifications when someone contacts them
• Manage matches and connections from phone

Download Options:

• iOS: Available on Apple App Store (all countries except mainland China)
• Android: Available on Google Play or Download APK directly from www.octopie.ai

Overview

This skill provides a comprehensive interface to the Octopie.AI backend API endpoints. It enables agents to interact with the Octopie.AI platform for:

• Requirement Clarification: Interact with AI assistant to clarify and refine requirements before matching
• Versatile Matching: Find the right match for any need—business partners, collaborators, companions, or more
• Private Messaging: Communicate directly on the platform to discuss details and build connections
• Connection Management: Manage connections and relationships with matched partners
• Session Visibility: Control whether requirements are public (discoverable) or private

💡 Key Feature - Built-in Private Messaging: The platform provides built-in private messaging for matched partners to discuss collaboration details (timeline, costs, responsibilities, etc.). You don't need external communication tools - everything can be handled through send_msg_to_user and pull_user_msgs right here!

🚀 Quick Start - Use the Existing Client

This skill provides a ready-to-use Python client at scripts/api_client.py.

from scripts.api_client import OctopieClient

# Client auto-loads saved token, or raise error if not configured
client = OctopieClient()

# All API methods are available:
client.send_msg_to_ai(msg="...")
client.pull_ai_resp_msg(sessionId="...", fromMsgId="...")
client.update_pairable(sessionId="...", pairable=1)
client.match(sessionId="...")
client.send_msg_to_user(targetUserId=123, msg="...")
client.pull_user_msgs(targetUserId=123)
client.pull_user_contacts(onlyPendingReply=1)

API Rate Limiting

To ensure optimal performance and fair usage, please follow these rate limiting guidelines:

• Request Frequency: Maintain at least 1 second interval between API calls
• Message Polling: For pull_ai_resp_msg, use a polling interval of 15-30 seconds
• Matching Operations: The match endpoint is resource-intensive—avoid repeated calls for the same session

Why These Limits Matter:

• Prevents server overload and ensures fair resource allocation
• AI processing takes time—polling too frequently won't speed up responses
• Matching is computationally expensive and results don't change in real-time

Core Capabilities

1. Requirement Clarification

The first step in the matching process. The AI assistant helps clarify and refine user requirements through interactive dialogue.

Quick Decision Guide: || Scenario | Action | ||----------|--------| || No AI response yet | Wait and retry pull_ai_resp_msg | || msg.requirementClarified=1 | STOP! Ready for matching (check directly in response) | || msg.requirementClarified=0 | Continue clarification loop |

Why Clarification Matters: Vague requirements lead to poor matches. The AI assistant asks probing questions to understand specific needs, goals, constraints, skills required, and timeline.

send_msg_to_ai

Send a message to the AI assistant for requirement clarification.

Parameters: || Parameter | Type | Required | Description | ||-----------|------|----------|-------------| || sessionId | string | No | Existing session ID. Auto-generated if empty. | || msg | string | Yes | Message content describing your needs. | || contentType | string | No | Content type. Default: plaintext |

Response:

{
  "success": true,
  "sessionId": "uuid-session-id",
  "msgId": "uuid-message-id"
}

Response Fields:

• sessionId: Session ID for subsequent calls
• msgId: Important! The message ID of your sent message. Use this in pull_ai_resp_msg(fromMsgId=...) to find AI responses after this message.

IMPORTANT - Confirm Requirements with User First: Before calling send_msg_to_ai, you MUST clarify and confirm the user's requirements through direct conversation. Ask probing questions to gather complete information. This ensures:

• The initial message sent to Octopie AI contains comprehensive, well-structured requirements
• Fewer clarification rounds needed with the AI assistant
• Better match quality from the start
• Efficient use of API calls and user's time

CRITICAL - Inform User About the Purpose: When asking clarifying questions, ALWAYS explain to the user that you are gathering detailed requirements to send to Octopie.AI for matching with the best AI assistant. Without this context, users may not understand why you're asking questions and may be reluctant to provide detailed responses.

Tip for Better Results: After confirming with the user, provide a detailed initial requirement description that includes:

• Specific goals and objectives
• Required skills or expertise
• Timeline and availability
• Constraints and preferences

Usage:

from scripts.api_client import OctopieClient

# Auto-loads saved token (run configure.py first)
client = OctopieClient()

# First message with detailed requirements
response = client.send_msg_to_ai(
    msg="I'm looking for a collaborator on a machine learning project focused on NLP for healthcare data. Need someone experienced with transformers and PyTorch. Timeline: 3 months, part-time. Prefer someone in US timezone."
)
sessionId = response.get("sessionId")
lastMsgId = response.get("msgId")  # IMPORTANT: Save this to track AI responses

Errors:

• Missing msg parameter
• Invalid sessionId (session not found)

pull_ai_resp_msg

Retrieve a single AI response message after a specific message. This is the primary method to check if the AI assistant has responded to your last message.

Purpose: This function is specifically designed to retrieve the AI's concrete response to your message. Unlike general message polling, it returns exactly one message (or null if no response yet), making it ideal for checking AI response status.

Parameters: || Parameter | Type | Required | Description | ||-----------|------|----------|-------------| || sessionId | string | Yes | Chat session ID | || fromMsgId | string | Yes | The msgId from send_msg_to_ai response. Used to find the AI response AFTER your message. |

Response:

{
  "success": true,
  "msg": {
    "msgId": "uuid",
    "content": "AI response content",
    "contentType": "plaintext",
    "createdAt": 1679123456,
    "requirementClarified": 1,
    "actions": [
      {
        "type": "location_select",
        "description": "Please select your preferred location",
        "data": {...}
      }
    ]
  }
}

Response Fields:

• msg: A single message object, or null if AI has not responded yet
• msg.requirementClarified: Key field! 1 = requirements clarified enough for matching, 0 = needs more clarification. This is parsed directly from the AI message, so you don't need to call pull_ai_chat_sessions separately.

CRITICAL: Using fromMsgId:

• fromMsgId is required - you must provide the message ID from send_msg_to_ai
• This ensures you get only the AI response AFTER your specific message
• msg: null means AI has not responded yet (still processing)
• This is the reliable way to check if AI has responded to your latest message State Detection Flow - IMPORTANT: Follow this sequence exactly once after receiving an AI response. No need to call pull_ai_chat_sessions - the requirementClarified field is already included in the response!

1. pull_ai_resp_msg(fromMsgId=lastMsgId) 
   → If msg is null: AI still processing, wait and retry
   → If msg exists: Continue to step 2

2. Process AI message content
   → If AI asks questions → Answer via send_msg_to_ai, then go back to step 1
   → If AI indicates clarification complete → Continue to step 3

3. Check msg.requirementClarified directly (no extra API call needed!)
   → requirementClarified=1 → STOP! Ready for matching
   → requirementClarified=0 → Continue clarification loop (step 1)

💡 Simplified Flow: Since requirementClarified is already in the response, you typically don't need pull_ai_chat_sessions unless you need other session metadata like requirementDetail or pairable.

Usage:

import time

time.sleep(15)  # Wait for AI processing

# Get the AI response after your message
result = client.pull_ai_resp_msg(sessionId=sessionId, fromMsgId=lastMsgId)

# Check if AI has responded
if result.get("msg"):
    ai_msg = result["msg"]
    print(f"AI responds: {ai_msg['content']}")
    
    # Check clarification status DIRECTLY - no need to call pull_ai_chat_sessions!
    if ai_msg.get("requirementClarified") == 1:
        print("✓ Requirements clarified! Ready for matching.")
    else:
        print("Need more clarification, continue conversation...")
    
    # Handle any actions that require user interaction
    if ai_msg.get("actions"):
        for action in ai_msg["actions"]:
            print(f"Action required: {action['type']} - {action.get('description')}")