Type: Package
Title: A Client for 'Evolution Cloud API'
Date: 2026-02-27
Version: 0.1.0
Description: Provides an 'R' interface to the 'Evolution API' https://evoapicloud.com, enabling sending and receiving 'WhatsApp' messages directly from 'R'. Functions include sending text, media (image/video/document), audio, stickers, geographic locations, contacts, polls, interactive lists and button messages. Also includes number verification and structured CLI logging for debugging.
License: MIT + file LICENSE
URL: https://github.com/StrategicProjects/evolution/
BugReports: https://github.com/StrategicProjects/evolution/issues/
Depends: R (≥ 4.2.0)
Imports: httr2 (≥ 1.0.0), cli (≥ 3.6.0), jsonlite, base64enc
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown, pkgdown
Config/testthat/edition: 3
Encoding: UTF-8
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2026-02-27 14:43:30 UTC; leite
Author: Andre Leite [aut, cre], Hugo Vasconcelos [aut], Diogo Bezerra [aut]
Maintainer: Andre Leite <leite@castlab.org>
Repository: CRAN
Date/Publication: 2026-02-27 15:40:02 UTC

Assert that a value is a single non-empty string

Description

Assert that a value is a single non-empty string

Usage

.assert_scalar_string(x, name)

Arguments

x

Value to check.

name

Argument name for the error message.

Compact a list removing NULL elements

Description

Compact a list removing NULL elements

Usage

.compact(x)

Arguments

x

A list possibly containing NULL elements.

Value

The same list with all NULL elements removed.

Build internal API path

Description

Build internal API path

Usage

.evo_path(...)

Arguments

...

Character path segments.

Value

A single character scalar with segments concatenated by "/".

Perform a JSON POST request (internal)

Description

Sends a JSON POST to the Evolution API and returns the parsed response. Includes structured CLI logging when verbose = TRUE and robust error handling that surfaces the actual API error message.

Usage

.evo_post(client, path, body, verbose = FALSE)

Arguments

client

An evo_client object.

path

Character. Path to append to the base URL.

body

List to be JSON-encoded as the request body.

verbose

Logical. If TRUE, prints request/response diagnostics via cli.

Value

Parsed JSON as list (with raw HTTP status stored in attribute http_status).

Normalise media input (URL, file path, base64, data-URI)

Description

Normalise media input (URL, file path, base64, data-URI)

Usage

.normalize_media(x)

Arguments

x

The media input to normalise.

Value

Character string suitable for the API body (URL or base64).

Check if numbers are on WhatsApp

Description

Verifies whether one or more phone numbers are registered on WhatsApp using the Evolution API v2 chat controller endpoint.

Usage

check_is_whatsapp(client, numbers, verbose = FALSE)

Arguments

client

An evo_client() object.

numbers

Character vector of phone numbers to check (with country code, e.g., "5581999990000").

verbose

Logical. If TRUE, logs request/response details.

Value

A named list (or data frame) from the API indicating which numbers are registered. The HTTP status code is stored in attr(result, "http_status").

Examples

## Not run: 
check_is_whatsapp(client, c("5581999990000", "5511988887777"))

## End(Not run)

Create an Evolution API client

Description

Creates a preconfigured httr2 client to call Evolution API v2. It sets the apikey header, a custom User-Agent and basic automatic retries.

The returned object is used by every ⁠send_*()⁠ function and stores the base request (req) and the instance name so you don't have to repeat them.

Usage

evo_client(base_url, api_key, instance)

Arguments

base_url

Character. Server base URL (no trailing slash), e.g. "https://your-host".

api_key

Character. API key (sent as apikey header). Prefer Sys.getenv("EVO_APIKEY") to avoid hardcoding secrets.

instance

Character. Instance name/ID used in endpoint paths.

Value

An object of class evo_client with fields req (httr2 request) and instance.

See Also

send_text(), send_media(), send_location()

Examples

## Not run: 
client <- evo_client(
  base_url = "https://your-evolution-host.com",
  api_key  = Sys.getenv("EVO_APIKEY"),
  instance = "myInstance"
)

