Package 'evolution'

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., "[email protected]").

Examples

jid("+55 81 99999-0000")
#> "[email protected]"

jid("5581999990000")
#> "[email protected]"

---

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 = "[email protected]",
    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 = "[email protected]",
  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)

---