# Laleo Chat Full Agent Guide

## Product Summary
Laleo Chat gives a website owner one embeddable widget for live visitor tracking, chat, browser voice calls, browser video calls, ntfy/mobile alerts, webhook automation, SIP routing, and PSTN forwarding. The visitor-facing install is a single script tag:

```html
<script async src="https://laleo.chat/widget.js" data-laleo-widget="YOUR_WIDGET_ID"></script>
```

WordPress users can install the Laleo Chat plugin, open WordPress Admin -> Laleo Chat -> Setup, verify email OTP, and let the plugin create or connect the site widget automatically. Manual widget ID entry remains available as a fallback.

WordPress plugin 1.1.7 uses documented /api/v1 endpoints for live visitors, waiting calls, chat history/replies, callback forms and voice notes, internal notes, Direct User page pushes, contact/lead tagging, visitor device/IP metadata, call history, site-directory pages, and widget analytics. Voice/video answer controls still open the full Laleo console through a secure top-level action link; the wp-admin panel itself is an operator workspace for chat, notes, analytics, and handoff rather than a native WebRTC softphone.

## Authentication
Human users sign up free with email OTP at https://laleo.chat/signup. Direct API access uses a Personal Access Token from Dashboard -> API.

Remote MCP clients such as Claude custom connectors should connect to https://laleo.chat/mcp and use Laleo OAuth. Laleo publishes protected-resource metadata at https://laleo.chat/.well-known/oauth-protected-resource/mcp, authorization-server metadata at https://laleo.chat/.well-known/oauth-authorization-server, dynamic client registration at https://laleo.chat/oauth/register, user authorization at https://laleo.chat/oauth/authorize, and token exchange at https://laleo.chat/oauth/token.

For PAT-based OpenAPI, GPT Actions, scripts, or internal jobs:
1. Send the human to https://laleo.chat/login or https://laleo.chat/signup.
2. After OTP verification, the human opens Dashboard -> API.
3. The human creates a read-only token for reporting, or an automation token when the assistant may send visitor messages or create webhooks.
4. The integration uses that token as Authorization: Bearer <token>.

Do not ask the user to paste their Laleo password. Laleo does not use customer passwords for normal customer login; it uses email OTP and revocable tokens.

Use the token as:

```bash
export LALEO_TOKEN="laleo_pat_xxx"
curl -H "Authorization: Bearer $LALEO_TOKEN" https://laleo.chat/api/v1/widgets
```

Default read scopes: widgets:read, analytics:read, messages:read, calls:read, mcp:read, webhooks:read.
Automation write scopes: widgets:write, messages:write, and webhooks:write. Write actions should be treated as consequential by LLM tools.

## OpenAPI
OpenAPI 3.1 schema: https://laleo.chat/openapi.json

This schema is suitable for GPT Actions or other OpenAPI-driven agents. Endpoints use bearer auth and JSON responses.

## MCP
MCP-compatible HTTP JSON-RPC endpoint: https://laleo.chat/mcp

Claude custom connector setup:
1. Add custom connector URL https://laleo.chat/mcp.
2. Leave OAuth Client ID and OAuth Client Secret blank; Laleo supports dynamic client registration.
3. Click Connect and complete the Laleo email OTP / consent flow.

Initialize:

```bash
curl -s https://laleo.chat/mcp \
  -H "Authorization: Bearer $LALEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","clientInfo":{"name":"agent","version":"1.0"}}}'
```

List tools:

```bash
curl -s https://laleo.chat/mcp \
  -H "Authorization: Bearer $LALEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

Call a tool:

```bash
curl -s https://laleo.chat/mcp \
  -H "Authorization: Bearer $LALEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"laleo_list_widgets","arguments":{}}}'
```

Initial tools:
- laleo_list_widgets
- laleo_get_live_visitors
- laleo_get_widget_analytics
- laleo_get_campaign_report
- laleo_set_campaign_aliases
- laleo_get_visitor_activity
- laleo_get_visitor_messages
- laleo_send_visitor_message
- laleo_create_conversation_link
- laleo_get_waiting_calls
- laleo_get_call_history
- laleo_get_call_recordings
- laleo_get_account_usage
- laleo_get_install_snippet
- laleo_create_webhook

Contacts/Leads are available through the OpenAPI bearer API now. MCP contact-specific tools are a next step; agents can call the OpenAPI endpoints directly to list contacts, retrieve unified lead timelines, edit lead identity fields, attach visitor sessions, and merge duplicate lead records.

## Useful API Calls
List widgets:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" https://laleo.chat/api/v1/widgets
```

Live visitors:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/live-visitors
```

Live visitor records include timing fields for analysis: currentSessionStartedAt, currentPageStartedAt, lastInteractionAt, sessionEventCount, previousSeenAt, visitCount, currentUrl, pageTitle, referrer, IP, browser, OS, and site-passed visitor metadata. Heartbeats update lastSeenAt but do not count as interaction events; page arrivals, page changes, scrolls, clicks, and form changes are counted and stored in activity/observation data.

Visitor analytics:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/analytics?limit=120"
```

