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
- Erstelle ein kostenloses TextMeFlow-Konto: 50 Nachrichten pro Monat, für immer, ohne Kreditkarte und ohne Meta-Business-Verifizierung.
- Scanne den QR-Code aus dem Portal mit dem Handy, auf dem die WhatsApp-Nummer läuft, von der du senden willst.
- 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