Skip to main content

External API Quick Reference

Need to integrate your Optimly AI Employee 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/v3', {
  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​

EndpointMethodPurpose
/external/agent/v3POSTSend messages to your agent (optimized default)
/external/agent/v2POSTLegacy compatibility for existing integrations
/external/agent/available-toolsGETList the tools enabled for your agent
/external/agent/v2/test-toolsPOSTValidate or debug individual tools
/external/message/new-chatPOSTCreate new chat sessions
/external/message/new-messagePOSTAppend a message/lead/appointment to a chat
/external/message/email-handoffPOSTTransfer to human support
/external/chat/{chat_id}/messagesGETGet conversation history
Compatibility

/external/agent/v3 is the optimized default for messaging, while /external/agent/v2 remains available for backwards-compatible clients and tool testing via /external/agent/v2/test-tools.

🔗 Complete Documentation​

For detailed guides, examples, and best practices:

📖 View Complete External API Documentation →

Key Sections​

⚡ 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/v3', {
      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/v3',
            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/v3', [
            '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?

🚦 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