waservix 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c3051c5426d31968d5f9c5fb891871698ec55b7c9f8efbbd91cd4b1f6f17dc2d
+  data.tar.gz: e45c7a50952b53cc4d9ddb756f9abbce88424cd8aa2af374bba63fa6be1b931c
+SHA512:
+  metadata.gz: 7f035fc9c42f8ca4699a738efaf5f13fb1ba3cd8d152a2b9b8a4337e94ea5cfc2a2d67cb68d52957678e8b4b7ba9441fc4433ffa83c155f1d8d4fd1aee0d9f6b
+  data.tar.gz: 752ff0e00f931b4e02242faf9c2bc9af29a921ca25c08090b0ef42f0ee2816d33a3c8d7bcbfecd0e14d90b4e8d69e504fa43214b2be4d34ce4a966b582aec74e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tekservix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,116 @@
+# WAservix Ruby client
+
+[![Gem Version](https://badge.fury.io/rb/waservix.svg)](https://rubygems.org/gems/waservix)
+
+Ruby client for the [WAservix WhatsApp API Gateway](https://tekservix.com/waservix/).
+
+WAservix links your own WhatsApp number by QR code (the same way WhatsApp Web does) and gives you a REST API to send text, images, video, audio, documents, locations, polls and more, with webhooks for incoming messages and status updates.
+
+- Ruby 2.7+, no dependencies (standard library only)
+- Works in Rails, Sinatra, Hanami, Sidekiq jobs and scripts
+- Webhook check built in
+
+## Install
+
+```bash
+gem install waservix
+```
+
+or in your Gemfile:
+
+```ruby
+gem 'waservix'
+```
+
+## Quick start
+
+Copy your device's API key from the WAservix dashboard (Devices -> API key) and keep it on your server.
+
+```ruby
+require 'waservix'
+
+wa = WAservix::Client.new(api_key: ENV['WASERVIX_KEY'])
+
+res = wa.send_text('+15551234567', 'Hello Aline, your order is ready')
+res['msgId']  # => 58213
+res['status'] # => "in_progress"
+```
+
+## Sending
+
+Messages are queued and sent one at a time per number, so each call returns right away with `status: "in_progress"` and a `msgId`.
+
+```ruby
+# Image with caption
+wa.send_image('+15551234567', 'https://example.com/product.jpg', caption: 'Back in stock')
+
+# Document
+wa.send_document('+15551234567', 'https://example.com/inv-1042.pdf', file_name: 'Invoice-1042.pdf', caption: 'Your invoice')
+
+# Anything the API supports, including groups (JID ending in @g.us)
+wa.send_message('120363040000000000@g.us', text: 'Team meeting at 3pm')
+wa.send_message('+15551234567', location: { latitude: -1.9441, longitude: 30.0619, name: 'Our shop' })
+```
+
+## Status, contacts and groups
+
+```ruby
+info  = wa.get_message_info(58213)       # queued, sent, delivered, read, played or failed
+check = wa.on_whatsapp('+15551234567')   # { "exists" => true, "jid" => "..." }
+conn  = wa.get_status                    # { "status" => "connected" }
+
+wa.edit_message(58213, 'Corrected text') # own text messages, about 15 minutes
+groups = wa.list_groups
+```
+
+Anything else in the [API reference](https://tekservix.com/waservix/docs/) is one call away:
+
+```ruby
+wa.request(:post, '/messages/read', { msgId: '3EB0X123456789' })
+```
+
+## Webhooks
+
+Set a webhook URL and events for the number in the dashboard. Each request carries `X-Webhook-Signature`, which equals the device's webhook secret. Rails example:
+
+```ruby
+class WaWebhooksController < ActionController::API
+  def create
+    unless WAservix.verify_webhook(request.headers['X-Webhook-Signature'], ENV['WASERVIX_WEBHOOK_SECRET'])
+      return head :unauthorized
+    end
+
+    payload = JSON.parse(request.raw_post)
+    if payload['event'] == 'messages.received'
+      m = payload['data']['messages']
+      IncomingWhatsAppJob.perform_later(m['key']['cleanedSenderPn'], m['messageBody'])
+    end
+    head :ok # acknowledge fast; do slow work in a job
+  end
+end
+```
+
+## Errors
+
+Failed calls raise `WAservix::Error` with `status`, `message`, field `errors` and, on 429, `retry_after` in seconds. A 503 means the device is reconnecting: retry shortly.
+
+Never put the key in JavaScript or a mobile app: anyone could read it. Call the API from your server.
+
+## Migrating from WaSender
+
+WAservix accepts the same `/send-message` body and webhook fields as WaSender, so most integrations switch by changing the base URL and key. See the [compatibility notes](https://tekservix.com/waservix/docs/).
+
+## Use it responsibly
+
+WAservix is not Meta's official WhatsApp Business Platform. There's no business verification and no per-conversation fee, but WhatsApp's spam rules apply to your number directly. Message people who expect to hear from you, warm up new numbers slowly and keep the built-in account protection on.
+
+## More from Tekservix
+
+- [SMS Gora SMS Gateway](https://tekservix.com/smsgora/): send SMS through your own Android phones (`gem install smsgora`)
+- [AI Sales Agent](https://tekservix.com/ai-sales-agent): answers customers on WhatsApp and SMS using your website's content
+- [Website to App](https://tekservix.com/mobile-apps): turn your website into Android and iOS apps
+- WAservix is also available for Node.js, Python, PHP, Go, Java/Kotlin and .NET: see [github.com/TekservixHQ](https://github.com/TekservixHQ)
+
+## License
+
+MIT

data/lib/waservix.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+# Ruby client for the WAservix WhatsApp API Gateway.
+#
+#   wa = WAservix::Client.new(api_key: ENV['WASERVIX_KEY'])
+#   wa.send_text('+15551234567', 'Hello Aline, your order is ready')
+#
+# Docs: https://tekservix.com/waservix/docs/
+module WAservix
+  VERSION = '1.0.0'
+  DEFAULT_BASE_URL = 'https://tekservix.com/waservix/api'
+
+  # Raised when the API answers with an error. A 503 means the device is reconnecting.
+  class Error < StandardError
+    attr_reader :status, :errors, :body, :retry_after
+
+    def initialize(message, status: nil, errors: nil, body: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @errors = errors
+      @body = body
+      @retry_after = retry_after
+    end
+  end
+
+  class Client
+    attr_reader :base_url
+
+    # api_key: device API key (wpk_...) or a personal access token for session management.
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 30)
+      raise ArgumentError, 'WAservix: api_key is required (Devices -> API key in the WAservix dashboard)' if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, '')
+      @timeout = timeout
+    end
+
+    # Call any documented endpoint, e.g. request(:get, '/groups'). Returns the `data` field.
+    def request(method, path, body = nil)
+      uri = URI(@base_url + path)
+      klass = { get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put, delete: Net::HTTP::Delete }.fetch(method.to_s.downcase.to_sym)
+      req = klass.new(uri)
+      req['Authorization'] = "Bearer #{@api_key}"
+      req['Accept'] = 'application/json'
+      req['User-Agent'] = "waservix-ruby/#{VERSION}"
+      unless body.nil?
+        req['Content-Type'] = 'application/json'
+        req.body = JSON.generate(body)
+      end
+
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
+                                                open_timeout: @timeout, read_timeout: @timeout) { |http| http.request(req) }
+      status = res.code.to_i
+      text = res.body.to_s
+      json = begin
+        text.empty? ? nil : JSON.parse(text)
+      rescue JSON::ParserError
+        nil
+      end
+
+      if status >= 400 || (json.is_a?(Hash) && json['success'] == false)
+        retry_after = res['Retry-After']
+        raise Error.new((json.is_a?(Hash) && json['message']) || "HTTP #{status}",
+                        status: status,
+                        errors: json.is_a?(Hash) ? json['errors'] : nil,
+                        body: json || text,
+                        retry_after: retry_after && Float(retry_after, exception: false))
+      end
+      json.is_a?(Hash) && json.key?('data') ? json['data'] : json
+    end
+
+    # Send any message type to a number or group JID (...@g.us). Fields use the API names:
+    # text, imageUrl, videoUrl, audioUrl, documentUrl, fileName, stickerUrl, contact, location,
+    # poll, replyTo, mentions, viewOnce. Returns { 'msgId' => ..., 'jid' => ..., 'status' => 'in_progress' }.
+    def send_message(to, **fields)
+      raise ArgumentError, 'send_message: "to" is required (international number or group JID)' if to.nil? || to.empty?
+
+      request(:post, '/send-message', { to: to }.merge(fields.reject { |_, v| v.nil? }))
+    end
+
+    def send_text(to, text)
+      send_message(to, text: text)
+    end
+
+    def send_image(to, image_url, caption: nil)
+      send_message(to, imageUrl: image_url, text: caption)
+    end
+
+    def send_document(to, document_url, file_name: nil, caption: nil)
+      send_message(to, documentUrl: document_url, fileName: file_name, text: caption)
+    end
+
+    # Status: queued, sent, delivered, read, played or failed.
+    def get_message_info(msg_id)
+      request(:get, "/messages/#{esc(msg_id)}/info")
+    end
+
+    # Edit one of your own text messages (about 15 minutes after sending).
+    def edit_message(msg_id, text)
+      request(:put, "/messages/#{esc(msg_id)}", { text: text })
+    end
+
+    def delete_message(msg_id)
+      request(:delete, "/messages/#{esc(msg_id)}")
+    end
+
+    def resend_message(msg_id)
+      request(:post, "/messages/#{esc(msg_id)}/resend")
+    end
+
+    # Is this number on WhatsApp? Returns { 'exists' => true/false, 'jid' => ... }.
+    def on_whatsapp(phone)
+      request(:get, "/on-whatsapp/#{esc(phone)}")
+    end
+
+    # connected, connecting, need_scan, disconnected, logged_out or expired.
+    def get_status
+      request(:get, '/status')
+    end
+
+    def get_user
+      request(:get, '/user')
+    end
+
+    def list_contacts
+      request(:get, '/contacts')
+    end
+
+    def get_contact(phone)
+      request(:get, "/contacts/#{esc(phone)}")
+    end
+
+    def save_contact(phone, name)
+      request(:put, '/contacts', { phone: phone, name: name })
+    end
+
+    def list_groups
+      request(:get, '/groups')
+    end
+
+    def get_group_metadata(group_jid)
+      request(:get, "/groups/#{esc(group_jid)}/metadata")
+    end
+
+    # Session management (needs a personal access token, not a device key).
+    def list_sessions
+      request(:get, '/whatsapp-sessions')
+    end
+
+    def get_session(id)
+      request(:get, "/whatsapp-sessions/#{esc(id)}")
+    end
+
+    def create_session(**params)
+      request(:post, '/whatsapp-sessions', params)
+    end
+
+    # method: 'qr', or 'code' with phone: for pairing codes.
+    def connect_session(id, method: 'qr', phone: nil)
+      body = { method: method }
+      body[:phone] = phone if phone
+      request(:post, "/whatsapp-sessions/#{esc(id)}/connect", body)
+    end
+
+    def get_session_qr_code(id)
+      request(:get, "/whatsapp-sessions/#{esc(id)}/qrcode")
+    end
+
+    private
+
+    def esc(value)
+      URI.encode_www_form_component(value.to_s).gsub('+', '%20')
+    end
+  end
+
+  # Constant-time check of the X-Webhook-Signature header against your device's webhook secret.
+  def self.verify_webhook(signature, secret)
+    return false if signature.nil? || signature.empty? || secret.nil? || secret.empty?
+    secure_compare(signature.to_s, secret.to_s)
+  end
+
+  # Constant-time string comparison (works on every Ruby version).
+  def self.secure_compare(a, b)
+    return false unless a.bytesize == b.bytesize
+
+    diff = 0
+    a.bytes.zip(b.bytes) { |x, y| diff |= x ^ y }
+    diff.zero?
+  end
+  private_class_method :secure_compare
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: waservix
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tekservix
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-10 00:00:00.000000000 Z
+dependencies: []
+description: 'Send WhatsApp messages, images and documents from your own number with
+  WAservix: status tracking, contacts, groups and webhooks. Works in Rails, Sinatra
+  and plain Ruby.'
+email: support@tekservix.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/waservix.rb
+homepage: https://tekservix.com/waservix/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://tekservix.com/waservix/
+  documentation_uri: https://tekservix.com/waservix/docs/
+  source_code_uri: https://github.com/TekservixHQ/waservix-ruby
+  bug_tracker_uri: https://github.com/TekservixHQ/waservix-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby client for the WAservix WhatsApp API Gateway
+test_files: []