@xenterprises/fastify-xwhatconverts

Fastify plugin for the WhatConverts lead tracking API. Provides lead management, account management, profile management, and call recording retrieval.

Installation

npm install @xenterprises/fastify-xwhatconverts

Usage

import Fastify from "fastify";
import xWhatConverts from "@xenterprises/fastify-xwhatconverts";

const fastify = Fastify({ logger: true });

await fastify.register(xWhatConverts, {
  token: process.env.WHATCONVERTS_TOKEN,
  secret: process.env.WHATCONVERTS_SECRET,
});

// List recent phone call leads
const result = await fastify.xwhatconverts.leads.list({
  leadType: "phone_call",
  leadsPerPage: 50,
});

// Get a single lead with customer journey
const lead = await fastify.xwhatconverts.leads.get("123456", {
  customerJourney: true,
});

// Create a new lead
const newLead = await fastify.xwhatconverts.leads.create({
  profileId: "your-profile-id",
  sendNotification: true,
  leadType: "form",
  contactName: "John Doe",
  contactEmail: "[email protected]",
});

Options

| Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| | token | string | Yes | — | WhatConverts API token | | secret | string | Yes | — | WhatConverts API secret | | baseUrl | string | No | https://app.whatconverts.com/api/v1 | API base URL override | | active | boolean | No | true | Set false to disable the plugin |

Environment Variables

| Name | Required | Description | |------|----------|-------------| | WHATCONVERTS_TOKEN | Yes | API token from WhatConverts dashboard | | WHATCONVERTS_SECRET | Yes | API secret from WhatConverts dashboard |

Generate API keys in your WhatConverts dashboard:

• Profile API Key: Account Profile → Tracking → Integrations (1,000 requests/day)
• Master API Key: Master Integrations — Agency plan required (10,000 requests/day)

Decorated Properties

| Property | Description | |----------|-------------| | fastify.xwhatconverts.leads | Lead CRUD operations and constants | | fastify.xwhatconverts.accounts | Account CRUD operations (Agency Key required) | | fastify.xwhatconverts.profiles | Profile CRUD operations | | fastify.xwhatconverts.recordings | Call recording retrieval |

Leads Service

leads.list(params?)

List leads with optional filtering.

| Param | Type | Default | Description | |-------|------|---------|-------------| | leadsPerPage | number | 25 | Results per page (max 250) | | pageNumber | number | 1 | Page number | | accountId | string | — | Filter by account | | profileId | string | — | Filter by profile | | leadType | string | — | phone_call, form, chat, transaction | | leadStatus | string | — | unique, repeat | | startDate | string | — | Start date (YYYY-MM-DD) | | endDate | string | — | End date (YYYY-MM-DD) | | order | string | — | asc or desc | | quotable | boolean | — | Filter quotable leads | | spam | boolean | — | Filter spam leads | | duplicate | boolean | — | Filter duplicate leads |

leads.get(leadId, params?)

Get a single lead by ID.

| Param | Type | Description | |-------|------|-------------| | leadId | string | Lead ID (required) | | params.customerJourney | boolean | Include customer journey (Elite plans only) |

leads.create(params)

Create a new lead.

| Param | Type | Required | Description | |-------|------|----------|-------------| | profileId | string | Yes | Profile ID | | leadType | string | Yes | phone_call, form, chat, transaction | | sendNotification | boolean | No | Send notification email | | dateTime | string | No | Lead date/time (YYYY-MM-DD HH:MM:SS) | | quotable | boolean | No | Whether lead is quotable | | quoteValue | number | No | Quote value | | salesValue | number | No | Sales value | | leadSource | string | No | Lead source | | leadMedium | string | No | Lead medium | | leadCampaign | string | No | Lead campaign | | leadContent | string | No | Lead content | | leadKeyword | string | No | Lead keyword | | contactName | string | No | Contact name | | contactEmail | string | No | Contact email | | contactPhone | string | No | Contact phone | | leadUrl | string | No | Lead URL | | additionalFields | object | No | Custom key-value fields |

leads.update(leadId, params)

Update an existing lead.

| Param | Type | Description | |-------|------|-------------| | leadId | string | Lead ID (required) | | quotable | boolean | Whether lead is quotable | | quoteValue | number | Quote value | | salesValue | number | Sales value | | leadUrl | string | Lead URL | | additionalFields | object | Custom key-value fields |

leads.delete(leadId) / leads.remove(leadId)

Delete a lead by ID.

Lead Constants

const { leadTypes, leadStatuses } = fastify.xwhatconverts.leads;

