Class: Whatsapp::Session

Inherits:
Object
  • Object
show all
Includes:
Concerns::GroupMethods, Concerns::MessageSending
Defined in:
lib/whatsapp/session.rb

Overview

A named WhatsApp session with its own bridge, auth state, and events.

Each session represents one WhatsApp account. Sessions are managed by SessionManager and can be accessed via +Whatsapp.session("name")+.

Examples:

session = Whatsapp.session("hotel_42")
session.connect
session.on_qr { |qr| display_qr(qr) }
session.send_message(to: "+33612345678", text: "Bienvenue!")
session.disconnect

Constant Summary collapse

STATUSES =

Valid session statuses.

%i[disconnected connecting qr_pending connected].freeze
EVENT_CALLBACKS =

Event callbacks delegated to the client.

%i[
  on_message on_message_any on_qr on_connected
  on_message_status on_message_sent on_message_delivered on_message_read
  on_presence_update on_message_receipt on_poll_vote
  on_contacts_update
].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Concerns::MessageSending

#react, #reply, #send_audio, #send_contact, #send_document, #send_image, #send_location, #send_poll, #send_sticker, #send_video

Methods included from Concerns::GroupMethods

#add_group_participants, #create_group, #group, #groups, #remove_group_participants, #update_group

Constructor Details

#initialize(name, config: Whatsapp.configuration) ⇒ Session

Returns a new instance of Session.

Parameters:

  • name (String) —

    session name

  • config (Configuration) (defaults to: Whatsapp.configuration) —

    gem configuration



46
47
48
49
50
51
52
53
54
55
 
# File 'lib/whatsapp/session.rb', line 46

def initialize(name, config: Whatsapp.configuration)
  @name = name
  @config = build_session_config(config)
  @client = Client.new(config: @config)
  @status = :disconnected
  @qr_data = nil
  @heartbeat = Heartbeat.new(self, interval: config.heartbeat_interval)
  @mutex = Mutex.new
  setup_event_tracking
end

Instance Attribute Details

#client ⇒ Client (readonly)

Returns the underlying WhatsApp client.

Returns:

  • (Client) —

    the underlying WhatsApp client



33
34
35
 
# File 'lib/whatsapp/session.rb', line 33

def client
  @client
end

#heartbeat ⇒ Heartbeat (readonly)

Returns the health check instance for this session.

Returns:

  • (Heartbeat) —

    the health check instance for this session



42
43
44
 
# File 'lib/whatsapp/session.rb', line 42

def heartbeat
  @heartbeat
end

#name ⇒ String (readonly)

Returns session name (used as directory name for auth state).

Returns:

  • (String) —

    session name (used as directory name for auth state)



30
31
32
 
# File 'lib/whatsapp/session.rb', line 30

def name
  @name
end

#qr_data ⇒ String? (readonly)

Returns base64-encoded QR code data (when status is +:qr_pending+).

Returns:

  • (String, nil) —

    base64-encoded QR code data (when status is +:qr_pending+)



36
37
38
 
# File 'lib/whatsapp/session.rb', line 36

def qr_data
  @qr_data
end

#status ⇒ Symbol (readonly)

Returns current session status (see STATUSES).

Returns:

  • (Symbol) —

    current session status (see STATUSES)



39
40
41
 
# File 'lib/whatsapp/session.rb', line 39

def status
  @status
end

Instance Method Details

#business_profile(phone) ⇒ Hash

Get a contact's business profile.

Parameters:

  • phone (String) —

    phone number or JID

Returns:

  • (Hash) 


156
157
158
 
# File 'lib/whatsapp/session.rb', line 156

def business_profile(phone)
  @client.business_profile(phone)
end

#connect ⇒ self

Start the bridge and connect to WhatsApp.

Returns:

  • (self) 


60
61
62
63
64
65
 
# File 'lib/whatsapp/session.rb', line 60

def connect
  @mutex.synchronize { @status = :connecting }
  @client.connect
  @heartbeat.start if @config.heartbeat_enabled
  self
end

#connected? ⇒ Boolean

Whether the session is connected to WhatsApp.

Returns:

  • (Boolean) 


83
84
85
 
