External API Quick Reference

Need to integrate Optimly's AI agents into your application? This quick reference helps you get started with the most commonly used endpoints.

🚀 Get Started in 3 Steps

1. Get Your Access Token

Find your agent access token in the Optimly dashboard under Agent Settings → API Access.

2. Create a Chat Session

const chat = await fetch('https://api.optimly.io/external/message/new-chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_id: 'user_123'
  })
});

const chatData = await chat.json();
const chatId = chatData.chat_id; // Save this for future messages

3. Send Messages

const response = await fetch('https://api.optimly.io/external/agent/v2', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    chat_id: chatId,
    content: 'Hello! How can you help me today?'
  })
});

const data = await response.json();
console.log('Agent response:', data.response);

📋 Common Endpoints

Endpoint	Method	Purpose
/external/agent/v2	POST	Send messages to your agent
/external/message/new-chat	POST	Create new chat sessions
/external/chat/{chat_id}/messages	GET	Get conversation history
/external/tools/lead-form	POST	Capture lead information
/external/tools/appointment	POST	Schedule appointments
/external/tools/email-handoff	POST	Transfer to human support

🔗 Complete Documentation

For detailed guides, examples, and best practices:

📖 View Complete External API Documentation →

Key Sections

• 🤖 Agent Interaction - Enhanced messaging with automatic tools
• 💬 Chat Management - Create and manage conversations
• 🛠️ Tools & Actions - Lead capture, appointments, and handoffs
• 🔐 Authentication - Security and best practices
• 📝 Message Handling - Advanced message management

⚡ Framework Examples

React Hook

import { useState, useCallback } from 'react';

function useOptimlyChat(accessToken, clientId) {
  const [chatId, setChatId] = useState(null);
  
  const createChat = useCallback(async () => {
    const response = await fetch('/external/message/new-chat', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ client_id: clientId })
    });
    
    const data = await response.json();
    setChatId(data.chat_id);
    return data.chat_id;
  }, [accessToken, clientId]);
  
  const sendMessage = useCallback(async (content) => {
    if (!chatId) throw new Error('No active chat');
    
    const response = await fetch('/external/agent/v2', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        chat_id: chatId,
        content
      })
    });
    
    return await response.json();
  }, [accessToken, chatId]);
  
  return { chatId, createChat, sendMessage };
}

Python Client

import requests

class OptimlyClient:
    def __init__(self, access_token):
        self.access_token = access_token
        self.base_url = 'https://api.optimly.io'
        self.headers = {
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json'
        }
    
    def create_chat(self, client_id):
        response = requests.post(
            f'{self.base_url}/external/message/new-chat',
            headers=self.headers,
            json={'client_id': client_id}
        )
        return response.json()
    
    def send_message(self, chat_id, content):
        response = requests.post(
            f'{self.base_url}/external/agent/v2',
            headers=self.headers,
            json={
                'chat_id': chat_id,
                'content': content
            }
        )
        return response.json()

# Usage
client = OptimlyClient('your_access_token')
chat = client.create_chat('user_123')
response = client.send_message(chat['chat_id'], 'Hello!')
print(response['response'])

PHP Example

<?php
class OptimlyClient {
    private $accessToken;
    private $baseUrl = 'https://api.optimly.io';
    
    public function __construct($accessToken) {
        $this->accessToken = $accessToken;
    }
    
    public function createChat($clientId) {
        return $this->makeRequest('/external/message/new-chat', [
            'client_id' => $clientId
        ]);
    }
    
    public function sendMessage($chatId, $content) {
        return $this->makeRequest('/external/agent/v2', [
            'chat_id' => $chatId,
            'content' => $content
        ]);
    }
    
    private function makeRequest($endpoint, $data) {
        $curl = curl_init();
        curl_setopt_array($curl, [
            CURLOPT_URL => $this->baseUrl . $endpoint,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode($data),
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->accessToken,
                'Content-Type: application/json'
            ]
        ]);
        
        $response = curl_exec($curl);
        curl_close($curl);
        return json_decode($response, true);
    }
}

// Usage
$client = new OptimlyClient('your_access_token');
$chat = $client->createChat('user_123');
$response = $client->sendMessage($chat['chat_id'], 'Hello!');
echo $response['response'];
?>

🎯 Use Cases

Website Chat Widget

Add AI-powered chat to your website for customer support and lead generation.

Mobile App Integration

Integrate conversational AI into iOS and Android applications.

Customer Support Portal

Enhance existing support systems with intelligent automation.

WhatsApp Business

Connect WhatsApp Business API for automated customer interactions.

E-commerce Assistance

Provide product recommendations and order support.

🔧 Tools & Automation

Optimly agents can automatically:

• Capture leads when users provide contact information
• Schedule appointments when users mention meetings or dates
• Transfer to human support for complex queries
• Provide personalized responses based on your knowledge base

📞 Support

Need help integrating?

• 📚 Complete Documentation - Comprehensive guides and examples
• 💬 Community Support - Connect with other developers
• 📧 Email Support - Direct technical assistance
• 🎥 Video Tutorials - Step-by-step integration guides

🚦 Rate Limits

• 100 requests per minute per access token
• 1000 requests per hour per access token
• Burst allowance: 20 requests in 10 seconds

Monitor the X-RateLimit-* headers in API responses to track your usage.

---

Ready to get started? → View Complete API Documentation