Socket Configuration

UserFacingSocketConfig

The configuration object passed to makeWASocket.

type UserFacingSocketConfig = Partial<SocketConfig> & {
  auth: AuthenticationState
}

All fields except auth are optional and will use default values from DEFAULT_CONNECTION_CONFIG.

Required Configuration

auth

AuthenticationState

required

Authentication state object containing credentials and keys. Use useMultiFileAuthState or useSingleFileAuthState to create this.

import { useMultiFileAuthState } from '@whiskeysockets/baileys'

const { state, saveCreds } = await useMultiFileAuthState('auth_info')

const sock = makeWASocket({
    auth: state
})

Connection Configuration

waWebSocketUrl

string | URL

default:"'wss://web.whatsapp.com/ws/chat'"

The WebSocket URL to connect to WhatsApp Web.

connectTimeoutMs

number

default:"20000"

Connection timeout in milliseconds. Connection fails if socket doesn’t open within this time.

keepAliveIntervalMs

number

default:"30000"

Ping-pong interval for WebSocket connection in milliseconds.

defaultQueryTimeoutMs

number | undefined

default:"60000"

Default timeout for queries in milliseconds. Set to undefined for no timeout.

agent

Agent

HTTPS proxy agent for the WebSocket connection.

import { HttpsProxyAgent } from 'https-proxy-agent'

const agent = new HttpsProxyAgent('http://proxy:8080')

const sock = makeWASocket({
    auth: state,
    agent
})

fetchAgent

Agent

Agent used for fetch requests when uploading/downloading media. Separate from the WebSocket agent.

Client Identification

version

WAVersion

default:"[2, 3000, 1033846690]"

WhatsApp Web version to use. Format: [major, minor, patch].

browser

WABrowserDescription

default:"Browsers.macOS('Chrome')"

Browser description sent to WhatsApp. Format: [device, manufacturer, version].

import { Browsers } from '@whiskeysockets/baileys'

const sock = makeWASocket({
    auth: state,
    browser: Browsers.ubuntu('Chrome'),
    // Or custom:
    // browser: ['MyApp', 'MyCompany', '1.0.0']
})

Logging

logger

ILogger

default:"Pino logger"

Logger instance for debugging. Must implement trace, debug, info, warn, error, and fatal methods.

import P from 'pino'

const sock = makeWASocket({
    auth: state,
    logger: P({ level: 'debug' })
})

Behavior Configuration

emitOwnEvents

boolean

default:"true"

Whether to emit events for actions performed by this socket connection.

markOnlineOnConnect

boolean

default:"true"

Automatically mark the client as online when the socket successfully connects.

fireInitQueries

boolean

default:"true"

Automatically fire initialization queries on connection. Set to false if you want manual control.

syncFullHistory

boolean

default:"true"

Whether Baileys should ask the phone for full message history (received asynchronously).

countryCode

string

default:"'US'"

Alphanumeric country code for the phone number being used (e.g., ‘US’, ‘GB’, ‘IN’).

Message Handling

getMessage

(key: WAMessageKey) => Promise<proto.IMessage | undefined>

default:"async () => undefined"

Fetch a message from your store. Implement this to enable message retries for failed sends.

const getMessage = async (key) => {
    const data = await messageDB.get(key.id)
    return data?.message
}

const sock = makeWASocket({
    auth: state,
    getMessage
})

shouldSyncHistoryMessage

(msg: proto.Message.IHistorySyncNotification) => boolean

Control which history sync messages to process. Default skips FULL sync type.

shouldSyncHistoryMessage: ({ syncType }) => {
    return syncType !== proto.HistorySync.HistorySyncType.FULL
}

shouldIgnoreJid

(jid: string) => boolean | undefined

default:"() => false"

Return true to ignore events and messages from specific JIDs. Messages from ignored JIDs won’t be decrypted.

shouldIgnoreJid: (jid) => {
    // Ignore broadcast messages
    return jid === 'status@broadcast'
}

patchMessageBeforeSending

function

(msg: proto.IMessage, recipientJids?: string[]) =>
  Promise<PatchedMessageWithRecipientJID[] | PatchedMessageWithRecipientJID>
  | PatchedMessageWithRecipientJID[] | PatchedMessageWithRecipientJID

Optionally modify messages before sending. Default returns the message unchanged.

Media Configuration

customUploadHosts

MediaConnInfo['hosts']

default:"[]"

Custom upload hosts for media uploads.

linkPreviewImageThumbnailWidth

number

default:"192"

Width for link preview thumbnail images in pixels.

generateHighQualityLinkPreview

boolean

default:"false"

Generate high quality link previews by uploading the jpegThumbnail to WhatsApp.

options

RequestInit

default:"{}"

Options for HTTP fetch requests (headers, etc.).

Retry & Error Handling

retryRequestDelayMs

number

default:"250"

Time to wait between sending new retry requests in milliseconds.

maxMsgRetryCount

number

default:"5"

