xWhatConverts

A Fastify plugin for integrating with WhatConverts' lead tracking API. Provides lead management, account management, and call recording retrieval.

Installation

npm install xwhatconverts

Usage

import Fastify from "fastify";
import xWhatConverts from "xwhatconverts";

const fastify = Fastify();

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

// Get all leads
const leads = await fastify.xwhatconverts.leads.list({
  leadsPerPage: 50,
  leadType: "phone_call",
});

// Get a single lead
const lead = await fastify.xwhatconverts.leads.get("123456");

// 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]",
});

Configuration Options

| Option | 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 | | active | boolean | No | true | Enable/disable the plugin |

Authentication

WhatConverts uses HTTP Basic authentication with a token and secret. You can generate API keys in your WhatConverts dashboard:

• Profile API Key: Navigate to an account profile -> "Tracking" -> "Integrations"
• Master API Key: Navigate to "Master Integrations" (requires Agency plan)

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

API Reference

Decorators

After registration, the following decorators are available on the Fastify instance:

| Decorator | Description | |-----------|-------------| | fastify.xwhatconverts.leads | Lead management methods | | fastify.xwhatconverts.accounts | Account management methods (requires Agency Key) | | fastify.xwhatconverts.recordings | Call recording methods | | fastify.xwhatconverts.config | Plugin configuration |

Leads Service

fastify.xwhatconverts.leads.list(params)

Get all leads with optional filtering.

const leads = await fastify.xwhatconverts.leads.list({
  leadsPerPage: 50,      // Default: 25, max: 250
  pageNumber: 1,
  accountId: "123",
  profileId: "456",
  leadType: "phone_call", // phone_call, form, chat, transaction
  leadStatus: "unique",   // unique, repeat
  startDate: "2024-01-01",
  endDate: "2024-12-31",
  order: "desc",
  quotable: true,
  spam: false,
  duplicate: false,
});

fastify.xwhatconverts.leads.get(leadId, params)

Get a single lead by ID.

const lead = await fastify.xwhatconverts.leads.get("123456", {
  customerJourney: true, // Elite plans only
});

fastify.xwhatconverts.leads.create(params)

Create a new lead.

const lead = await fastify.xwhatconverts.leads.create({
  profileId: "your-profile-id",     // Required
  sendNotification: true,            // Required
  leadType: "form",                  // Required: phone_call, form, chat, transaction
  dateTime: "2024-01-15 10:30:00",
  quotable: true,
  quoteValue: 1000,
  salesValue: 500,
  leadSource: "google",
  leadMedium: "organic",
  leadCampaign: "winter-sale",
  contactName: "John Doe",
  contactEmail: "[email protected]",
  contactPhone: "+1234567890",
  leadUrl: "https://example.com/landing",
  additionalFields: {
    company: "Acme Inc",
    notes: "Interested in premium plan",
  },
});

fastify.xwhatconverts.leads.update(leadId, params)

Update an existing lead.

const lead = await fastify.xwhatconverts.leads.update("123456", {
  quotable: true,
  quoteValue: 1500,
  salesValue: 1200,
  additionalFields: {
    status: "converted",
  },
});

Lead Type Constants

const { leadTypes } = fastify.xwhatconverts.leads;
// leadTypes.PHONE_CALL = "phone_call"
// leadTypes.FORM = "form"
// leadTypes.CHAT = "chat"
// leadTypes.TRANSACTION = "transaction"

Accounts Service

Note: Account operations require an Agency Key (Master API Key).

fastify.xwhatconverts.accounts.list(params)

Get all accounts.

const accounts = await fastify.xwhatconverts.accounts.list({
  accountsPerPage: 50,   // Default: 25, max: 250
  pageNumber: 1,
  startDate: "2024-01-01T00:00:00Z",
  endDate: "2024-12-31T23:59:59Z",
  order: "asc",
});

fastify.xwhatconverts.accounts.get(accountId)

Get a single account by ID.

const account = await fastify.xwhatconverts.accounts.get("123");

fastify.xwhatconverts.accounts.create(params)

Create a new account.

const account = await fastify.xwhatconverts.accounts.create({
  accountName: "New Client Account",
  createProfile: true,  // Optional: create a default profile
});

fastify.xwhatconverts.accounts.update(accountId, params)

Update an existing account.

const account = await fastify.xwhatconverts.accounts.update("123", {
  accountName: "Updated Account Name",
});

fastify.xwhatconverts.accounts.remove(accountId)

Delete an account. Warning: This will remove all profiles, numbers, leads, and other settings.

const result = await fastify.xwhatconverts.accounts.remove("123");

Recordings Service

fastify.xwhatconverts.recordings.get(leadId)

Get the MP3 recording for a lead as an ArrayBuffer.

const audioData = await fastify.xwhatconverts.recordings.get("123456");
// Returns ArrayBuffer

fastify.xwhatconverts.recordings.getBuffer(leadId)

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

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

fastify.xwhatconverts.recordings.getUrl(leadId)

Get the API URL for a recording.

const url = fastify.xwhatconverts.recordings.getUrl("123456");
// Returns: "https://app.whatconverts.com/api/v1/recording?lead_id=123456"

Testing

npm test

License

MIT