# File 'lib/whatsapp/session.rb', line 83

def connected?
  status == :connected
end

#disconnect ⇒ self

Disconnect from WhatsApp and stop the bridge.

Returns:

  • (self) 


70
71
72
73
74
75
76
77
78
 
# File 'lib/whatsapp/session.rb', line 70

def disconnect
  @heartbeat.stop
  @client.disconnect
  @mutex.synchronize do
    @status = :disconnected
    @qr_data = nil
  end
  self
end

#events ⇒ Events

Access the event emitter.

Returns:



246
247
248
 
# File 'lib/whatsapp/session.rb', line 246

def events
  @client.events
end

#fetch_status(phone) ⇒ Hash

Get a contact's status/about text.

Parameters:

  • phone (String) —

    phone number or JID

Returns:

  • (Hash) 


148
149
150
 
# File 'lib/whatsapp/session.rb', line 148

def fetch_status(phone)
  @client.fetch_status(phone)
end

#on(event_name) {|data| ... } ⇒ void

This method returns an undefined value.

Register a handler for a custom event.

Parameters:

  • event_name (String) —

    event name

Yields:

  • (data) —

    event payload



225
226
227
 
# File 'lib/whatsapp/session.rb', line 225

def on(event_name, &block)
  @client.on(event_name, &block)
end

#on_connected(&block) ⇒ void

This method returns an undefined value.

Register a handler for successful connection.




# File 'lib/whatsapp/session.rb', line 177

#on_contacts_update(&block) ⇒ void

This method returns an undefined value.

Register a handler for contact list updates.



214
215
216
217
218
 
# File 'lib/whatsapp/session.rb', line 214

EVENT_CALLBACKS.each do |method_name|
  define_method(method_name) do |&block|
    @client.send(method_name, &block)
  end
end

#on_message {|message| ... } ⇒ void

This method returns an undefined value.

Register a handler for new incoming messages.

Yields:

  • (message) —

    called for each new message

Yield Parameters:




# File 'lib/whatsapp/session.rb', line 160

#on_message_any {|message| ... } ⇒ void

This method returns an undefined value.

Register a handler for all messages (live + history sync).

Yields:

  • (message)

Yield Parameters:




# File 'lib/whatsapp/session.rb', line 166

#on_message_delivered(&block) ⇒ void

This method returns an undefined value.

Register a handler for "delivered" status.




# File 'lib/whatsapp/session.rb', line 190

#on_message_read(&block) ⇒ void

This method returns an undefined value.

Register a handler for "read" status.




# File 'lib/whatsapp/session.rb', line 194

#on_message_receipt(&block) ⇒ void

This method returns an undefined value.

Register a handler for message receipt updates.




# File 'lib/whatsapp/session.rb', line 202

#on_message_sent(&block) ⇒ void

This method returns an undefined value.

Register a handler for "sent" status.




# File 'lib/whatsapp/session.rb', line 186

#on_message_status {|data| ... } ⇒ void

This method returns an undefined value.

Register a handler for message status changes.

Yields:

  • (data) —

    +{ id:, to:, status:, status_code: }+




# File 'lib/whatsapp/session.rb', line 181

#on_poll_vote(&block) ⇒ void

This method returns an undefined value.

Register a handler for poll vote results.




# File 'lib/whatsapp/session.rb', line 206

#on_presence_update(&block) ⇒ void

This method returns an undefined value.

Register a handler for presence updates.




# File 'lib/whatsapp/session.rb', line 198

#on_qr {|qr| ... } ⇒ void

This method returns an undefined value.

Register a handler for QR code events.

Yields:

  • (qr) —

    base64 QR data




# File 'lib/whatsapp/session.rb', line 172

#on_whatsapp?(phone) ⇒ Hash

Check if a phone number is registered on WhatsApp.

Parameters:

  • phone (String) —

    phone number

Returns:

  • (Hash) 


131
132
133
 
# File 'lib/whatsapp/session.rb', line 131

def on_whatsapp?(phone)
  @client.on_whatsapp?(phone)
end

#profile_picture(phone, high_res: false) ⇒ Hash

Get a contact's profile picture URL.

