Skip to main content

External API Overview

The Optimly External API provides a comprehensive set of endpoints for integrating AI-powered chat agents into your applications. These APIs are designed to be publicly accessible with proper authentication and enable seamless communication between your users and Optimly agents.

Base URL​

https://api.optimly.io

Authentication​

All external API endpoints require authentication using an Agent Access Token. This token can be provided in two ways:

Authorization: Bearer YOUR_AGENT_ACCESS_TOKEN

2. Query Parameter​

GET /external/agent/v2?access_token_query=YOUR_AGENT_ACCESS_TOKEN

API Endpoints Overview​

🤖 Agent Interaction​

💬 Chat Management​

📝 Message Handling​

🛠️ Tools & Actions​

Quick Start Example​

Here's a simple example of how to interact with the Optimly API:

// 1. Create a new chat
const chatResponse = 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 chat = await chatResponse.json();

// 2. Send a message to the agent
const messageResponse = 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: chat.chat_id,
    content: 'Hello! How can you help me today?'
  })
});

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

Response Format​

All API endpoints return JSON responses with the following structure:

Success Response​

{
  "success": true,
  "data": {
    // Endpoint-specific data
  }
}

Error Response​

{
  "success": false,
  "error": "Error message",
  "detail": "Detailed error description"
}

Rate Limits​

  • 100 requests per minute per access token
  • 1000 requests per hour per access token

Integration Examples​

Website Chat Widget​

Perfect for adding AI chat to your website or web application.

Mobile Applications​

Native iOS and Android apps can integrate using standard HTTP requests.

Customer Support Systems​

Integrate with existing support platforms for seamless handoffs.

WhatsApp Business​

Connect your WhatsApp Business account for automated responses.

Next Steps​

  1. Get Started - Learn the basics of the Optimly API
  2. Agent Setup - Start with the enhanced agent endpoint
  3. Chat Management - Understand how to manage conversations
  4. Tools Integration - Add lead capture and appointment booking

Support​

Need help? Contact our support team at support@optimly.io.