## End(Not run)

Build a WhatsApp JID from a raw phone number

Description

Normalises a raw phone number by removing spaces, dashes, parentheses, and the leading + sign, then appends ⁠@s.whatsapp.net⁠.

Usage

jid(number)

Arguments

number

Character scalar or vector. Raw phone number(s) (e.g., "+5581999990000").

Value

Character JID(s) (e.g., "5581999990000@s.whatsapp.net").

Examples

jid("+55 81 99999-0000")
#> "5581999990000@s.whatsapp.net"

jid("5581999990000")
#> "5581999990000@s.whatsapp.net"

Send interactive buttons

Description

Sends a message with interactive buttons via Evolution API v2.

Usage

send_buttons(
  client,
  number,
  title,
  description,
  footer,
  buttons,
  delay = NULL,
  link_preview = NULL,
  mentions_everyone = NULL,
  verbose = FALSE
)

Arguments

client

An evo_client() object.

number

Character. Recipient number with country code (e.g., "5581999990000" or "+5581999990000").

title

Character. Button message title.

description

Character. Button message description/body.

footer

Character. Footer text.

buttons

List of buttons. Each button should be a named list following the API specification (see Evolution API docs).

delay

Integer (ms). Optional presence delay before sending. Simulates typing before the message is sent.

link_preview

Logical. Enable URL link preview in the message.

mentions_everyone

Logical. Mention everyone in a group.

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list with the API response. The HTTP status code is stored in attr(result, "http_status").

Note

Baileys connector: Interactive buttons are not supported on the Baileys (WhatsApp Web) connector and are likely to be discontinued. This endpoint is fully supported only on the Cloud API connector. If you are on Baileys, consider using send_poll() as an alternative.

See Also

send_poll()

Examples

## Not run: 
send_buttons(client, "5581999990000",
  title = "Choose",
  description = "Pick an option:",
  footer = "Powered by R",
  buttons = list(
    list(type = "reply", title = "Option A"),
    list(type = "reply", title = "Option B")
  ))

## End(Not run)

Send a WhatsApp contact (auto-generate wuid)

Description

Sends one or more contacts following the Evolution API v2 format. Automatically generates the wuid field as ⁠<digits>@s.whatsapp.net⁠ from each contact's phone number (or from number if not provided).

Usage

send_contact(client, number, contact, verbose = FALSE)

Arguments

client

An evo_client() object.

number

Recipient number (e.g., "5581999990000").

contact

Either:

  • a named list with fields fullName, phoneNumber, organization, email, url; or

  • a list of such lists (to send multiple contacts). The wuid field will be auto-generated if missing.

verbose

Logical; if TRUE, shows detailed logs.

Value

Parsed JSON response as list (see .evo_post() for details).

Examples

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

## End(Not run)

Send a list message

Description

Sends an interactive list message via Evolution API v2. List messages display a menu of selectable options organised into sections.

Usage

send_list(
  client,
  number,
  title,
  description,
  button_text,
  sections,
  footer = "",
  delay = NULL,
  verbose = FALSE
)

Arguments

client

An evo_client() object.

number

Character. Recipient number with country code (e.g., "5581999990000" or "+5581999990000").

title

Character. List message title.

description

Character. List message body text.

button_text

Character. Text displayed on the list button (e.g., "View options").

sections

A list of section objects. Each section is a named list with title and rows, where rows is a list of named lists each containing title, optional description, and optional rowId.

footer

Character. Footer text (required by the API, defaults to "").

delay

Integer (ms). Optional presence delay before sending. Simulates typing before the message is sent.

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list with the API response. The HTTP status code is stored in attr(result, "http_status").

Note

Baileys connector: Interactive list messages are not supported on the Baileys (WhatsApp Web) connector and are likely to be discontinued. This endpoint is fully supported only on the Cloud API connector. If you are on Baileys, consider using send_poll() as an alternative.

See Also

send_poll()

Examples

