evolution

     

R wrapper for Evolution API v2 — a lightweight WhatsApp API.

Overview

evolution is a tidy-style R client for the Evolution API v2, a RESTful platform that enables automation across WhatsApp (via Web/Baileys or Cloud API modes) and other channels. It wraps HTTP calls using {httr2}, exposes snake_case helper functions, and integrates structured logging with {cli} for use in modern R pipelines and production ETL tasks.

With evolution you can:

• Send plain text, media (image/video/document), WhatsApp audio, stickers, or status (stories)
• Send locations, contacts, buttons, or polls
• Check if a number is on WhatsApp
• Use options(evolution.timeout) to control timeouts and verbose = TRUE for detailed logs

Note: This package is an independent wrapper for the Evolution API and is not affiliated with WhatsApp or Meta.

Installation

# install.packages("remotes")
remotes::install_github("StrategicProjects/evolution")

Quick Start

library(evolution)

client <- evo_client(
  base_url = "https://YOUR-HOST",
  api_key  = Sys.getenv("EVO_APIKEY"),
  instance = "yourInstance"
)

# Optional: set a global timeout
options(evolution.timeout = 60)

# Example: Send a simple message
send_text(client, "+5581999990000", "Hello from R!", verbose = TRUE)

Functions Overview

Function	Description	Key Arguments
evo_client()	Creates preconfigured client	base_url, api_key, instance
send_text()	Sends plain text message	number, text, delay, verbose
send_status()	Sends status (text or media)	type, content, caption, verbose
send_media()	Sends image/video/document (URL, base64, or file)	number, mediatype, mimetype, media, file_name
send_whatsapp_audio()	Sends voice note (PTT)	number, audio, verbose
send_sticker()	Sends sticker (URL or base64)	number, sticker, verbose
send_location()	Sends location pin	number, latitude, longitude, name
send_contact()	Sends one or more contacts (auto wuid)	number, contact, verbose
send_reaction()	Sends emoji reaction to message	key, reaction, verbose
send_buttons()	Sends message with interactive buttons	number, buttons, verbose
send_poll()	Sends a poll	number, name, values, verbose
check_is_whatsapp()	Verifies numbers	numbers
jid()	Builds WhatsApp JID	number

Examples

Send Text

send_text(client, "+5581999990000", "Hello world!", delay = 120, link_preview = FALSE, verbose = TRUE)

Send Media

# URL
send_media(client, "+5581999990000", "image", "image/png",
            "https://www.r-project.org/logo/Rlogo.png", "Rlogo.png",
            caption = "R Logo", verbose = TRUE)

# Local File
send_media(client, "+5581999990000", "document", "application/pdf",
            media = "report.pdf", file_name = "report.pdf",
            caption = "Monthly Report", verbose = TRUE)

Send Contact

send_contact(client, "+5581999990000",
             contact = list(
               fullName = "Jane Doe",
               phoneNumber = "+5581999990000",
               organization = "Company Ltd.",
               email = "jane@example.com",
               url = "https://company.com"
             ),
             verbose = TRUE)

Send Location

send_location(
  client,
  number = "+5581999990000",
  latitude = -8.05,
  longitude = -34.88,
  name = "Recife Antigo",
  address = "Marco Zero - Recife/PE",
  verbose = TRUE
)

Configuration

• Timeout: controlled by options(evolution.timeout) (default 60 seconds)
• Verbose mode: verbose = TRUE enables detailed CLI + httr2 logs
• Error handling: HTTP status >= 400 triggers error message via req_error()

Advanced Tips

• Base64: remove data:*;base64, prefix and all line breaks before sending
• Contact wuid: automatically generated as <digits>@s.whatsapp.net
• Security: store your API key securely using .Renviron
• Debugging: compare verbose output with a working curl request

Contributing

Contributions are welcome! Open issues with reproducible examples and sanitized logs.

License

MIT © 2025 Andre Leite, Hugo Vasconcelos & Diogo Bezerra
See LICENSE for details.