Session-based channel — Sessions use WhatsApp Web under the hood. This is a separate channel from the official WhatsApp Business Platform (Meta API). The phone must stay connected, and this channel is subject to WhatsApp Web limitations. For production workloads, we recommend using Business Accounts with the official Meta API.
List sessions
result = client.sessions.list
result.data # => Array of Session objects
result.meta # => { "total" => 2 }
Create a session
session = client.sessions.create(name: "My Session")
session.id # => "ses_01hx..."
session.status # => "qr_pending"
session.qr_code # => "data:image/png;base64,..."
Scan QR and wait for connection
session = client.sessions.create(name: "Production")
# Display QR to the user, poll until connected
session.wait_for_qr(timeout: 60, interval: 2) do |qr_code|
puts "Scan this QR: #{qr_code}"
end
session.connected? # => true
session.phone_number # => "+33612345678"
Retrieve a session
session = client.sessions.retrieve("ses_01hx...")
session.status # => "connected"
session.phone_number # => "+33612345678"
Reload session state
session.reload
session.refresh # alias
Delete a session
client.sessions.delete("ses_01hx...") # => true
Send messages
session = client.sessions.list.data.first
# Text
session.send_message(to: "+33699887766", text: "Hello!")
# Image
session.send_image(to: "+33699887766", url: "https://example.com/image.png")
# Video
session.send_video(to: "+33699887766", url: "https://example.com/video.mp4")
# Audio
session.send_audio(to: "+33699887766", url: "https://example.com/audio.ogg")
# Document
session.send_document(to: "+33699887766", url: "https://example.com/file.pdf")
# Location
session.send_location(to: "+33699887766", latitude: 48.8566, longitude: 2.3522)
# Contact
session.send_contact(to: "+33699887766", name: "John Doe", phone: "+33611223344")
Access the messages resource
messages = session.messages
# or:
messages = client.messages(session.id)
result = messages.list
msg = messages.retrieve("msg_01hz...")
Session attributes
| Attribute | Type | Description |
|---|---|---|
id | String | Session ID |
name | String | Session label |
status | String | connecting, qr_pending, connected, disconnected |
phone_number | String | Connected phone number |
qr_code | String | Base64 QR image (while qr_pending) |
status_reason | String | Reason for current status (e.g. phone_offline) |
connected | Boolean | Whether session is connected (boolean from API) |
last_connected_at | String | Last successful connection timestamp (ISO 8601) |
connected? | Boolean | Whether session is active |