## Not run: 
send_list(client, "5581999990000",
  title = "Our Menu",
  description = "Select from the options below:",
  button_text = "View options",
  footer = "Powered by R",
  sections = list(
    list(title = "Drinks", rows = list(
      list(title = "Coffee", description = "Hot coffee", rowId = "1"),
      list(title = "Tea",    description = "Green tea",  rowId = "2")
    )),
    list(title = "Food", rows = list(
      list(title = "Cake", description = "Chocolate cake", rowId = "3")
    ))
  ))

## End(Not run)

Send a location

Description

Sends a geographic location pin via Evolution API v2.

Usage

send_location(
  client,
  number,
  latitude,
  longitude,
  name = NULL,
  address = NULL,
  verbose = FALSE
)

Arguments

client

An evo_client() object.

number

Character. Recipient number with country code (e.g., "5581999990000" or "+5581999990000").

latitude

Numeric. Latitude coordinate.

longitude

Numeric. Longitude coordinate.

name

Optional character. Location label name.

address

Optional character. Address description.

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list with the API response. The HTTP status code is stored in attr(result, "http_status").

Examples

## Not run: 
send_location(client, "5581999990000",
              latitude = -8.05, longitude = -34.88,
              name = "Recife Antigo", address = "Marco Zero")

## End(Not run)

Send media (image, video, document)

Description

Sends an image, video, or document via Evolution API v2. The media argument is flexible: it accepts an HTTP(S) URL, a local file path (auto-encoded to base64), raw base64, or a data-URI.

Usage

send_media(
  client,
  number,
  mediatype,
  mimetype,
  media,
  file_name,
  caption = NULL,
  delay = NULL,
  link_preview = NULL,
  verbose = FALSE
)

Arguments

client

An evo_client() object.

number

Character. Recipient number with country code (e.g., "5581999990000" or "+5581999990000").

mediatype

One of "image", "video", "document".

mimetype

MIME type string, e.g., "image/png", "video/mp4", "application/pdf".

media

The media content. Can be: (a) an HTTP/HTTPS URL; (b) a local file path; (c) raw base64; or (d) a data-URI (⁠data:*;base64,...⁠).

file_name

Suggested filename for the recipient (should match the MIME type, e.g., "report.pdf").

caption

Optional caption text displayed with the media.

delay

Integer (ms). Optional presence delay before sending. Simulates typing before the message is sent.

link_preview

Logical. Enable URL link preview in the message.

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list with the API response. The HTTP status code is stored in attr(result, "http_status").

Examples

## Not run: 
# From URL
send_media(client, "5581999990000", "image", "image/png",
           media = "https://www.r-project.org/logo/Rlogo.png",
           file_name = "Rlogo.png", caption = "R Logo")

# From local file
send_media(client, "5581999990000", "document", "application/pdf",
           media = "report.pdf", file_name = "report.pdf")

## End(Not run)

Send a poll

Description

Sends a poll (question with selectable options) via Evolution API v2.

Usage

send_poll(client, number, name, values, selectable_count = 1L, verbose = FALSE)

Arguments

client

An evo_client() object.

number

Character. Recipient number with country code (e.g., "5581999990000" or "+5581999990000").

name

Question text displayed in the poll.

values

Character vector of poll options (minimum 2).

selectable_count

Integer. Number of options a user can select (default 1L for single-choice).

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list with the API response. The HTTP status code is stored in attr(result, "http_status").

Examples

## Not run: 
send_poll(client, "5581999990000",
  name = "Favourite language?",
  values = c("R", "Python", "Julia"),
  selectable_count = 1)

## End(Not run)

React to a message

Description

Sends an emoji reaction to an existing message.

Usage

send_reaction(client, key, reaction, verbose = FALSE)

Arguments

client

An evo_client() object.

key

List with remoteJid, fromMe, and id identifying the target message.

reaction

Emoji string (e.g., "\U0001f44d" for thumbs up). Use an empty string "" to remove a reaction.

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list with the API response. The HTTP status code is stored in attr(result, "http_status").

Examples

## Not run: 
send_reaction(client, key = list(
  remoteJid = "5581999990000@s.whatsapp.net",
  fromMe = TRUE,
  id = "BAE594145F4C59B4"
), reaction = "\U0001f44d")

