waha-ruby

Framework-neutral Ruby client for the WAHA WhatsApp HTTP API. It provides resource-oriented access to sessions, messages, media, chats, contacts, presence, webhooks, and explicit GOWS helpers, with an opt-in Rails adapter.

waha-ruby is an independent community project, not an official WAHA project. WAHA is documented at waha.dev and developed at devlikeapro/waha. This gem links to the Apache-2.0 upstream project and does not copy its code.

• Ruby 4.0.5 or newer
• WAHA v2025.9 or a compatible WAHA HTTP API deployment
• An API key when the WAHA deployment requires one

The gem is tested against the declared v0.1 API surface. WAHA server versions can add or change response fields; the client returns parsed provider JSON without imposing a domain model.

Add the gem to your application:

gem "waha-ruby"

Then run bundle install. The only runtime dependency is faraday.

require "waha"

client = Waha::Client.new(
  base_url: ENV.fetch("WAHA_BASE_URL"),
  api_key: ENV["WAHA_API_KEY"],
  session: ENV.fetch("WAHA_SESSION", "default")
)

client.sessions.list
client.messages.send_text(chat_id: "5511999999999@c.us", text: "Olá")

Every request uses the client's default session unless a resource method accepts an explicit session: override. Keep credentials in environment variables or a secret manager; do not commit them.

Applications that prefer process-wide defaults can configure the module once and build a fresh client per call:

Waha.configure do |config|
  config.base_url = ENV.fetch("WAHA_BASE_URL")
  config.api_key = ENV["WAHA_API_KEY"]
  config.session = ENV.fetch("WAHA_SESSION", "default")
end

Waha.configured?                 # => true
Waha.client(session: "default")  # a new Waha::Client, never cached

Waha.client never caches instances, so per-call session overrides cannot leak across callers.

The complete v0.1 resource map, argument conventions, raw return shapes, file payloads, errors, GOWS helpers, webhook verification, and Rails integration are in docs/api.md. For setup and secret handling, see docs/installation.md.

The client sends X-Api-Key to WAHA and never logs credentials. Error details are bounded and redacted before they are placed in Waha::Error messages. Treat raw response hashes as untrusted provider data and redact message text, phone numbers, media URLs, and API keys before logging or persisting them. Webhook verification must run against the exact raw request body before JSON parsing.

asdf install
bundle install
bundle exec rspec path/to/spec.rb
bin/ci

See CONTRIBUTING.md for quality rules and releases. See CHANGELOG.md for changes.

MIT. See LICENSE.txt.