Maximum retry count for failed messages.

enableAutoSessionRecreation

boolean

default:"true"

Enable automatic session recreation for failed messages.

enableRecentMessageCache

boolean

default:"true"

Enable recent message caching for retry handling.

Caching

mediaCache

CacheStore

Cache to store media files to avoid re-uploading.

interface CacheStore {
    get<T>(key: string): Promise<T> | T | undefined
    set<T>(key: string, value: T): Promise<void> | void | number | boolean
    del(key: string): void | Promise<void> | number | boolean
    flushAll(): void | Promise<void>
}

msgRetryCounterCache

CacheStore

Cache to store retry counts for failed messages.

userDevicesCache

PossiblyExtendedCacheStore

Cache to store user device lists. Can optionally support batch operations:

interface PossiblyExtendedCacheStore extends CacheStore {
    mget?<T>(keys: string[]): Promise<Record<string, T | undefined>>
    mset?<T>(entries: { key: string; value: T }[]): Promise<void> | void
    mdel?(keys: string[]): void | Promise<void> | number | boolean
}

callOfferCache

CacheStore

Cache to store call offers.

placeholderResendCache

CacheStore

Cache to track placeholder resend requests.

Advanced Configuration

qrTimeout

number

Time to wait for QR code generation in milliseconds.

transactionOpts

TransactionCapabilityOptions

Transaction options for SignalKeyStore operations.

appStateMacVerification

object

default:"{ patch: false, snapshot: false }"

Verify app state MACs for security.

{
    patch: boolean
    snapshot: boolean
}

cachedGroupMetadata

(jid: string) => Promise<GroupMetadata | undefined>

default:"async () => undefined"

Provide cached group metadata to prevent redundant requests and speed up message sending.

const cachedGroupMetadata = async (jid) => {
    return await groupMetadataDB.get(jid)
}

const sock = makeWASocket({
    auth: state,
    cachedGroupMetadata
})

makeSignalRepository

function

(auth: SignalAuthState, logger: ILogger, pnToLIDFunc?: (jids: string[]) => Promise<LIDMapping[] | undefined>) => SignalRepositoryWithLIDStore

Factory function to create the Signal protocol repository. Default uses libsignal implementation.

Deprecated Options

mobile

boolean

deprecated

Deprecated. This feature has been removed. Previously used to switch between mobile and multi-device API.

printQRInTerminal

boolean

deprecated

Deprecated. This feature has been removed. Use the connection.update event to handle QR codes.

sock.ev.on('connection.update', (update) => {
    const { qr } = update
    if(qr) {
        // Use a QR code library to display
        console.log('QR Code:', qr)
    }
})

Example: Full Configuration

import makeWASocket, { 
    useMultiFileAuthState,
    Browsers,
    DisconnectReason 
} from '@whiskeysockets/baileys'
import P from 'pino'

const { state, saveCreds } = await useMultiFileAuthState('auth_info')

const sock = makeWASocket({
    // Required
    auth: state,
    
    // Connection
    connectTimeoutMs: 30000,
    keepAliveIntervalMs: 25000,
    defaultQueryTimeoutMs: 60000,
    
    // Client Info
    browser: Browsers.macOS('Chrome'),
    
    // Logging
    logger: P({ level: 'info' }),
    
    // Behavior
    emitOwnEvents: true,
    markOnlineOnConnect: true,
    syncFullHistory: false,
    
    // Message Handling
    getMessage: async (key) => {
        return await messageStore.loadMessage(key.id)
    },
    
    // Group Metadata Caching
    cachedGroupMetadata: async (jid) => {
        return await groupCache.get(jid)
    },
    
    // Media
    generateHighQualityLinkPreview: true,
    linkPreviewImageThumbnailWidth: 192,
    
    // Retry
    maxMsgRetryCount: 5,
    retryRequestDelayMs: 250,
    enableAutoSessionRecreation: true,
})

sock.ev.on('creds.update', saveCreds)

Core

Messages

Groups & Chats

Utilities

Socket Configuration

UserFacingSocketConfig

Required Configuration

Connection Configuration

Client Identification

Logging

Behavior Configuration

Message Handling

Media Configuration

Retry & Error Handling

Caching

Advanced Configuration

Deprecated Options

Example: Full Configuration

Build docs developers (and LLMs) love

Core

Messages

Groups & Chats

Utilities

Documentation Index

​UserFacingSocketConfig

​Required Configuration

​Connection Configuration

​Client Identification

​Logging

​Behavior Configuration

​Message Handling

​Media Configuration

​Retry & Error Handling

​Caching

​Advanced Configuration

​Deprecated Options

​Example: Full Configuration

Build docs developers (and LLMs) love

UserFacingSocketConfig

Required Configuration

Connection Configuration

Client Identification

Logging

Behavior Configuration

Message Handling

Media Configuration

Retry & Error Handling

Caching

Advanced Configuration

Deprecated Options

Example: Full Configuration