Getting started

Quickstart.

Four steps, end-to-end. By the end of this page you will have the messenger running on your site, a webhook receiving events, and a successful API call reading back a message.

Before you start

A Campfire workspace and your widgetId (the organisation UUID in your dashboard URL).
A Personal API key from Settings → API keys.
A public HTTPS endpoint for webhooks. A tunnel (ngrok, cloudflared) works in development.

Step 1

Embed the messenger

Paste the snippet below into any HTML page, before the closing </body>. The messenger loads asynchronously and will not block your initial render. Replace YOUR_ORG_ID with your workspace ID.

index.htmlhtml

<script
  async
  src="https://campfire.is/campfire.js"
  data-widget-id="YOUR_ORG_ID"
  data-position="bottom-right"
  data-color="hsl(142 71% 45%)"
  data-theme="auto"
></script>

Reload the page. The launcher appears in the bottom-right. See Widget for the full config surface — authenticated visitors, theming, event callbacks, and the programmatic window.Campfire API.

Step 2

Wire a webhook

Go to Settings → Webhooks → New webhook, point it at your HTTPS endpoint, and subscribe to message.created and conversation.created. Campfire will show you a signing secret once — copy it and store it where you keep your other secrets.

Deliveries are POSTed as JSON with a raw body; verify signatures against the raw bytes, not a re-encoded copy. The signing scheme and worked examples live on the Webhooks page.

terminalbash

# Tail your own endpoint, then trigger a test delivery from the dashboard.
# Headers you will see on every delivery:
#   X-Campfire-Event: message.created
#   X-Campfire-Delivery: <uuid>
#   X-Campfire-Timestamp: 2026-04-17T14:02:31.000Z
#   X-Campfire-Signature: <hex sha256 of raw body>

Step 3

Make your first API call

Authenticate with a bearer token — the same Personal API key you created above. The API is organisation-scoped; the key carries the tenant, so no explicit organisation parameter is required.

terminalbash

# Route lives on the main app (Next.js App Router: /api/v1/conversations).
# Same path is also served by the API app when deployed.
curl https://campfire.is/api/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Without a Bearer token the API returns JSON 401 (not HTML 404):
#   {"error":"unauthorized"}

A successful response is a JSON object with conversations (array) and total (integer). Use a Personal API key from Settings → API keys (cf_…) or a workspace widget API key. See API reference.

Step 4

Read messages back

Pick a conversation ID from the list response and read its thread. Messages are returned newest-last for easy render.

terminalbash

curl https://campfire.is/api/v1/conversations/<conversationId>/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

That’s the round trip: a visitor sends a message through the messenger, your webhook fires, and you can pull the full thread back through the API.

# Tail your own endpoint, then trigger a test delivery from the dashboard. # Headers you will see on every delivery: # X-Campfire-Event: message.created # X-Campfire-Delivery: <uuid> # X-Campfire-Timestamp: 2026-04-17T14:02:31.000Z # X-Campfire-Signature: <hex sha256 of raw body>

# Route lives on the main app (Next.js App Router: /api/v1/conversations). # Same path is also served by the API app when deployed. curl https://campfire.is/api/v1/conversations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" # Without a Bearer token the API returns JSON 401 (not HTML 404): # {"error":"unauthorized"}