· 5 min · TextMeFlow Team

WhatsApp-Nachricht senden mit Ruby on Rails (API)

Die TextMeFlow-API ist schlichtes JSON über HTTPS, deshalb braucht eine Rails-App kein Gem, um mit ihr zu sprechen. Net::HTTP (oder Faraday, falls du es ohnehin für andere Dienste nutzt) und Rubys eingebautes OpenSSL reichen, um Nachrichten zu senden, Rate Limits zu wiederholen und eingehende Webhooks zu prüfen. Dieser Leitfaden geht alle drei Punkte durch, mit Code, den du direkt in ein Service Object und einen Controller übernehmen kannst.

Bevor du startest

  1. Erstelle ein kostenloses TextMeFlow-Konto: 50 Nachrichten pro Monat, für immer, ohne Kreditkarte und ohne Meta-Business-Verifizierung.
  2. Scanne den QR-Code aus dem Portal mit dem Handy, auf dem die WhatsApp-Nummer läuft, von der du senden willst.
  3. Kopiere deinen API-Schlüssel aus dem Dashboard und dein Webhook-Secret aus /admin/webhook.

Die vollständige Endpunkt-Referenz findest du unter /de/docs/api. Alles Folgende bezieht sich auf POST /v1/messages auf https://api.textmeflow.eu.

Ein Sende-Service

Kapsle den Aufruf in einem kleinen Service Object, statt Net::HTTP-Aufrufe über Controller oder Jobs zu verstreuen:

# app/services/text_me_flow/client.rb
require "net/http"
require "json"
require "uri"

module TextMeFlow
  class Client
    BASE_URL = "https://api.textmeflow.eu"

    def initialize(api_key: Rails.application.credentials.textmeflow_api_key)
      @api_key = api_key
    end

    def send_message(to:, text: nil, media_url: nil)
      uri = URI("#{BASE_URL}/v1/messages")
      request = Net::HTTP::Post.new(uri)
      request["Content-Type"] = "application/json"
      request["Authorization"] = "Bearer #{@api_key}"
      request.body = { to: to, text: text, media_url: media_url }.compact.to_json

      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
      handle_response(response)
    end

    private

    def handle_response(response)
      case response.code.to_i
      when 202
        JSON.parse(response.body)
      when 429
        raise RateLimited.new(JSON.parse(response.body))
      else
        raise Error, "textmeflow: unexpected status #{response.code} — #{response.body}"
      end
    end
  end

  class Error < StandardError; end
  class RateLimited < Error
    attr_reader :reason, :retry_after_seconds
    def initialize(body)
      @reason = body["reason"]
      @retry_after_seconds = body["retry_after_seconds"]
      super("rate limited: #{@reason}")
    end
  end
end

Halte to im E.164-Format (+32472932208). Eine Nummer ohne führendes + und Ländervorwahl wird mit 422 abgelehnt und ist in jeder Sprache der häufigste Integrationsfehler. media_url ist optional und akzeptiert jede öffentlich erreichbare Datei bis 100 MB; lass es für eine reine Textnachricht weg. Ein 202 bedeutet, dass die Nachricht eingereiht ist, nicht dass sie zugestellt wurde. Mit der message_id aus dem Response-Body prüfst du anschließend den tatsächlichen Status.

Bei 429 aus einem Hintergrundjob wiederholen

Da Rails-Apps für alles, was eine Drittanbieter-API berührt, ohnehin Sidekiq oder GoodJob laufen lassen, überlass das Warten dem Retry-Mechanismus des Jobs, statt inline zu schlafen:

# app/jobs/send_whatsapp_job.rb
class SendWhatsappJob < ApplicationJob
  queue_as :default
  retry_on TextMeFlow::RateLimited,
           wait: ->(executions) { TextMeFlow::RateLimited.new({}).retry_after_seconds || executions * 5 },
           attempts: 5

  def perform(to:, text:)
    TextMeFlow::Client.new.send_message(to: to, text: text)
  end
end

Ein 429-Body enthält immer reason (burst_exceeded oder hourly_exceeded) und retry_after_seconds, dokumentiert auf der Seite zu Rate Limits. Du musst also weder ein Backoff-Intervall raten noch in einer engen Schleife pollen. Die ganze Abwägung zwischen Polling von GET /v1/messages/{id} und dem Vertrauen auf Webhooks für den Zustellstatus findest du unter Rate Limits und Nachrichtenstatus handhaben.

Eingehende Webhooks in einem Rails-Controller prüfen

Antworten von Kunden werden per POST an den Endpunkt geschickt, den du in /admin/webhook konfigurierst, signiert per HMAC-SHA256 über den rohen Request-Body in einem X-TextMeFlow-Signature: sha256=<hex>-Header. ActionDispatch in Rails puffert den rohen Body, lies ihn also mit request.raw_post, bevor JSON geparst wird. Erst parsen und dann zum Vergleich neu serialisieren ist der häufigste Grund, warum diese Prüfung unbemerkt kaputtgeht:

# app/controllers/webhooks/text_me_flow_controller.rb
class Webhooks::TextMeFlowController < ActionController::API
  skip_before_action :verify_authenticity_token, raise: false

  def create
    raw = request.raw_post
    secret = Rails.application.credentials.textmeflow_webhook_secret
    expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, raw)
    received = request.headers["X-TextMeFlow-Signature"].to_s

    unless ActiveSupport::SecurityUtils.secure_compare(expected, received)
      return head :unauthorized
    end

    event_id = request.headers["X-TextMeFlow-Event-Id"]
    return head :ok if ProcessedWebhookEvent.exists?(event_id: event_id)

    ProcessedWebhookEvent.create!(event_id: event_id)
    HandleIncomingWhatsappJob.perform_later(JSON.parse(raw))
    head :ok
  end
end

ActiveSupport::SecurityUtils.secure_compare ist der Konstantzeit-Vergleich von Rails. Verwende ihn statt ==, das beim ersten abweichenden Byte abbricht und Timing-Informationen preisgibt. X-TextMeFlow-Event-Id bleibt über Wiederholungen hinweg gleich, ein eindeutiger Index auf dieser Spalte (über ProcessedWebhookEvent) reicht also, um doppelte Verarbeitung zu vermeiden: TextMeFlow wiederholt nicht zugestellte Webhooks bis zu 5 Mal mit steigender Wartezeit, und alles außer einer 2xx-Antwort innerhalb von 10 Sekunden zählt als fehlgeschlagener Versuch. Antworte sofort mit 200 und übergib die eigentliche Arbeit an perform_later. Eine langsame Controller-Action sieht aus Sicht von TextMeFlow wie ein Timeout aus und wird unnötig wiederholt. Die vollständige Header-Liste und die Payload-Struktur stehen in der Webhook-Dokumentation; die Signaturmechanik wird ausführlicher, mit PHP/Python/Node nebeneinander, in WhatsApp-Webhook-Signaturen verifizieren behandelt.

Zusammenfassung

Eine Rails-Integration besteht aus drei Teilen: einem Net::HTTP-POST mit Bearer-Token, einer Job-Retry-Strategie, die retry_after_seconds respektiert statt fester Pause, und einer HMAC-Prüfung beim Eingang mit ActiveSupport::SecurityUtils.secure_compare. Ein Gem ist nicht nötig. Starte kostenlos und du hast einen Sende-Service und einen Webhook-Controller laufen, noch bevor dein nächstes Deployment ansteht.

Selbst WhatsApp-Nachrichten per API senden?

Für immer gratis bis 50 Nachrichten/Monat. QR scannen und in 5 Minuten die erste Nachricht senden.

Für immer gratis