Sending Mass Messages

1
interface SmartList {
2
  uuid: string;
3
  name: string;
4
  count: number;
5
}
6
7
interface CustomList {
8
  uuid: string;
9
  name: string;
10
  count: number;
11
  createdAt: string;
12
}
13
14
async function discoverLists(accessToken: string) {
15
  const headers = {
16
    Authorization: `Bearer ${accessToken}`,
17
    "X-Fanvue-API-Version": "2025-06-26",
18
  };
19
20
  // Fetch smart lists
21
  const smartListsRes = await fetch("https://api.fanvue.com/chats/lists/smart", {
22
    headers,
23
  });
24
  const smartLists: SmartList[] = await smartListsRes.json();
25
26
  // Fetch custom lists (first page)
27
  const customListsRes = await fetch("https://api.fanvue.com/chats/lists/custom?page=1&size=20", {
28
    headers,
29
  });
30
  const customListsData = await customListsRes.json();
31
  const customLists: CustomList[] = customListsData.data;
32
33
  return { smartLists, customLists };
34
}
35
36
// Usage
37
const { smartLists, customLists } = await discoverLists("YOUR_ACCESS_TOKEN");
38
console.log("Smart Lists:", smartLists);
39
console.log("Custom Lists:", customLists);

1
interface MassMessageRequest {
2
  text?: string; // Message text (optional if media provided)
3
  mediaUuids?: string[]; // Array of media UUIDs
4
  price?: number | null; // Price in cents for pay-to-view (requires media)
5
  includedLists: {
6
    smartListUuids?: string[]; // Smart list IDs to include
7
    customListUuids?: string[]; // Custom list UUIDs to include
8
  };
9
  excludedLists?: {
10
    // Optional: lists to exclude
11
    smartListUuids?: string[];
12
    customListUuids?: string[];
13
  };
14
}

1
interface MassMessageRequest {
2
  text?: string;
3
  mediaUuids?: string[];
4
  price?: number | null; // Price in cents (e.g., 999 = $9.99)
5
  includedLists: {
6
    smartListUuids?: string[];
7
    customListUuids?: string[];
8
  };
9
  excludedLists?: {
10
    smartListUuids?: string[];
11
    customListUuids?: string[];
12
  };
13
}
14
15
interface MassMessageResponse {
16
  id: string;
17
  recipientCount: number;
18
  createdAt: string;
19
}
20
21
class MassMessagingService {
22
  private baseUrl = "https://api.fanvue.com";
23
  private accessToken: string;
24
25
  constructor(accessToken: string) {
26
    this.accessToken = accessToken;
27
  }
28
29
  private async request(endpoint: string, options: RequestInit = {}) {
30
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
31
      ...options,
32
      headers: {
33
        Authorization: `Bearer ${this.accessToken}`,
34
        "X-Fanvue-API-Version": "2025-06-26",
35
        "Content-Type": "application/json",
36
        ...options.headers,
37
      },
38
    });
39
40
    if (!response.ok) {
41
      const error = await response.json().catch(() => ({}));
42
      throw new Error(error.message || `HTTP ${response.status}: ${response.statusText}`);
43
    }
44
45
    return response.json();
46
  }
47
48
  // Step 1: Get available lists
49
  async getSmartLists() {
50
    return this.request("/chats/lists/smart");
51
  }
52
53
  async getCustomLists(page = 1, size = 20) {
54
    return this.request(`/chats/lists/custom?page=${page}&size=${size}`);
55
  }
56
57
  async getSmartListMembers(listId: string, page = 1, size = 20) {
58
    return this.request(`/chats/lists/smart/${listId}?page=${page}&size=${size}`);
59
  }
60
61
  async getCustomListMembers(listUuid: string, page = 1, size = 20) {
62
    return this.request(`/chats/lists/custom/${listUuid}?page=${page}&size=${size}`);
63
  }
64
65
  // Step 2: Send mass message
66
  async sendMassMessage(request: MassMessageRequest): Promise<MassMessageResponse> {
67
    return this.request("/chats/mass-messages", {
68
      method: "POST",
69
      body: JSON.stringify(request),
70
    });
71
  }