## End(Not run)

Send a WhatsApp Status (story)

Description

Posts a status (story) message visible to your contacts. Supports text or media (image, video, document, audio) types.

Usage

send_status(
  client,
  type = c("text", "image", "video", "document", "audio"),
  content,
  caption = NULL,
  background_color = NULL,
  font = NULL,
  all_contacts = FALSE,
  status_jid_list = NULL,
  verbose = FALSE
)

Arguments

client

An evo_client() object.

type

One of "text", "image", "video", "document", "audio".

content

Text (for type = "text") or URL/base64 for media.

caption

Optional caption for media types.

background_color

Hex colour for text status background (e.g., "#FF5733").

font

Integer font id (0–14).

all_contacts

Logical. If TRUE, sends to all contacts.

status_jid_list

Optional character vector of specific JIDs to receive the status.

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list with the API response. The HTTP status code is stored in attr(result, "http_status").

Examples

## Not run: 
send_status(client, type = "text", content = "Hello from R!",
            background_color = "#317873", font = 2, all_contacts = TRUE)

## End(Not run)

Send a sticker

Description

Sends a sticker image via Evolution API v2.

Usage

send_sticker(client, number, sticker, delay = NULL, verbose = FALSE)

Arguments

client

An evo_client() object.

number

Character. Recipient number with country code (e.g., "5581999990000" or "+5581999990000").

sticker

URL, base64-encoded sticker image, or local file path (auto-encoded to base64). Supports ~ expansion.

delay

Integer (ms). Optional presence delay before sending. Simulates typing before the message is sent.

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list with the API response. The HTTP status code is stored in attr(result, "http_status").

Examples

## Not run: 
send_sticker(client, "5581999990000",
             sticker = "https://example.com/sticker.webp")

## End(Not run)

Send a plain text message

Description

Sends a plain text WhatsApp message using Evolution API v2.

Usage

send_text(
  client,
  number,
  text,
  delay = NULL,
  link_preview = NULL,
  mentions_everyone = NULL,
  mentioned = NULL,
  quoted = NULL,
  verbose = FALSE
)

Arguments

client

An evo_client() object.

number

Character. Recipient number with country code (e.g., "5581999990000" or "+5581999990000").

text

Character. Message body.

delay

Integer (ms). Optional presence delay before sending. Simulates typing before the message is sent.

link_preview

Logical. Enable URL link preview in the message.

mentions_everyone

Logical. Mention everyone in a group.

mentioned

Character vector of JIDs to mention (e.g., jid("+5581999990000")).

quoted

Optional list with Baileys message key and message to reply to a specific message.

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list parsed from the JSON response returned by Evolution API, containing the message key (with remoteJid, fromMe, id), message, messageTimestamp, and status. The HTTP status code is stored in attr(result, "http_status").

See Also

send_media(), send_location(), jid()

Examples

## Not run: 
client <- evo_client("https://my-host", Sys.getenv("EVO_APIKEY"), "myInst")
send_text(client, "5581999990000", "Hello from R!", verbose = TRUE)

## End(Not run)

Send WhatsApp audio (voice note)

Description

Sends an audio message (push-to-talk / voice note) via Evolution API v2.

Usage

send_whatsapp_audio(
  client,
  number,
  audio,
  delay = NULL,
  quoted = NULL,
  verbose = FALSE
)

Arguments

client

An evo_client() object.

number

Character. Recipient number with country code (e.g., "5581999990000" or "+5581999990000").

audio

URL, base64-encoded audio, or local file path (auto-encoded to base64). Supports ~ expansion.

delay

Integer (ms). Optional presence delay before sending. Simulates typing before the message is sent.

quoted

Optional list with Baileys message key and message to reply to a specific message.

verbose

Logical. If TRUE, logs request/response details with cli.

Value

A named list with the API response. The HTTP status code is stored in attr(result, "http_status").

Examples

## Not run: 
send_whatsapp_audio(client, "5581999990000",
                    audio = "https://example.com/note.ogg")

## End(Not run)