Norahelp
Login Get Started

API Documentation

Complete guide to integrate Norahelp AI chatbot into your applications

Table of Contents

Getting Started

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

Base URL

https://norahelp.com/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 plans with API access enabled. 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://norahelp.com/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 limited to 60 requests per minute per caller to ensure fair usage and protect against abuse.

Rate Limit Headers: Every response includes X-RateLimit-Limit and X-RateLimit-Remaining headers so you can track your usage.
Exceeding the limit: Requests beyond the limit receive a 429 Too Many Requests response. Wait until the window resets before retrying.

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://norahelp.com/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://norahelp.com/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://norahelp.com/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://norahelp.com/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. Send only the fields you want to change.

Request Parameters

Parameter Type Required Description
name string Optional New display name for the widget
welcome_message string Optional Greeting shown when a chat starts
is_active boolean Optional Enable or disable the widget

Example Request

curl -X PUT https://norahelp.com/api/widgets/widget_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"welcome_message": "Hi there! How can I help?"}'

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

{
  "success": true,
  "from": "2026-07-11",
  "to": "2026-08-10",
  "total_conversations": 21,
  "total_messages": 42,
  "unique_users": 5
}