User API

API endpoints for managing WhatsApp sessions, groups, and contacts

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

session · object | null

WhatsApp session object or null if not connected

id · string

Session ID

sessionName · string

Unique session name

phoneNumber · string

Associated phone number

userId · string

Owner user ID

createdAt · Date

Session creation timestamp

updatedAt · Date

Last update timestamp

WhatsAppGroups · array

Array of associated WhatsApp groups

id · string

Group database ID

groupName · string

Group name

groupId · string

WhatsApp group ID

campaigns · array

Active campaigns for this group

Example

const session = await trpc.user.getWhatsAppSession.query();

if (session) {
  console.log(session);
  // {
  //   id: "cls1234567890",
  //   sessionName: "session_1234567890",
  //   phoneNumber: "[phone]",
  //   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

sessionName · string

The unique session name created or reused

id · string

The session database ID

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.

Input Parameters

sessionName · string · required

The session name to check

Response

status · string

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.

Input Parameters

sessionName · string · required

The session name to get the QR code for

Response

qr · string

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.

Input Parameters

sessionName · string · required

The session name to restart

Response

success · boolean

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.

Input Parameters

id · string · required

The session database ID

phoneNumber · string · required

The new phone number

Response

success · boolean

Indicates whether the phone number was updated successfully

Example

const result = await trpc.user.updateSessionPhone.mutate({
  id: "cls1234567890",
  phoneNumber: "[phone]"
});

console.log(result);
// { success: true }

---

logoutSession

Logout and delete a WhatsApp session.

Input Parameters

sessionName · string · required

The session name to logout

Response

success · boolean

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.

Input Parameters

sessionName · string · required

The session name to fetch groups from

limit · number · default: 10

Maximum number of groups to return (minimum 1)

cursor · number · default: 0

Pagination cursor (offset)

search · string

Optional search term to filter groups by name

Response

items · array

Array of group objects

groupId · string

WhatsApp group ID

groupName · string

Group name

nextCursor · number | undefined

Cursor for the next page, or undefined if no more results

total · undefined

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: "[e-mail]",
//       groupName: "Community Group"
//     }
//   ],
//   nextCursor: 10
// }

---

getWhatsAppContacts

Retrieve WhatsApp contacts for a session with pagination and search.

Input Parameters

sessionName · string · required

The session name to fetch contacts from

limit · number · default: 50

Maximum number of contacts to return (minimum 1)

cursor · number · default: 0

Pagination cursor (offset)

search · string

Optional search term to filter contacts by name or number

Response

items · array

Array of contact objects

groupId · string

Contact ID (used as groupId for consistency)

groupName · string

Contact name

number · string

Contact phone number

isContact · boolean

Always true for contacts

nextCursor · number | undefined

Cursor for the next page, or undefined if no more results

total · undefined

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: "[e-mail]",
//       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;
};