User API

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

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

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: "+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

sessionName

string

The unique session name created or reused

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

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

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: "+1234567890"
});

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)

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: "120363123456789012@g.us",
//       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)

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: "1234567890@c.us",
//       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;
};

tRPC Routers

Database Schema

getWhatsAppSession

Response

Example

initiateWhatsAppSession

Response

Example

Error Cases

getSessionStatus

Input Parameters

Response

Example

getSessionQR

Input Parameters

Response

Example

restartSession

Input Parameters

Response

Example

updateSessionPhone

Input Parameters

Response

Example

logoutSession

Input Parameters

Response

Example

getWhatsAppGroups

Input Parameters

Response

Example

getWhatsAppContacts

Input Parameters

Response

Example

Type Definitions

Build docs developers (and LLMs) love

tRPC Routers

Database Schema

Documentation Index

​getWhatsAppSession

​Response

​Example

​initiateWhatsAppSession

​Response

​Example

​Error Cases

​getSessionStatus

​Input Parameters

​Response

​Example

​getSessionQR

​Input Parameters

​Response

​Example

​restartSession

​Input Parameters

​Response

​Example

​updateSessionPhone

​Input Parameters

​Response

​Example

​logoutSession

​Input Parameters

​Response

​Example

​getWhatsAppGroups

​Input Parameters

​Response

​Example

​getWhatsAppContacts

​Input Parameters

​Response

​Example

​Type Definitions

Build docs developers (and LLMs) love

getWhatsAppSession

Response

Example

initiateWhatsAppSession

Response

Example

Error Cases

getSessionStatus

Input Parameters

Response

Example

getSessionQR

Input Parameters

Response

Example

restartSession

Input Parameters

Response

Example

updateSessionPhone

Input Parameters

Response

Example

logoutSession

Input Parameters

Response

Example

getWhatsAppGroups

Input Parameters

Response

Example

getWhatsAppContacts

Input Parameters

Response

Example

Type Definitions