leadTypes.PHONE_CALL  // "phone_call"
leadTypes.FORM        // "form"
leadTypes.CHAT        // "chat"
leadTypes.TRANSACTION // "transaction"

leadStatuses.UNIQUE   // "unique"
leadStatuses.REPEAT   // "repeat"

Accounts Service

Requires Agency Key (Master API Key) for all operations.

accounts.list(params?)

| Param | Type | Default | Description | |-------|------|---------|-------------| | accountsPerPage | number | 25 | Results per page (max 250) | | pageNumber | number | 1 | Page number | | startDate | string | — | Start date (ISO 8601) | | endDate | string | — | End date (ISO 8601) | | order | string | — | asc or desc |

accounts.get(accountId)

Get a single account by ID.

accounts.create(params)

| Param | Type | Required | Description | |-------|------|----------|-------------| | accountName | string | Yes | Account name | | createProfile | boolean | No | Create a default profile |

accounts.update(accountId, params)

Update an existing account.

accounts.delete(accountId) / accounts.remove(accountId)

Delete an account. Warning: removes all profiles, numbers, leads, and settings.

Profiles Service

profiles.list(params?)

| Param | Type | Default | Description | |-------|------|---------|-------------| | profilesPerPage | number | 25 | Results per page (max 250) | | pageNumber | number | 1 | Page number | | accountId | string | — | Filter by account | | startDate | string | — | Start date (ISO 8601) | | endDate | string | — | End date (ISO 8601) | | order | string | — | asc or desc |

profiles.get(profileId)

Get a single profile by ID.

profiles.create(params)

| Param | Type | Required | Description | |-------|------|----------|-------------| | accountId | string | Yes | Parent account ID | | profileName | string | Yes | Profile name | | profileUrl | string | No | Profile URL |

profiles.update(profileId, params)

| Param | Type | Description | |-------|------|-------------| | profileId | string | Profile ID (required) | | profileName | string | Profile name | | profileUrl | string | Profile URL |

profiles.delete(profileId) / profiles.remove(profileId)

Delete a profile by ID.

Recordings Service

recordings.get(leadId)

Get the MP3 recording for a lead as an ArrayBuffer.

recordings.getBuffer(leadId)

Get the MP3 recording for a lead as a Node.js Buffer.

import { writeFile } from "fs/promises";
const buffer = await fastify.xwhatconverts.recordings.getBuffer("123456");
await writeFile("recording.mp3", buffer);

recordings.getUrl(leadId)

Get the API URL for a recording (does not make a request).

Exported Constants

import { LEAD_TYPES, LEAD_STATUSES, SORT_ORDERS } from "@xenterprises/fastify-xwhatconverts";

LEAD_TYPES    // ["phone_call", "form", "chat", "transaction"]
LEAD_STATUSES // ["unique", "repeat"]
SORT_ORDERS   // ["asc", "desc"]

Error Reference

All errors thrown by the plugin follow a consistent pattern:

| Code | Description | |------|-------------| | XWHATCONVERTS_API_ERROR | WhatConverts API returned a non-2xx status. Error includes statusCode and whatConvertsError properties. | | XWHATCONVERTS_NETWORK_ERROR | Network-level failure (DNS, timeout, connection refused). |

Validation errors (missing required params) throw standard Error with [xWhatConverts] prefix — e.g. [xWhatConverts] leads.get: leadId is required.

try {
  await fastify.xwhatconverts.leads.get("bad-id");
} catch (err) {
  if (err.code === "XWHATCONVERTS_API_ERROR") {
    console.error(err.statusCode);        // 404
    console.error(err.whatConvertsError);  // { message: "Lead not found" }
  }
}

How It Works

The plugin registers a single xwhatconverts decorator on the Fastify instance. On startup it validates the token and secret options, builds a Basic Auth header, and initializes four service namespaces: leads, accounts, profiles, and recordings.

All services share a common apiRequest helper that handles authentication headers, JSON serialization, error parsing (both JSON and plain-text API responses), and network error wrapping. The recordings service uses a separate binary request helper that returns raw ArrayBuffer data.

API credentials are only held in closure scope — they are not exposed on the decorator object.

The plugin uses fastify-plugin with fastify: ">=5.0.0" so the decorator is available to the enclosing scope (not scoped to a prefix).

Rate Limits

• Profile API key: 1,000 requests per day
• Master API key: 10,000 requests per day
• Maximum: 1 request per millisecond, 20 concurrent requests

License

UNLICENSED