The connector reference.

Everything a platform needs to become a lane on Fanogram: authenticate, declare what you can honour, stream what happened, and execute the actions we hand back. Chat, CRM, co-pilot, autopilot and payments are inherited. You do not implement them.

Getting started

Three things happen before your first event lands: you log in to the partner dashboard and generate a sandbox key, you register your platform with the capabilities you can honour, and you point a webhook at your side. Nothing in the sandbox touches real money or a real fan.

Auth

Every request carries a bearer key. Every request that acts on a creator also carries the creator scope you were granted. A key alone can read your connector, never a creator’s fans. Access decisions fail closed: an unresolvable scope is a 403, never a silent empty list.

curl https://api.fanogram.co/v1/connectors/self \
  -H "Authorization: Bearer fg_live_…" \
  -H "Fg-Creator-Scope: crt_9f2a41" \
  -H "Fg-Api-Version: 2026-08-01"

const fg = new Fanogram({
  key: process.env.FG_API_KEY,   // never inline a key
  apiVersion: '2026-08-01'
});

const me = await fg.connectors.self({
  creatorScope: 'crt_9f2a41'
});

Connector standard

Registration is where you declare what your platform can actually do. Capabilities you do not declare are never offered to your creators, and never appear in their UI. A lane cannot over-promise by accident; that is the whole point of declaring rather than discovering.

{
  "slug": "yourplatform",
  "display_name": "Your Platform",
  "capabilities": [
    "chat.send",
    "chat.media",
    "payments.unlock",
    "crm.read"
  ],
  "webhook_url": "https://api.yourplatform.com/fg/actions",
  "regions": ["GB", "US", "DE"]
}

{
  "id": "con_4b81de",
  "slug": "yourplatform",
  "status": "sandbox",
  "capabilities": [
    "chat.send",
    "chat.media",
    "payments.unlock",
    "crm.read"
  ],
  "webhook_secret_hint": "whsec_…4f7c",   // full value shown once
  "created_at": "2026-08-12T09:14:02Z"
}

Per-platform enablement

Implementing the standard once grants access to the standardised capabilities. Which of them are enabled for a given lane is a per-platform decision, ruled on the Connect engine’s side: a ruling, not a default. Registration declares what your platform can honour; the engine’s enablement rules decide what your lane actually offers. A capability that is declared but not enabled for your lane is never offered to your creators, and calling it is refused: like every access decision on this page, enablement fails closed.

Who connects

• Platforms with the audience: inherit chat, CRM, autopilot and payments, stay the brand your users see, and ship a lane instead of a payments company.
• Tools with the workflow: read the fan record you never had, attribute your workflow to real revenue, and embed chat where the work already happens.
• Agencies with the operators: one integration per agency, scoped access by creator, lane and hours, with attribution and splits already computed.

Trust and compliance

• Consent: voice, likeness and chat training are opt-in per feature, per creator, and revocable. A partner cannot enable them on a creator’s behalf.
• Data: every token is scoped to declared capabilities. Access decisions fail closed, and every read of a fan record is attributable to a key.
• Content: paid media is invisibly watermarked to the buying fan on every send, including sends your product initiates.
• Money: Fanogram is merchant of record. Refunds, chargebacks and payouts resolve against a single book; there is no partner-side reconciliation.

Chat API

The differentiator, in endpoint form: a connected platform is not handed a read-only feed and asked to rebuild a chat client. Your lane gets the thread itself (send, media, drafts, unsend, reactions and read state), with correctness owned on our side. This is part of the connector standard, for platforms connected as lanes; it is not the standalone engine offering. See the partner overview for why that matters.

curl -X POST https://api.fanogram.co/v1/threads/thr_71c/messages \
  -H "Authorization: Bearer fg_live_…" \
  -H "Fg-Creator-Scope: crt_9f2a41" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "It’s live. It unlocks right here in the chat.",
    "media_ids": ["med_28ba9f"],
    "price": 2400,
    "mode": "co-pilot",
    "idempotency_key": "snd_2026-08-12_01"
  }'

{
  "id": "msg_c02e19",
  "thread_id": "thr_71c",
  "state": "awaiting_approval",   // co-pilot: creator approves
  "mode": "co-pilot",
  "price": 2400,
  "currency": "USD",
  "attribution": {
    "connector": "con_4b81de",
    "surface": "partner"
  },
  "created_at": "2026-08-12T09:31:44Z"
}