72
}
73
74
// Example usage
75
async function main() {
76
  const service = new MassMessagingService("YOUR_ACCESS_TOKEN");
77
78
  try {
79
    // Step 1: Discover available lists
80
    console.log("📋 Fetching available lists...");
81
    const smartLists = await service.getSmartLists();
82
    const customListsData = await service.getCustomLists();
83
84
    console.log("Smart Lists:", smartLists);
85
    console.log("Custom Lists:", customListsData.data);
86
87
    // Step 2: Send mass message to subscribers
88
    console.log("\n📤 Sending mass message...");
89
    const result = await service.sendMassMessage({
90
      text: "Hello everyone! Thank you for your support!",
91
      includedLists: {
92
        smartListUuids: ["subscribers"],
93
      },
94
    });
95
96
    console.log("✅ Mass message sent!");
97
    console.log(`   Message ID: ${result.id}`);
98
    console.log(`   Recipients: ${result.recipientCount}`);
99
    console.log(`   Sent at: ${result.createdAt}`);
100
  } catch (error) {
101
    console.error("❌ Error:", error);
102
  }
103
}

1
// Preview recipients before sending
2
const preview = await service.getSmartListMembers("subscribers", 1, 5);
3
console.log("First 5 recipients:", preview.data);
4
5
// Then send to the full list
6
const result = await service.sendMassMessage({
7
  text: "Test message",
8
  includedLists: { smartListUuids: ["subscribers"] },
9
});

1
async function sendWithRetry(service: MassMessagingService, request: MassMessageRequest) {
2
  let retries = 0;
3
  const maxRetries = 3;
4
5
  while (retries < maxRetries) {
6
    try {
7
      return await service.sendMassMessage(request);
8
    } catch (error: any) {
9
      if (error.message.includes("429") && retries < maxRetries - 1) {
10
        // Rate limited - wait and retry
11
        const waitTime = Math.pow(2, retries) * 1000; // Exponential backoff
12
        console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
13
        await new Promise((resolve) => setTimeout(resolve, waitTime));
14
        retries++;
15
      } else {
16
        throw error;
17
      }
18
    }
19
  }
20
}

1
function validateMassMessageRequest(request: MassMessageRequest): string | null {
2
  // Must have text or media
3
  if (!request.text && !request.mediaUuids?.length) {
4
    return "Must provide either text or media";
5
  }
6
7
  // Must have at least one included list
8
  const hasIncludedLists =
9
    (request.includedLists.smartListUuids?.length ?? 0) > 0 ||
10
    (request.includedLists.customListUuids?.length ?? 0) > 0;
11
12
  if (!hasIncludedLists) {
13
    return "Must include at least one list";
14
  }
15
16
  // Price requires media
17
  if (request.price && !request.mediaUuids?.length) {
18
    return "Pay-to-view messages require media";
19
  }
20
21
  return null; // Valid
22
}
23
24
// Usage
25
const error = validateMassMessageRequest(myRequest);
26
if (error) {
27
  console.error("Invalid request:", error);
28
  return;
29
}

1
interface SendRecord {
2
  messageId: string;
3
  recipientCount: number;
4
  sentAt: string;
5
  lists: string[];
6
  text: string;
7
}
8
9
async function sendAndTrack(
10
  service: MassMessagingService,
11
  request: MassMessageRequest
12
): Promise<SendRecord> {
13
  const result = await service.sendMassMessage(request);
14
15
  const record: SendRecord = {
16
    messageId: result.id,
17
    recipientCount: result.recipientCount,
18
    sentAt: result.createdAt,
19
    lists: [
20
      ...(request.includedLists.smartListUuids || []),
21
      ...(request.includedLists.customListUuids || []),
22
    ],
23
    text: request.text || "(media only)",
24
  };
25
26
  // Save to your database or analytics service
27
  console.log("Send record:", record);
28
29
  return record;
30
}

1
// ❌ Wrong - empty lists
2
{
3
  includedLists: {
4
  }
5
}
6
7
// ✅ Correct - at least one list
8
{
9
  includedLists: {
10
    smartListUuids: ["subscribers"];
11
  }
12
}

1
// ❌ Wrong - uppercase
2
{
3
  smartListUuids: ["SUBSCRIBERS"];
4
}
5
6
// ✅ Correct - lowercase
7
{
8
  smartListUuids: ["subscribers"];
9
}

1
// Check list counts first
2
const smartLists = await service.getSmartLists();
3
const subscriberList = smartLists.find((l) => l.uuid === "subscribers");
4
console.log("Subscribers count:", subscriberList?.count);