API Documentation

Complete guide to integrate Noras.AI AI chatbot into your applications

Table of Contents

Getting Started

Welcome to the Noras.AI API! This RESTful API allows you to integrate our AI chatbot capabilities into your applications.

Base URL

https://www.noras.ai/api

Quick Start

To get started with the API:

  1. Generate an API key from your Settings page
  2. Include your API key in the Authorization header of all requests
  3. Make requests to the endpoints documented below
Note: API access is available on Professional and Enterprise plans. Upgrade now

Authentication

All API requests must be authenticated using Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X POST https://www.noras.ai/api/chat \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_key": "widget_xyz123",
    "message": "Hello",
    "user_code": "user_abc789"
  }'
Security Warning: Never expose your API keys in client-side code. Always make API calls from your server.

Rate Limits

API requests are subject to rate limiting to ensure fair usage:

Plan Requests per Minute Requests per Hour
Professional 60 1,000
Enterprise 120 5,000
Rate Limit Headers: Check response headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset

Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with details:

Status Code Meaning
200 Success - Request completed successfully
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
403 Forbidden - Plan limit reached
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Server Error - Something went wrong on our end

Error Response Example

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or expired"
}

Send Chat Message

Send a message to your AI chatbot and receive a response.

POST /api/chat

Request Parameters

Parameter Type Required Description
widget_key string Required Your widget's unique identifier
message string Required The user's message (max 2000 characters)
user_code string Required Unique identifier for the user/session
context object Optional Additional context (user info, page URL, etc.)

Example Request

curl -X POST https://www.noras.ai/api/chat \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_key": "widget_abc123",
    "message": "What are your business hours?",
    "user_code": "user_unique_id_123",
    "context": {
      "page_url": "https://example.com/contact",
      "user_name": "John Doe"
    }
  }'

Success Response (200 OK)

{
  "success": true,
  "message": "Our business hours are Monday to Friday, 9 AM to 6 PM EST. We're closed on weekends and major holidays. How can I assist you today?",
  "conversation_id": "conv_xyz789",
  "timestamp": "2024-01-15T10:30:00Z"
}

JavaScript Example

const response = await fetch('https://www.noras.ai/api/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    widget_key: 'widget_abc123',
    message: 'Hello!',
    user_code: 'user_123'
  })
});

const data = await response.json();
console.log(data.message); // AI response

Python Example

import requests

url = "https://www.noras.ai/api/chat"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "widget_key": "widget_abc123",
    "message": "What services do you offer?",
    "user_code": "user_456"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(data["message"])

Get Conversations

Retrieve conversation history for a specific widget.

GET /api/conversations/{widget_key}

Query Parameters

Parameter Type Required Description
limit integer Optional Number of conversations to return (default: 50, max: 100)
offset integer Optional Pagination offset (default: 0)
user_code string Optional Filter by specific user

Example Request

curl -X GET https://www.noras.ai/api/conversations/widget_abc123?limit=10 \
  -H "Authorization: Bearer sk_your_api_key"

Success Response (200 OK)

{
  "success": true,
  "conversations": [
    {
      "id": "conv_123",
      "user_code": "user_456",
      "message": "What are your prices?",
      "response": "Our pricing starts at $29/month...",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 145,
  "has_more": true
}

Widget Management

Manage your chatbot widgets via API.

GET /api/widgets

Get list of all your widgets.

GET /api/widgets/{widget_key}

Get details of a specific widget.

PUT /api/widgets/{widget_key}

Update widget settings (name, welcome message, etc.).

Analytics

Access detailed analytics and statistics.

GET /api/analytics/{widget_key}

Query Parameters

Parameter Type Description
from date Start date (YYYY-MM-DD)
to date End date (YYYY-MM-DD)

Response Example

{
  "total_conversations": 1250,
  "total_messages": 3780,
  "unique_users": 890,
  "avg_response_time": 1.2,
  "satisfaction_rate": 94.5
}

Webhooks

Receive real-time notifications when events occur.

Real-time Events: Get notified instantly when users send messages, conversations end, or other important events occur.

Available Events

  • conversation.started - New conversation initiated
  • message.received - New message from user
  • conversation.ended - Conversation concluded

Webhook Payload Example

{
  "event": "message.received",
  "widget_key": "widget_abc123",
  "user_code": "user_456",
  "message": "I need help with my order",
  "timestamp": "2024-01-15T10:30:00Z"
}
Setup Webhooks: Configure webhook URLs in your Settings.