# Envoy Developer Docs (llms.txt)

> Envoy is an AI website chatbot by Sanaf AI Solutions. It crawls your website,
> answers visitor questions 24/7, captures leads, and hands off to a human when
> needed. This file is the machine-readable companion to https://sanafai.com/envoy/docs.

API base URL: https://app.sanafai.com

## Quick start (embed)

Paste this snippet before </head> on your website. Get your widget API key
from the Envoy dashboard (Settings → Embed Code / API & Integrations):

    <script
      src="https://app.sanafai.com/widget.js"
      data-key="YOUR_WIDGET_API_KEY"
      async
    ></script>

The widget loads asynchronously (~20 KB gzipped, served from a CDN) and has no
impact on Core Web Vitals.

## Authentication

- Widget API key: public, used in the embed snippet (data-key) and the
  widget-config endpoint. Available on all plans, including Free.
- Secret API key: server-side only, used as a Bearer token for the /v1/*
  REST endpoints. Available on the Pro plan and above.

Send the secret key as: Authorization: Bearer <API_KEY>

## REST API

Public endpoints (no key required, CORS-enabled):

- GET  https://app.sanafai.com/api/public/envoy/showcase
    Public gallery of chatbots that opted into the showcase.
- GET  https://app.sanafai.com/api/envoy/widget-config?key={widgetApiKey}
    Widget config (brand color, greeting, position, site name). Cached 5 min.
- POST https://app.sanafai.com/api/envoy/widget/leads
    Submit a lead captured from the widget (name, email, phone).
- POST https://app.sanafai.com/api/envoy/widget/handoff
    Trigger a human-handoff request from the widget.
- POST https://app.sanafai.com/api/envoy/experiments/track
    Track an A/B test impression or conversion event.

Authenticated endpoints (Bearer secret key, Pro plan and above):

- POST https://app.sanafai.com/api/envoy/v1/query
    Query the chatbot programmatically and get an AI answer.
- POST https://app.sanafai.com/api/envoy/v1/sites
    Create a new Envoy chatbot site.
- GET  https://app.sanafai.com/api/envoy/v1/pages
    List the pages indexed for a site.

### Example widget-config response

    {
      "primaryColor": "#2563eb",
      "greeting": "Hi there! How can I help you today?",
      "showBranding": true,
      "position": "bottom-right",
      "siteName": "Sunrise Dental"
    }

## Webhooks

Register a webhook URL under Envoy → Settings → Webhooks. Each delivery
includes an X-Envoy-Signature header you can verify against your signing
secret. Events:

- lead.captured        — a visitor submits contact info via lead capture.
- handoff.requested    — a visitor asks for a human, or the bot escalates.
- conversation.started — a new visitor opens the widget and sends a message.

### Example lead.captured payload

    {
      "event": "lead.captured",
      "siteId": "site_abc123",
      "siteName": "Sunrise Dental",
      "timestamp": "2026-04-27T14:32:00Z",
      "lead": {
        "name": "Maria Lopez",
        "email": "maria@example.com",
        "phone": "+14055550199",
        "conversationId": "conv_xyz789"
      }
    }

## Key pages

- Docs (human):      https://sanafai.com/envoy/docs
- Product overview:  https://sanafai.com/envoy
- Pricing:           https://sanafai.com/envoy/pricing
- Integrations:      https://sanafai.com/envoy/integrations
- Add to your CMS:   https://sanafai.com/envoy/add-to
- Site-wide index:   https://sanafai.com/llms.txt