Skip to main content

The Complete Guide to Calling an Optimly Agent Using cURL

· 4 min read
Daniel Garcia
Daniel Garcia
CEO @ Optimly

Your first integration with Optimly, fully explained from zero to production.

Introduction​

Before integrating Optimly with WhatsApp, websites, CRMs, automation platforms, or custom backends, the most reliable and diagnostic-first step is to test your setup using a simple HTTPS request.

The quickest tool for this is cURL, available in every Unix environment (macOS, Linux, WSL, and even Git Bash on Windows). This single step helps you verify that:

  • Your API key works
  • Your agent is configured correctly
  • The network connection is valid
  • Optimly is receiving, processing, and logging messages
  • The dashboard is updating in real time
  • The OpenAPI contract is understood correctly

In this guide, we will go deep into:

  • Understanding the endpoint
  • Authentication methods
  • Creating new chats vs. continuing existing ones
  • Structuring payloads correctly
  • Handling errors
  • Viewing stored analytics
  • Real-world debugging tips

This article is fully standalone and does not require reading any other guide.

1. Understanding the Optimly Message Flow​

Optimly exposes a clean external API consisting primarily of:

  • Chat creation → POST /external/chat
  • Sending user messages → POST /external/message/new-message
  • Requesting agent responses → POST /external/agent

All three ultimately feed into the Optimly analytics engine, storing:

  • Sentiment
  • Emotion
  • Toxicity
  • Word count
  • Intent detection
  • Topic classification
  • Flags
  • Response latency
  • Token usage (if applicable)

Before calling the agent through cURL, it’s crucial to understand the two main interaction patterns.

Pattern A — Fire-and-Forget Agent Call (Simplest)​

You directly request:

POST /external/agent

Passing:

  • a chat_id
  • the user’s message (content)
  • your authentication token

Optimly will:

  • load (or create) the conversation internally
  • generate a model response
  • log everything

This is perfect for quick validations, prototyping, and testing integration layers.

Pattern B — Manual Chat Creation + Messages​

For more advanced use cases (WhatsApp, email, multi-channel routing), you may:

  • Create a chat via /external/chat
  • Append messages with /external/message/new-message
  • Trigger the agent via /external/agent

But for this guide, we keep it simple and use Pattern A.

2. The Endpoint You Will Use​

According to the OpenAPI file (v3.yaml), the main endpoint is:

POST /external/agent

Request Body Specification (AgentExecutor)​

AgentExecutor:
  properties:
    chat_id: string (required)
    content: string (required)

Response Structure (AgentResponse)​

You will receive:

AgentResponse:
  response: string
  content: string
  tool_data: object|null
  execution_time: number|null
  success: boolean|null
  error: string|null
  language_detected: string|null
  tools_executed: integer|null
  performance_optimized: boolean|null
  framework: string|null

This returns both functional output (the agent’s reply) and diagnostic metadata.

3. Authentication Methods​

Optimly supports three equally valid authentication methods:

  1. Header: x_api_key

    x_api_key: <your API key here>

    Recommended for most server-to-server integrations.

  2. Header: Authorization: Bearer <token>

    Authorization: Bearer <your token>

    Useful when integrating Optimly behind middlewares.

  3. Query Parameter: ?access_token_query=<token>

    Useful for no-code tools (Make.com, n8n) or URL-based routing.

For this article, we’ll use x_api_key.

4. Create Your API Key​

In Optimly:

Dashboard → API Keys → Create Key

Save it:

export OPTIMLY_API_KEY="your-key-here"

5. Sending Your First cURL Request​

This is the simplest possible request:

curl -X POST "https://api.optimly.io/external/agent" \
  -H "Content-Type: application/json" \
  -H "x_api_key: $OPTIMLY_API_KEY" \
  -d '{
        "chat_id": "demo_chat_001",
        "content": "Hello Optimly, I am testing the cURL integration."
      }'

What happens internally​

  • Optimly receives the message
  • It fetches your agent configuration
  • It generates an LLM response
  • It logs:
    • message
    • metadata
    • analytics
    • timing
    • any tool execution
  • It returns JSON immediately
  • The dashboard updates instantly

6. Example Successful Response​

