API Reference

Integrate Hal with your backend systems

REST API

The Hal API allows you to manage conversations, send messages, and access visitor data programmatically.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer your-jwt-token

Get your token by logging in via POST /api/auth/login.

Base URL

https://api.chatwithhal.com/api

Authentication Endpoints

POST

/api/auth/signup

Create a new account

Request Body

{
  "email": "user@example.com",
  "password": "securepassword",
  "company_name": "Acme Inc"
}

POST

/api/auth/login

Authenticate and get JWT token

Request Body

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "company_name": "Acme Inc"
  }
}

Apps Endpoints

GET

/api/apps

List all apps for the authenticated user

POST

/api/apps

Create a new app

Request Body

{
  "name": "My Website",
  "domain": "example.com"
}

GET

/api/apps/:id

Get app details

PATCH

/api/apps/:id

Update app settings

Request Body

{
  "name": "Updated Name",
  "widget_config": "{\"primaryColor\": \"#dc2626\"}"
}

Conversations Endpoints

GET

/api/apps/:appId/conversations

List conversations for an app

GET

/api/apps/:appId/conversations/:id

Get conversation with messages

PATCH

/api/apps/:appId/conversations/:id

Update conversation status

Request Body

{
  "status": "resolved"
}

Messages Endpoints

POST

/api/conversations/:id/messages

Send a message as an agent

Request Body

{
  "content": "Thanks for reaching out!"
}

WebSocket API

For real-time updates, connect via WebSocket:

Agent Connection

wss://api.chatwithhal.com/ws/agent?token=your-jwt-token

Events

new_message - New message in any conversation
conversation_updated - Conversation status changed
typing - Visitor is typing

Rate Limits

API requests are limited to:

100 requests per minute for authenticated endpoints
1000 messages per hour per app