API Documentation

Getting Started

The Replyza API lets you embed an AI-powered chatbot on any website, manage conversations, capture leads, and configure the widget's appearance — all programmatically.

Authentication

Every API request is authenticated with your API key. You can find (or regenerate) this key in your Dashboard → Settings. Pass it as the key query parameter (GET) or in the JSON body (POST).

Base URL

https://replyza.io

Widget Installation

Add a single script tag to your site and Replyza handles the rest. Paste the following snippet just before the closing </body> tag:

<script
  src="https://replyza.io/widget.js"
  data-key="YOUR_API_KEY"
  async
></script>

• Replace YOUR_API_KEY with your actual key from Settings.
• The widget appears as a floating chat button in the corner of the page.
• Works on any website — HTML, React, Shopify, WordPress, Webflow, Squarespace, and more.
• The script loads asynchronously so it won't block your page rendering.

Widget Configuration API

Retrieve the current configuration for your chatbot widget. Useful if you're building a custom integration.

Response

{
  "chatbot_name": "Your Bot",
  "brand_color": "#F97316",
  "welcome_msg": "Hi! How can I help?",
  "placeholder_text": "Ask a question...",
  "logo_url": null,
  "show_powered_by": true,
  "widget_position": "bottom-right",
  "lead_capture_enabled": false,
  "message_limit": 1000,
  "quick_prompts": [],
  "widget_theme": "dark",
  "border_radius": 16,
  "font_family": null,
  "show_timestamps": false
}

Chat API

Send a message and receive an AI-generated response. Pass previous messages in the messages array to maintain conversation context.

Request body

{
  "key": "YOUR_API_KEY",
  "messages": [
    { "role": "user", "content": "What products do you sell?" }
  ],
  "visitor_id": "v_unique_visitor_id",
  "page_url": "https://yoursite.com/shop",
  "conversation_id": "optional-uuid-for-continuing-conversations"
}

Response

{
  "conversation_id": "uuid",
  "message": "We sell a wide range of...",
  "message_id": "uuid",
  "sources": [
    {
      "url": "https://yoursite.com/products",
      "title": "Our Products",
      "similarity": 0.87
    }
  ]
}

Lead Capture API

Capture visitor contact information during a conversation. Enable lead capture in your dashboard to prompt visitors automatically, or call this endpoint directly.

Request body

{
  "key": "YOUR_API_KEY",
  "conversation_id": "uuid",
  "visitor_id": "v_unique_visitor_id",
  "email": "visitor@example.com",
  "name": "John Doe",
  "page_url": "https://yoursite.com/pricing"
}

Message Feedback API

Allow visitors to rate individual bot responses. Feedback is visible in your dashboard and helps improve response quality over time.

Request body

{
  "key": "YOUR_API_KEY",
  "message_id": "uuid",
  "feedback": "up"
}

Valid feedback values: "up" or "down"

Webhooks

Configure a webhook URL in Settings to receive real-time notifications when events occur.

• Events: conversation.created, lead.captured
• Each event sends a POST request with a JSON body containing event, timestamp, and data.
• Includes the X-Replyza-Event header with the event name.

conversation.created

{
  "event": "conversation.created",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "conversation_id": "uuid",
    "visitor_id": "v_unique_visitor_id",
    "page_url": "https://yoursite.com/pricing",
    "first_message": "Hi, I have a question about pricing."
  }
}

lead.captured

{
  "event": "lead.captured",
  "timestamp": "2025-01-15T10:32:00.000Z",
  "data": {
    "conversation_id": "uuid",
    "visitor_id": "v_unique_visitor_id",
    "email": "visitor@example.com",
    "name": "John Doe",
    "page_url": "https://yoursite.com/pricing"
  }
}

Rate Limits

API requests are rate-limited per plan. When the limit is exceeded, the API responds with HTTP 429.

Error Codes

The API uses standard HTTP status codes. Below are the most common ones you may encounter.

Platform Guides

<!-- Replyza Chat Widget -->
<script
  src="https://replyza.io/widget.js"
  data-key="YOUR_API_KEY"
  async
></script>
</body>

<!-- Add before </body> in footer.php -->
<script
  src="https://replyza.io/widget.js"
  data-key="YOUR_API_KEY"
  async
></script>

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://replyza.io/widget.js"
          data-key="YOUR_API_KEY"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

<script
  src="https://replyza.io/widget.js"
  data-key="YOUR_API_KEY"
  async
></script>