Below is a real example structure, based on OpenAPI:

{
  "response": "Hello! How can I help you today?",
  "content": "Hello! How can I help you today?",
  "execution_time": 1.12,
  "success": true,
  "language_detected": "english",
  "tools_executed": 0,
  "performance_optimized": true,
  "framework": "legacy"
}

Key fields:

  • response → always trust this field (canonical output)
  • execution_time → latency in seconds
  • language_detected → used for analytics segmentation
  • framework → shows which internal pipeline handled the query

7. Viewing the Conversation in the Optimly Dashboard​

Open:

Dashboard → Agents → Conversations

You will see:

  • The chat ID
  • All messages
  • Message-level metrics
  • Flags
  • Sentiment & toxicity
  • Intent & topic
  • Response times
  • Full chronological flow

This confirms your integration works end-to-end.

8. Continuing the Conversation (Append Message)​

To send message #2, you use:

POST /external/message/new-message

Example:

curl -X POST "https://api.optimly.io/external/message/new-message" \
  -H "Content-Type: application/json" \
  -H "x_api_key: $OPTIMLY_API_KEY" \
  -d '{
        "chat_id": "demo_chat_001",
        "sender": "user",
        "content": "Can you explain your pricing?"
      }'

This adds the message to the conversation timeline.

9. Creating a New Chat via API (Optional but Useful)​

POST /external/chat

Example:

curl -X POST "https://api.optimly.io/external/chat" \
  -H "Content-Type: application/json" \
  -H "x_api_key: $OPTIMLY_API_KEY" \
  -d '{
        "client_id": "customer_001",
        "ai_enabled": true,
        "lead_collected": false
      }'

This returns a fresh chat_id that you can pass into /external/agent.

10. Debugging Common Errors​

  • 401 – Not authenticated Your key is missing or invalid.

  • 403 – Forbidden Your key is valid, but it doesn't belong to the agent.

  • 422 – Validation Error Your request body does not match the schema.

    Check:

    • chat_id (required)
    • content (required)
    • JSON formatting

  • 500 – Internal Server Error Usually indicates:

    • malformed payload
    • agent misconfiguration
    • upstream provider downtime

    Retry with a simpler message.

11. Advanced Usage Tips​

Tip 1 — Chat IDs can be client-specific​

Use deterministic chat IDs for omnichannel integrations:

  • whatsapp_<phone_number>
  • email_<thread_id>
  • web_<session_id>

This keeps conversations unified across multiple platforms.

Tip 2 — You can pass the key via Query Params​

Useful for no-code platforms:

https://api.optimly.io/external/agent?access_token_query=<key>

Tip 3 — You can store external IDs​

When creating chats, external_id allows:

  • CRM contact IDs
  • Email thread IDs
  • WhatsApp sender IDs

This enables cross-channel tracking.

12. Full Example: End-to-End Conversation Flow​

Step 1 — Create Chat​

curl -X POST "https://api.optimly.io/external/chat" \
  -H "Content-Type: application/json" \
  -H "x_api_key: $OPTIMLY_API_KEY" \
  -d '{
        "client_id": "customer001"
      }'

Step 2 — Send User Message​

curl -X POST "https://api.optimly.io/external/agent" \
  -H "Content-Type: application/json" \
  -H "x_api_key: $OPTIMLY_API_KEY" \
  -d '{
        "chat_id": "customer001",
        "content": "I need help with my order."
      }'

Step 3 — Append Next User Message​

curl -X POST "https://api.optimly.io/external/message/new-message" \
  -H "Content-Type: application/json" \
  -H "x_api_key: $OPTIMLY_API_KEY" \
  -d '{
        "chat_id": "customer001",
        "sender": "user",
        "content": "Is it possible to change the delivery address?"
      }'

Optimly will:

  • Log each message
  • Generate analytics
  • Produce insights
  • Keep full history visible

13. Conclusion​

With this single endpoint and a few lines of cURL, you can fully validate your Optimly integration. This is the foundation for:

  • WhatsApp automation
  • Webchat deployments
  • CRM interaction tracking
  • Multi-agent routing
  • Lead scoring
  • Analytic dashboards
  • RAG systems
  • Sales and support automation

Everything begins with this first message.