Developer reference

Envoy Developer Reference

Everything you need to embed, query, and extend Envoy programmatically — from a single script tag to a full REST API integration.

Get your API key Product overview

Quick start

Add Envoy to any website with a single script tag. Get your widget API key from the Envoy dashboard, then paste this snippet before the </head> closing tag on your site:

HTML

Paste before </head>

<!-- 1. Get your widget API key from the Envoy dashboard -->
<!-- 2. Paste this before </head> on your website: -->
<script
  src="https://app.sanafai.com/widget.js"
  data-key="YOUR_WIDGET_API_KEY"
  async
></script>

Replace YOUR_WIDGET_API_KEY with the key from your chatbot settings. The widget loads asynchronously and does not block page rendering. That is all that is required for the chat bubble to appear.

Fetch live widget settings for a chatbot. Useful for building custom embed wrappers or previewing configuration without loading the full widget script.

GET https://app.sanafai.com/api/envoy/widget-config?key={widgetApiKey}

•CORS-enabled — safe to call from any browser origin.
•Response is cached for 5 minutes at the edge.
•No authentication required — the widget API key is the identifier.

Example response:

JSON

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

REST API endpoints

All endpoints share the base URL https://app.sanafai.com. Authenticated endpoints require an Authorization: Bearer <API_KEY> header. API access is available on Growth plan and above.

Method	Path	Description
GET	`/api/public/envoy/showcase`	Public gallery of chatbots that have opted in to the showcase.
GET	`/api/envoy/widget-config?key={widgetApiKey}`	Widget configuration for a chatbot. CORS-enabled, cached 5 min. Returns brand color, greeting, position, and site name.
POST	`/api/envoy/widget/leads`	Submit a lead captured from the widget (name, email, phone). CORS-enabled, public.
POST	`/api/envoy/widget/handoff`	Trigger a human handoff request from the widget. CORS-enabled, public.
POST	`/api/envoy/experiments/track`	Track an A/B test impression or conversion event from the widget. CORS-enabled, public.
POST	`/api/envoy/v1/query`	Query the chatbot programmatically and receive an AI-generated answer. Requires API key. Growth plan and above.
POST	`/api/envoy/v1/sites`	Create a new Envoy chatbot site via API. Requires API key. Growth plan and above.
GET	`/api/envoy/v1/pages`	List pages indexed for a chatbot site. Requires API key. Growth plan and above.

Public — no auth requiredRequires API key (Growth plan+)

Webhooks

Envoy can POST real-time event notifications to any HTTPS endpoint you configure in the dashboard. Register your webhook URL under Envoy → Settings → Webhooks. Each delivery includes an X-Envoy-Signature header you can use to verify authenticity.

lead.captured

Fired when a visitor submits their contact info through the lead capture form in the widget.

handoff.requested

Fired when a visitor clicks "Talk to a human" or the chatbot determines a human agent is needed.

conversation.started

Fired when a new visitor opens the widget and sends their first message.

Sample lead.captured payload:

JSON — POST to your webhook URL

{
  "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"
  }
}

Get your API key

Two types of keys exist in Envoy:

Widget API key

Used in the embed script data-key attribute and the widget-config endpoint. Public — safe to expose in HTML. Available on all plans including Free.

Secret API key

Growth plan+

Used in the Authorization: Bearer header for the /v1/* endpoints. Keep this private — store it server-side, never in browser code. Available on Growth ($79/mo) and above.

Both keys are available in your Envoy dashboard under Settings → API & Integrations.

Open Envoy dashboard

AI-readable documentation

This page is also available in a structured, machine-readable format at /envoy/docs/llms.txt, following the emerging llms.txt standard for helping AI search engines and coding assistants discover and cite your API documentation accurately.

Build something with Envoy

Agencies, developers, and freelancers use Envoy to add AI chatbots to client websites in minutes. Free plan available — no credit card required.

Start building — free See pricing

Free plan available · Growth plan from $79/mo includes API access