Campfire
DocsQuickstart

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
curl https://api.campfire.is/v1/conversations \
  -H "Authorization: Bearer cmp_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json"

A successful response is a JSON object with conversations (array) and total (integer). The shapes match the dashboard — 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://api.campfire.is/v1/conversations/<conversationId>/messages \
  -H "Authorization: Bearer cmp_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

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.

Next