evolution

CRAN_Status_Badge CRAN Downloads

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.