Skip to main content
Configuration types for creating and managing WhatsApp socket connections.

​
SocketConfig

Complete configuration object for makeWASocket().

​
Connection Settings

​
waWebSocketUrl
string | URL
required
The WebSocket URL to connect to WhatsApp serversDefault: 'wss://web.whatsapp.com/ws/chat'
​
connectTimeoutMs
number
required
Connection timeout in milliseconds. Fails if socket doesn’t connect within this time.Default: 20000 (20 seconds)
​
defaultQueryTimeoutMs
number | undefined
required
Default timeout for queries in milliseconds. undefined for no timeout.Default: 60000 (60 seconds)
​
keepAliveIntervalMs
number
required
Ping-pong interval for WebSocket connection in millisecondsDefault: 25000 (25 seconds)
​
agent
Agent
Proxy agent for WebSocket connection
​
fetchAgent
Agent
Agent used for HTTP fetch requests (uploading/downloading media)

​
Client Identification

​
version
WAVersion
required
WhatsApp Web version to connect withType: [number, number, number]Example: [2, 2323, 4]
​
browser
WABrowserDescription
required
Browser identification sent to WhatsAppType: [string, string, string]Example: ['Baileys', 'Chrome', '1.0.0']
​
countryCode
string
required
Alphanumeric country code for the number (e.g., ‘US’, ‘BR’, ‘IN’)

​
Authentication

​
auth
AuthenticationState
required
Authentication state object containing credentials and keysSee AuthenticationState
​
transactionOpts
TransactionCapabilityOptions
required
Options for SignalKeyStore transaction capability

​
Logging and Events

​
logger
ILogger
required
Logger instance for debug output
​
emitOwnEvents
boolean
required
Whether to emit events for actions done by this socket connectionDefault: true

​
History and Sync

​
syncFullHistory
boolean
required
Whether to ask the phone for full history (received asynchronously)Default: false
​
shouldSyncHistoryMessage
function
required
Control which history messages to sync
(msg: proto.Message.IHistorySyncNotification) => boolean
Return true to sync, false to skip
​
fireInitQueries
boolean
required
Whether to automatically fire initialization queriesDefault: true

​
Message Handling

​
getMessage
function
required
Fetch a message from your store for retry logic
(key: WAMessageKey) => Promise<proto.IMessage | undefined>
Required for handling “this message can take a while” issues
​
patchMessageBeforeSending
function
required
Optionally modify messages before sending
(msg: proto.IMessage, recipientJids?: string[]) =>
  | Promise<PatchedMessageWithRecipientJID[] | PatchedMessageWithRecipientJID>
  | PatchedMessageWithRecipientJID[] 
  | PatchedMessageWithRecipientJID
​
shouldIgnoreJid
function
required
Determine if a JID should be ignored (no events, no decryption)
(jid: string) => boolean | undefined

​
Media

​
customUploadHosts
MediaConnInfo['hosts']
required
Custom upload hosts for media
​
linkPreviewImageThumbnailWidth
number
required
Width for link preview images in pixelsDefault: 192
​
generateHighQualityLinkPreview
boolean
required
Generate high quality link previews (uploads jpegThumbnail to WhatsApp)Default: false

​
Retry and Error Handling

​
retryRequestDelayMs
number
required
Time to wait between sending retry requests in millisecondsDefault: 250
​
maxMsgRetryCount
number
required
Maximum retry count for messagesDefault: 5
​
qrTimeout
number
Time to wait for QR code generation in millisecondsDefault: 60000 (60 seconds)
​
enableAutoSessionRecreation
boolean
required
Enable automatic session recreation for failed messagesDefault: false
​
enableRecentMessageCache
boolean
required
Enable recent message caching for retry handlingDefault: false

​
Caching

​
mediaCache
CacheStore
Cache to store media to avoid re-uploadingSee CacheStore
​
msgRetryCounterCache
CacheStore
Cache to track retry counts for failed messages
​
userDevicesCache
PossiblyExtendedCacheStore
Cache to store user device lists
​
callOfferCache
CacheStore
Cache to store call offers
​
placeholderResendCache
CacheStore
Cache to track placeholder resends
​
cachedGroupMetadata
function
required
Fetch cached group metadata to speed up message sending
(jid: string) => Promise<GroupMetadata | undefined>