Parameters:

  • phone (String) —

    phone number or JID

  • high_res (Boolean) (defaults to: false) —

    full-resolution image

Returns:

  • (Hash) 


140
141
142
 
# File 'lib/whatsapp/session.rb', line 140

def profile_picture(phone, high_res: false)
  @client.profile_picture(phone, high_res: high_res)
end

#qr_pending? ⇒ Boolean

Whether the session is waiting for a QR code scan.

Returns:

  • (Boolean) 


90
91
92
 
# File 'lib/whatsapp/session.rb', line 90

def qr_pending?
  status == :qr_pending
end

#rate_limit_stats ⇒ Hash

Get rate limiting statistics.

Returns:

  • (Hash) 


232
233
234
 
# File 'lib/whatsapp/session.rb', line 232

def rate_limit_stats
  @client.rate_limit_stats
end

#read_messages(keys) ⇒ Hash

Mark messages as read.

Parameters:

  • keys (Array<Hash>) —

    message keys

Returns:

  • (Hash) 


123
124
125
 
# File 'lib/whatsapp/session.rb', line 123

def read_messages(keys)
  @client.read_messages(keys)
end

#safety_status ⇒ Hash

Get comprehensive safety status for monitoring.

Returns:

  • (Hash) —

    safety status with risk level, usage percentages, and features



239
240
241
 
# File 'lib/whatsapp/session.rb', line 239

def safety_status
  @client.safety_status
end

#send_message(to:, text: nil, media: nil, location: nil, contact: nil, react: nil, poll: nil, quoted_message_id: nil, unsafe: false) ⇒ Message

Send a message through this session.

Parameters:

  • to (String) —

    recipient phone number (e.g. "+33612345678")

  • text (String, nil) (defaults to: nil) —

    text content

  • media (Hash, nil) (defaults to: nil) —

    media payload (+{ type:, file:, caption:, filename: }+)

  • location (Hash, nil) (defaults to: nil) —

    location payload (+{ latitude:, longitude:, name:, address: }+)

  • contact (Hash, nil) (defaults to: nil) —

    contact payload (+{ name:, phone: }+)

  • react (Hash, nil) (defaults to: nil) —

    reaction payload (+{ emoji:, message_id: }+)

  • poll (Hash, nil) (defaults to: nil) —

    poll payload (+{ question:, options:, selectable_count: }+)

  • quoted_message_id (String, nil) (defaults to: nil) —

    ID of message to quote (reply)

  • unsafe (Boolean) (defaults to: false) —

    skip all safety checks. Use with extreme caution — bypasses rate limiting, typing simulation, and all anti-ban protections.

Returns:



98
99
100
 
# File 'lib/whatsapp/session.rb', line 98

def send_message(to:, text: nil, media: nil, location: nil, contact: nil, react: nil, poll: nil, quoted_message_id: nil, unsafe: false)
  @client.send_message(to: to, text: text, media: media, location: location, contact: contact, react: react, poll: poll, quoted_message_id: quoted_message_id, unsafe: unsafe)
end

#send_presence(type, to: nil) ⇒ Hash

Send a presence update through this session.

Parameters:

  • type (String) —

    presence type

  • to (String, nil) (defaults to: nil) —

    recipient JID

Returns:

  • (Hash) 


107
108
109
 
# File 'lib/whatsapp/session.rb', line 107

def send_presence(type, to: nil)
  @client.send_presence(type, to: to)
end

#subscribe_presence(jid) ⇒ Hash

Subscribe to presence updates for a JID.

Parameters:

  • jid (String) —

    JID to subscribe to

Returns:

  • (Hash) 


115
116
117
 
# File 'lib/whatsapp/session.rb', line 115

def subscribe_presence(jid)
  @client.subscribe_presence(jid)
end

#to_h ⇒ Hash

Session info as a hash.

Returns:

  • (Hash) —

    +{ name:, status:, qr_pending:, rate_limits:, heartbeat: }+



253
254
255
256
257
258
259
260
261
 
# File 'lib/whatsapp/session.rb', line 253

def to_h
  {
    name: name,
    status: status,
    qr_pending: qr_pending?,
    rate_limits: rate_limit_stats,
    heartbeat: @heartbeat.to_h
  }
end