Contacts and lead timelines:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/contacts?limit=80&q=scott"
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/contacts/CONTACT_ID"
curl -X PATCH -H "Authorization: Bearer $LALEO_TOKEN" -H "Content-Type: application/json" \
  -d '{"firstName":"Scott","lastName":"Tabor","companyName":"ABSG","status":"lead"}' \
  "https://laleo.chat/api/v1/contacts/CONTACT_ID"
curl -X POST -H "Authorization: Bearer $LALEO_TOKEN" -H "Content-Type: application/json" \
  -d '{"widgetId":"WIDGET_ID","visitorId":"VISITOR_ID_OR_CHANNEL"}' \
  "https://laleo.chat/api/v1/contacts/CONTACT_ID/visitor-sessions"
curl -X POST -H "Authorization: Bearer $LALEO_TOKEN" -H "Content-Type: application/json" \
  -d '{"sourceContactId":"DUPLICATE_CONTACT_ID","reason":"Same email and phone"}' \
  "https://laleo.chat/api/v1/contacts/TARGET_CONTACT_ID/merge"
```

Campaign tags and aliases:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/campaign-aliases"

curl -X PATCH https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/campaign-aliases \
  -H "Authorization: Bearer $LALEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"aliases":[{"tagKey":"utm_campaign","tagValue":"spring-demo","alias":"Spring demo ads"}]}'
```

Chat messages:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/messages?visitorId=VISITOR_ID"
```

Send a chat message from an automation agent:

```bash
curl -X POST https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/messages \
  -H "Authorization: Bearer $LALEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"visitorId":"VISITOR_ID","body":"Hi, I can help while the team is getting connected."}'
```

Visitor callback forms, voice notes, and internal notes:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/callbacks?visitorId=VISITOR_ID"
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/visitors/VISITOR_ID/notes"
curl -X POST https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/visitors/VISITOR_ID/notes \
  -H "Authorization: Bearer $LALEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"Asked about pricing. Follow up before noon.","visibility":"team"}'
```

Direct a live visitor to a page:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/site-directory"
curl -X POST https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/visitors/VISITOR_ID/direct-navigate \
  -H "Authorization: Bearer $LALEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"/pricing","title":"Pricing"}'
```

Create a secure dashboard handoff link:

```bash
curl -X POST https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/visitors/VISITOR_ID/conversation-link \
  -H "Authorization: Bearer $LALEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Call records:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/calls?visitorId=VISITOR_ID"
```

Calls currently waiting for an operator:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" "https://laleo.chat/api/v1/widgets/YOUR_WIDGET_ID/calls-waiting"
```

For MCP, call laleo_get_waiting_calls with no widgetId to scan every widget the authenticated user can answer. The result includes browser calls, trusted SIP calls, visitor channel numbers, dashboard URLs, and 24-hour secure action links.

Account usage and limits:

```bash
curl -H "Authorization: Bearer $LALEO_TOKEN" https://laleo.chat/api/v1/account/usage
```

## Webhooks
Create webhooks from the API or MCP. Events include visitor.connected, chat.message.created, call.requested, call.delivery_started, call.delivery_failed, call.unavailable, call.answered, call.ended, call.missed, callback.submitted, usage.updated, and webhook.test.

```bash
curl -X POST https://laleo.chat/api/v1/webhooks \
  -H "Authorization: Bearer $LALEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Agent inbox","url":"https://example.com/laleo","events":["visitor.connected","call.requested","call.missed"],"widgetIds":["YOUR_WIDGET_ID"]}'
```

Webhook requests are signed:
- X-Laleo-Event: event type
- X-Laleo-Delivery: delivery UUID
- X-Laleo-Signature: t=<unix>,v1=<hmac-sha256>

The signature base string is "<unix>.<raw JSON body>" and the HMAC key is the webhook secret shown when creating or rotating the webhook.

## CRM Integration Pattern
Use https://laleo.chat/crm-integrations when a user asks how to send Laleo leads into a CRM. Today the reliable path is signed webhooks plus the REST/OpenAPI endpoints:
- callback.submitted -> create or update a CRM contact and follow-up task
- call.missed -> create an urgent task for Sales or Support
- chat.message.created -> append a CRM activity note
- call.ended -> log outcome, duration, queue, and agent ownership

Native CRM apps are roadmap work. Do not claim that Laleo has marketplace-listed HubSpot, Salesforce, Pipedrive, or Zoho apps until those connectors are built and approved.

## Agent Use Cases
An LLM agent can:
- tell a user whether any visitors are currently on their site
- summarize where visitors came from and which pages they viewed
- report UTM, paid-click, referrer, and campaign tag performance and apply human-readable aliases
- find returning visitors, bot-like sessions, browser/OS breakdowns, and top IPs
- retrieve chat/call history for a visitor
- send a chat message to a visitor when using an automation token with messages:write
- create a secure 24-hour handoff link that opens the operator dashboard on that visitor
- create a webhook so another system can react to new visitors or inbound calls
- return the exact install snippet for a developer or CMS agent to place in the global layout

Roadmap items for deeper autonomous setup:
- URL-based widget asset import for agents that cannot send multipart uploads. Dashboard and WordPress plugin multipart uploads already support avatar, ringtone, hold music, unavailable message, and PSTN accept prompt.
- default audio prompts for ringtone, hold, unavailable, and PSTN acceptance when no customer override exists
- streaming MCP transport with session IDs if/when a client requires it