{
  "id": "fan_a81f30",
  "handle": "alex",
  "lifetime_value": 92700,       // minor units, fan-facing
  "currency": "USD",
  "lanes": ["telegram", "yourplatform"],
  "tags": ["vip", "renewed"],
  "last_active_at": "2026-08-12T08:52:10Z"
}

Payments

You render the money; you never hold it. Fanogram is merchant of record, mints the transaction, and settles out through the Spire rail. Your side asks for an unlock and reads the resulting ledger line; there is no partner-side book to reconcile.

{
  "id": "unl_5d7a02",
  "state": "captured",
  "amount": 2400,
  "currency": "USD",
  "merchant_of_record": "fanogram",
  "processor": "ccbill",
  "ledger_entry": "led_9ce441",
  "splits": "resolved_server_side",  // terms: PRICING-CANONICAL.md
  "settlement": {
    "rail": "spire",
    "status": "pending_launch"       // concept, not live
  }
}

Webhooks

Step 4 of the connector standard: we hand you signed actions to perform. Your side stays a thin, verifiable executor. Verify the signature, do the thing, return 2xx.

• Signed with Fg-Signature: a timestamp and an HMAC over the raw body. Verify before parsing.
• Retried with exponential backoff for 24 hours on any non-2xx or timeout over 5 seconds.
• At-least-once delivery. Deduplicate on event.id: a repeat is expected, not a bug.
• Order is not guaranteed across threads. Within a thread, sequence is monotonic.

{
  "id": "evt_0f3b7c",
  "type": "action.dispatch",
  "sequence": 418,
  "created_at": "2026-08-12T09:33:01Z",
  "data": {
    "action": "send_message",
    "thread_id": "thr_71c",
    "external_fan_id": "u_88213",
    "body": "It’s live. It unlocks right here in the chat.",
    "media": [{ "url": "https://cdn.fanogram.co/…", "expires_in": 600 }]
  }
}

// Fg-Signature: t=1786000381,v1=9f2c…
const [t, v1] = parseSig(req.headers['fg-signature']);
const expected = hmacSha256(
  process.env.FG_WEBHOOK_SECRET,
  `${t}.${rawBody}`            // RAW body, before JSON.parse
);
if (!timingSafeEqual(v1, expected)) return res.status(400).end();
if (Date.now()/1000 - t > 300) return res.status(400).end();  // replay window

Engines overview

Four surfaces arrive wired to one fan record. A conversation that starts in your app, a sale that closes in ours and a payout that settles next week are the same object with three views, not three integrations you reconcile by hand:

• Chat: threads, media, unsend, reactions, scheduled sends and read state, rendered in your product and backed by the shared engine. One thread per fan, whichever lane the message arrived on.
• CRM: lifetime value, spend history, tags, smart lists and the whole relationship, computed once and readable from your side.
• Co-pilot and autopilot: two modes, and only two. Co-pilot drafts and waits for approval; autopilot runs autonomously. Both write in the creator’s trained tone and are switchable per chat.
• Payments: tips, subscriptions and in-chat unlocks, plus the ledger underneath them: splits, refunds, chargebacks and payouts. Your product shows the money; it never has to hold it.

Chat: the surface, not a feed

Most partner APIs in this category hand you events and wish you luck. You rebuild threading, media and the AI layer yourself, and it drifts from the source of truth on the first release. Ours will expose the chat surface itself: your creators answer inside your app, and the thread, fan record and attribution are the same objects we run. The Chat API above is a different thing: it documents the connected-platform lane under the connector standard. The standalone reference lands here when this offering opens.

Payments: without becoming the bank

Being the merchant of record in this category is the expensive part: high-risk processing, chargeback exposure, KYC and payout compliance in every country. Fanogram mints the transaction instead. One ledger records the split, refund, chargeback and payout, and Spire settles it out. The Payments section above covers the connector standard’s hand-off for connected lanes; no standalone payments reference exists yet.

Errors

Errors are machine-readable first. Every response carries a stable code, a human message that is safe to log, and a request_id to quote. Access failures fail closed: you get a refusal, never a quietly empty result.

Changelog

Breaking changes ship behind a dated Fg-Api-Version. A version is supported for twelve months after its successor lands, and deprecations are announced here before they are enforced.