​
Advanced

​
markOnlineOnConnect
boolean
required
Mark client as online when socket connectsDefault: true
​
appStateMacVerification
object
required
Verify app state MACs
{
  patch: boolean
  snapshot: boolean
}
​
options
RequestInit
required
Options for HTTP fetch requests
​
makeSignalRepository
function
required
Factory function for creating signal repositories
(
  auth: SignalAuthState,
  logger: ILogger,
  pnToLIDFunc?: (jids: string[]) => Promise<LIDMapping[] | undefined>
) => SignalRepositoryWithLIDStore

​
CacheStore

Interface for cache implementations used throughout Baileys.
​
get
function
required
Get a cached key
get<T>(key: string): Promise<T> | T | undefined
​
set
function
required
Set a key in the cache
set<T>(key: string, value: T): Promise<void> | void | number | boolean
​
del
function
required
Delete a key from the cache
del(key: string): void | Promise<void> | number | boolean
​
flushAll
function
required
Flush all data from cache
flushAll(): void | Promise<void>

​
PossiblyExtendedCacheStore

Extended cache store with batch operations:
​
mget
function
Get multiple keys at once
mget?<T>(keys: string[]): Promise<Record<string, T | undefined>>
​
mset
function
Set multiple keys at once
mset?<T>(entries: { key: string; value: T }[]): 
  Promise<void> | void | number | boolean
​
mdel
function
Delete multiple keys at once
mdel?(keys: string[]): void | Promise<void> | number | boolean

​
Supporting Types

​
WAVersion

type WAVersion = [number, number, number]

// Example:
const version: WAVersion = [2, 2323, 4]

​
WABrowserDescription

type WABrowserDescription = [string, string, string]

// Example:
const browser: WABrowserDescription = ['Baileys', 'Chrome', '1.0.0']

​
PatchedMessageWithRecipientJID

type PatchedMessageWithRecipientJID = proto.IMessage & {
  recipientJid?: string
}

​
Example Configuration

import makeWASocket, { 
  DisconnectReason, 
  useMultiFileAuthState,
  makeCacheableSignalKeyStore 
} from '@whiskeysockets/baileys'
import NodeCache from 'node-cache'
import pino from 'pino'

const logger = pino({ level: 'debug' })
const { state, saveCreds } = await useMultiFileAuthState('./auth_info')

// Create cache instances
const msgRetryCounterCache = new NodeCache()
const userDevicesCache = new NodeCache()

const sock = makeWASocket({
  version: [2, 2323, 4],
  logger,
  auth: {
    creds: state.creds,
    keys: makeCacheableSignalKeyStore(state.keys, logger)
  },
  browser: ['Baileys', 'Chrome', '1.0.0'],
  
  // Message handling
  getMessage: async (key) => {
    return await getMessageFromDB(key)
  },
  
  // Caching
  msgRetryCounterCache,
  userDevicesCache,
  
  // Group metadata caching
  cachedGroupMetadata: async (jid) => {
    return await getGroupMetadataFromDB(jid)
  },
  
  // Sync settings
  syncFullHistory: true,
  shouldSyncHistoryMessage: (msg) => {
    // Only sync last 30 days
    const thirtyDaysAgo = Date.now() - (30 * 24 * 60 * 60 * 1000)
    return msg.messageTimestamp > thirtyDaysAgo
  },
  
  // Connection settings
  connectTimeoutMs: 60000,
  defaultQueryTimeoutMs: 60000,
  keepAliveIntervalMs: 30000,
  
  // Advanced
  emitOwnEvents: false,
  markOnlineOnConnect: true,
  generateHighQualityLinkPreview: true
})

// Save credentials on update
sock.ev.on('creds.update', saveCreds)

Build docs developers (and LLMs) love

Get started for freeTalk to us