Quickstart

Send your first AI message in under 5 minutes.

This guide will walk you through creating a bot, sending a message, and getting an AI response. You'll see how easy it is to integrate AI conversations into your platform.

Prerequisites

• An API key from app.prioros.com (see Making an API Key)
• An HTTP client (requests, axios, fetch, etc.)

Step 1: Create a Bot

You can create bots through the dashboard or via the API. Here's how to create one via API:

import requests

API_KEY = "sk_your_api_key_here"
BASE_URL = "https://api.prioros.com/v3"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create a bot
response = requests.post(
    f"{BASE_URL}/api/bots",
    headers=headers,
    json={
        "name": "Fitness Coach Miami",
        "freeform": "You're a 28-year-old fitness trainer from Miami. You're energetic, motivating, and passionate about helping people reach their health goals. You love beach workouts and healthy smoothies.",
        "attributes": [
            {"name": "bio", "value": "Certified personal trainer specializing in HIIT and nutrition"},
            {"name": "age", "value": "28"},
            {"name": "location", "value": "Miami, FL"},
            {"name": "job", "value": "Personal Trainer"},
            {"name": "interests", "value": "fitness, nutrition, beach volleyball"},
            {"name": "personality", "value": "energetic, motivating, friendly"}
        ]
    }
)

bot = response.json()['bot']
bot_id = bot['id']
print(f"✅ Bot created! ID: {bot_id}")

The freeform field defines your bot's personality in natural language. The attributes array can contain any name-value pairs you want - the AI uses them to understand your bot's characteristics. Common attributes include:

• bio - Short biography or description
• age, location, job - Basic demographics
• personality, interests, hobbies - Character traits
• relationship_status, height, body_type - For dating platforms
• Anything else relevant to your use case!

Step 2: Create a Conversation

Create a conversation between the bot and a user:

# Create a conversation
response = requests.post(
    f"{BASE_URL}/api/conversations",
    headers=headers,
    json={
        "bot_id": bot_id,
        "user_id": "user_sarah_m",
        "create_user_if_not_exists": True  # Auto-create the user if needed
    }
)

conversation = response.json()['conversation']
conversation_id = conversation['id']
print(f"✅ Conversation created! ID: {conversation_id}")

Step 3: Send a Message

Now send a message in the conversation:

# Send a message from the user
response = requests.post(
    f"{BASE_URL}/api/conversations/{conversation_id}/messages",
    headers=headers,
    json={
        "message": {
            "text": "Hey! How are you?",
            "from_bot": False  # False = message from user, True = from bot
        }
    }
)

print(f"✅ Message sent! The AI is generating a response...")

The API processes the message asynchronously and the bot will respond automatically.

Step 4: Set Up Webhooks to Receive Responses

Configure a webhook URL to receive bot messages in real-time:

# Create a conversation with webhook
response = requests.post(
    f"{BASE_URL}/api/conversations",
    headers=headers,
    json={
        "bot_id": bot_id,
        "user_id": "user_sarah_m",
        "create_user_if_not_exists": True,
        "webhook": "https://webhook.site/your-unique-url"  # Get a URL from webhook.site
    }
)

conversation = response.json()['conversation']
conversation_id = conversation['id']
print(f"✅ Conversation created with webhook!")

# Example Flask webhook handler
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    data = request.json
    # Process the conversation data...
    return '', 200  # Must return 200!

When you send a message, the bot's response will be POSTed to your webhook URL automatically. The webhook receives the full conversation object including all messages.

What's Happening Behind the Scenes?

When you create a conversation and send messages:

1. The conversation links the user and bot together (one conversation per user-bot pair)
2. When you send a message, it's added to the conversation history
3. The AI analyzes the bot's personality (freeform and attributes) and conversation context
4. The AI generates a response automatically
5. The response is added to the conversation
6. If you configured a webhook, you're notified immediately when new messages arrive

Next Steps

Production Tips

Alternative: Polling Example

If you prefer not to use webhooks, you can poll the conversation endpoint to receive messages.