The User API provides endpoints for users to manage their WhatsApp sessions, retrieve groups and contacts, and control session lifecycle.
getWhatsAppSession
Retrieve the current user’s connected WhatsApp session.
Response
WhatsApp session object or null if not connectedSession creation timestamp
Array of associated WhatsApp groupsActive campaigns for this group
Example
const session = await trpc.user.getWhatsAppSession.query();
if (session) {
console.log(session);
// {
// id: "cls1234567890",
// sessionName: "session_1234567890",
// phoneNumber: "+1234567890",
// userId: "clx1234567890",
// createdAt: new Date("2024-01-01"),
// WhatsAppGroups: [...]
// }
} else {
console.log("No active session");
}
initiateWhatsAppSession
Create or reconnect to a WhatsApp session for the current user.
Response
The unique session name created or reused
Example
const result = await trpc.user.initiateWhatsAppSession.mutate();
console.log(result);
// {
// sessionName: "session_1234567890",
// id: "cls1234567890"
// }
Error Cases
- INTERNAL_SERVER_ERROR: Failed to create WhatsApp session
getSessionStatus
Check the current status of a WhatsApp session.
The session name to check
Response
Session status from WAHA API (e.g., “WORKING”, “SCAN_QR_CODE”, “STOPPED”)
Example
const status = await trpc.user.getSessionStatus.query({
sessionName: "session_1234567890"
});
console.log(status);
// { status: "WORKING" }
getSessionQR
Retrieve the QR code for authenticating a WhatsApp session.
The session name to get the QR code for
Response
Base64-encoded QR code image
Example
const qrCode = await trpc.user.getSessionQR.query({
sessionName: "session_1234567890"
});
console.log(qrCode);
// { qr: "iVBORw0KGgoAAAANSUhEUgAA..." }
// Display in HTML
// <img src={`data:image/png;base64,${qrCode.qr}`} />
restartSession
Restart a WhatsApp session by stopping and starting it.
The session name to restart
Response
Indicates whether the session was restarted successfully
Example
const result = await trpc.user.restartSession.mutate({
sessionName: "session_1234567890"
});
console.log(result);
// { success: true }
updateSessionPhone
Update the phone number associated with a session.
Response
Indicates whether the phone number was updated successfully
Example
const result = await trpc.user.updateSessionPhone.mutate({
id: "cls1234567890",
phoneNumber: "+1234567890"
});
console.log(result);
// { success: true }
logoutSession
Logout and delete a WhatsApp session.
The session name to logout
Response
Indicates whether the logout was successful
Example
const result = await trpc.user.logoutSession.mutate({
sessionName: "session_1234567890"
});
console.log(result);
// { success: true }
getWhatsAppGroups
Retrieve WhatsApp groups for a session with pagination and search.
The session name to fetch groups from
Maximum number of groups to return (minimum 1)
Pagination cursor (offset)
Optional search term to filter groups by name
Response
Cursor for the next page, or undefined if no more results
Total count not available without fetching all groups
Example
const groups = await trpc.user.getWhatsAppGroups.query({
sessionName: "session_1234567890",
limit: 10,
cursor: 0,
search: "Community"
});
console.log(groups);
// {
// items: [
// {
// groupId: "[email protected]",
// groupName: "Community Group"
// }
// ],
// nextCursor: 10
// }
Retrieve WhatsApp contacts for a session with pagination and search.
The session name to fetch contacts from
Maximum number of contacts to return (minimum 1)
Pagination cursor (offset)
Optional search term to filter contacts by name or number
Response
Array of contact objectsContact ID (used as groupId for consistency)
Cursor for the next page, or undefined if no more results
Total count not available
Example
const contacts = await trpc.user.getWhatsAppContacts.query({
sessionName: "session_1234567890",
limit: 50,
cursor: 0,
search: "John"
});
console.log(contacts);
// {
// items: [
// {
// groupId: "[email protected]",
// groupName: "John Doe",
// number: "1234567890",
// isContact: true
// }
// ],
// nextCursor: 50
// }
Type Definitions
type SessionStatusResponse = {
status: string; // "WORKING" | "SCAN_QR_CODE" | "STOPPED" | etc.
};
type SessionQRResponse = {
qr: string; // Base64-encoded image
};
type WhatsAppGroup = {
groupId: string;
groupName: string;
};
type WhatsAppContact = {
groupId: string; // Contact ID
groupName: string; // Contact name
number: string;
isContact: boolean;
};