Envoyer un message WhatsApp avec Ruby on Rails (API)
L'API TextMeFlow, c'est du JSON simple sur HTTPS : une application Rails n'a donc pas besoin de gem pour communiquer avec elle. Net::HTTP (ou Faraday si vous l'utilisez déjà pour d'autres services) et OpenSSL, intégré à Ruby, suffisent pour envoyer des messages, réessayer en cas de limite de débit et vérifier les webhooks entrants. Ce guide passe en revue les trois, avec du code que vous pouvez placer tel quel dans un service object et un contrôleur.
Avant de commencer
- Créez un compte TextMeFlow gratuit : 50 messages par mois, pour toujours, sans carte bancaire et sans vérification Meta Business.
- Scannez le QR code du portail avec le téléphone qui contient le numéro WhatsApp depuis lequel vous voulez envoyer.
- Copiez votre clé d'API depuis le tableau de bord et votre secret de webhook depuis
/admin/webhook.
La référence complète des endpoints se trouve sur /fr/docs/api ; tout ce qui suit cible POST /v1/messages sur https://api.textmeflow.eu.
Un service d'envoi
Encapsulez l'appel dans un petit service object plutôt que de disperser des appels Net::HTTP dans les contrôleurs ou les jobs :
# 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
Gardez to au format E.164 (+32472932208) : un numéro sans le + initial ni l'indicatif pays est rejeté avec une erreur 422, et c'est le bug d'intégration le plus fréquent, quel que soit le langage. media_url est facultatif et accepte tout fichier accessible publiquement jusqu'à 100 Mo ; omettez-le pour un simple message texte. Un 202 signifie que le message est en file d'attente, pas qu'il est livré : le message_id du corps de la réponse vous sert ensuite à vérifier le statut réel.
Réessayer sur 429 depuis un job d'arrière-plan
Comme les applications Rails font déjà tourner Sidekiq ou GoodJob pour tout ce qui touche une API tierce, laissez le mécanisme de retry du job faire l'attente plutôt que de dormir en ligne :
# 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
Un corps 429 contient toujours reason (burst_exceeded ou hourly_exceeded) et retry_after_seconds, documentés sur la page des limites de débit : inutile de deviner un intervalle de backoff ou d'interroger en boucle serrée. Pour tout le raisonnement sur l'interrogation de GET /v1/messages/{id} par rapport à la confiance accordée aux webhooks pour le statut de livraison, voir gérer les limites de débit et le statut des messages.
Vérifier les webhooks entrants dans un contrôleur Rails
Les réponses des clients sont envoyées en POST à l'endpoint que vous configurez dans /admin/webhook, signées en HMAC-SHA256 sur le corps brut de la requête, dans un en-tête X-TextMeFlow-Signature: sha256=<hex>. ActionDispatch de Rails met le corps brut en mémoire tampon : lisez-le donc avec request.raw_post avant tout parsing JSON. Parser d'abord puis re-sérialiser pour comparer est la façon la plus courante dont cette vérification casse sans bruit :
# 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 est la comparaison en temps constant de Rails : utilisez-la à la place de ==, qui s'arrête au premier octet différent et laisse fuiter des informations de timing. X-TextMeFlow-Event-Id reste identique d'une tentative à l'autre : un index unique sur cette colonne (via ProcessedWebhookEvent) suffit donc pour éviter le double traitement. TextMeFlow réessaie les webhooks non livrés jusqu'à 5 fois avec un délai croissant, et toute réponse autre qu'un 2xx en moins de 10 secondes compte comme une tentative échouée. Répondez 200 immédiatement et confiez le vrai travail à perform_later : une action de contrôleur lente ressemble, du côté de TextMeFlow, à un timeout et déclenche des réessais inutiles. La liste complète des en-têtes et la forme de la charge utile figurent dans la documentation des webhooks ; la mécanique de signature est détaillée, avec PHP/Python/Node côte à côte, dans vérifier les signatures des webhooks WhatsApp.
Pour conclure
Une intégration Rails se compose de trois éléments : un POST Net::HTTP avec un jeton bearer, une politique de retry de job qui respecte retry_after_seconds plutôt qu'une pause fixe, et une vérification HMAC à l'entrée avec ActiveSupport::SecurityUtils.secure_compare, sans aucune gem. Démarrez gratuitement et vous pouvez avoir un service d'envoi et un contrôleur de webhook en marche avant votre prochain déploiement.
Envie d'envoyer des messages WhatsApp via API ?
Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.
Gratuit pour toujours