Evolution API SDK for Javascript

Unofficial SDK for the Evolution Whatsapp API (v2).

This is a fork of @solufy/evolution-sdk with additional features.

Installation

``bash
npm install evolution-api-sdk
// or
yarn add evolution-api-sdk
// or
bun add evolution-api-sdk
`

Getting Started

`ts
import { EvolutionClient } from "evolution-api-sdk";

const client = new EvolutionClient({
serverUrl: "Your server url",
token: "Global api key or instance token",
instance: "Your instance", // optional
});
`

Usage Examples

$3

`ts
client.setInstance("my-instance-01");

await client.messages.sendText({
number: "5511999999999",
text: "Hello from the SDK!",
});
`

$3

You can override the default instance for any method call:

`ts
// Send message using a different instance
await client.messages.sendText(
{
number: "5511999999999",
text: "Hello from another instance!",
},
{ instance: "different-instance-name" }
);

// Check numbers on a specific instance
await client.chats.check(["5511999999999"], { instance: "my-instance" });

// Works with all methods across all modules
await client.groups.create(
{
subject: "My Group",
participants: ["5511999999999"],
},
{ instance: "work-instance" }
);

await client.profile.updateName(
{
name: "New Name",
},
{ instance: "personal-instance" }
);
`

$3

`ts
await client.messages.sendImage({
number: "5511999999999",
image: "https://i.imgur.com/REo1ODy.png",
caption: "A cute cat",
});
`

$3

`ts
await client.groups.create({
subject: "My Awesome Group",
participants: ["5511999999999", "5522988888888"],
});
`

$3

`ts
const result = await client.chats.check(["5511999999999"]);
console.log(result);
// [{ jid: '5511999999999@s.whatsapp.net', exists: true }]
`

API Reference

> 💡 Pro Tip: All methods support an optional { instance: "instance-name" } parameter to override the default instance.

$3

#### Create Instance

`ts
await client.instance.create({
instanceName: "my-bot",
token: "optional-token",
});
`

#### Setting the default Instance

`ts
await client.setInstance("InstanceName");
`

#### Connect to Instance

`ts
await client.instance.connect({ instanceName: "my-bot" });
`

#### Get Connection State

`ts
const state = await client.instance.connectionState({ instanceName: "my-bot" });
`

#### Manage Instance

`ts
// Logout
await client.instance.logout({ instanceName: "my-bot" });

// Restart
await client.instance.restart({ instanceName: "my-bot" });

// Delete
await client.instance.delete({ instanceName: "my-bot" });

// List all instances
const instances = await client.instance.fetchAll();

// Set presence
await client.instance.setPresence({
instanceName: "my-bot",
presence: "available",
});
`

---

$3

#### Check WhatsApp Numbers

`ts
const result = await client.chats.check(["5511999999999", "5522888888888"]);
// Override instance: client.chats.check(numbers, { instance: "my-instance" })
`

#### Get All Chats

`ts
const chats = await client.chats.findAll();
`

#### Chat Actions

`ts
client.setInstance("my-instance-01");
// Update presence
await client.chats.updatePresence({
number: "5511999999999",
presence: "composing",
delay: 1000,
});

// Mark as read
await client.chats.markAsRead({
remoteJid: "5511999999999@s.whatsapp.net",
fromMe: false,
id: "message-id",
});

// Archive chat
await client.chats.archive({
remoteJid: "5511999999999@s.whatsapp.net",
archive: true,
});
`

#### Message Management

`ts
// Delete message
await client.chats.deleteMessage({
remoteJid: "5511999999999@s.whatsapp.net",
fromMe: true,
id: "message-id",
});

// Find messages
const messages = await client.chats.findMessages({
where: {
key: {
remoteJid: "5511999999999@s.whatsapp.net",
},
},
offset: 10, // limit
page: 1,
});

// Update message
await client.chats.updateMessage({
remoteJid: "5511999999999@s.whatsapp.net",
fromMe: true,
id: "message-id",
text: "Updated message",
});

// Get base64 from media message
const mediaBase64 = await client.chats.getBase64FromMediaMessage({
message: {
key: {
id: "message-id",
},
},
convertToMp4: true, // Optional: Convert video to MP4
});

// Response format:
// {
// "mediaType": "audioMessage",
// "fileName": "3A3B333C3EC7505284A8.oga",
// "size": {"fileLength": "7905"},
// "mimetype": "audio/mp4",
// "base64": "AAAAIGZ0eXBpc2....=",
// "buffer": null
// }
`

#### Contact & Profile

`ts
// Fetch profile picture
const profilePic = await client.chats.fetchProfilePicture({
number: "5511999999999",
});

// Find contacts
const contacts = await client.chats.findContacts({
where: { name: "John" },
});
`

---

$3

#### Text Messages

`ts
await client.messages.sendText({
number: "5511999999999",
text: "Hello! 👋",
});
`

#### Media Messages

`ts
// Send image
await client.messages.sendImage({
number: "5511999999999",
image: "https://example.com/image.jpg",
caption: "Check this out!",
});

// Send video
await client.messages.sendVideo({
number: "5511999999999",
video: "https://example.com/video.mp4",
caption: "Amazing video!",
});

// Send document
await client.messages.sendDocument({
number: "5511999999999",
document: "https://example.com/document.pdf",
fileName: "report.pdf",
});

// Send audio
await client.messages.sendAudio({
number: "5511999999999",
audio: "https://example.com/audio.mp3",
});
`

#### Interactive Messages

`ts
// Send location
await client.messages.sendLocation({
number: "5511999999999",
latitude: -23.5505,
longitude: -46.6333,
name: "São Paulo",
});

// Send contact
await client.messages.sendContact({
number: "5511999999999",
contact: [
{
fullName: "John Doe",
phones: ["5511999999999"],
},
],
});

// Send reaction
await client.messages.sendReaction({
reactionMessage: {
key: { remoteJid: "5511999999999@s.whatsapp.net", id: "message-id" },
text: "👍",
},
});
`

#### Advanced Messages

`ts
// Send list
await client.messages.sendList({
number: "5511999999999",
title: "Choose an option",
description: "Select from the options below",
sections: [
{
title: "Options",
rows: [
{ title: "Option 1", description: "First option" },
{ title: "Option 2", description: "Second option" },
],
},
],
});

// Send template
await client.messages.sendTemplate({
number: "5511999999999",
template: {
name: "hello_world",
language: { code: "en_US" },
},
});
`

---

$3

#### Group Operations

`ts
// Create group
await client.groups.create({
subject: "My Awesome Group",
participants: ["5511999999999", "5522888888888"],
});

// Get all groups
const groups = await client.groups.findAll(false); // without participants
const groupsWithMembers = await client.groups.findAll(true); // with participants

// Find group by invite code
const group = await client.groups.findByInviteCode("invite-code-here");

// Find group by JID
const group = await client.groups.findByJid("group-id@g.us");
`

#### Group Settings

`ts
// Update group subject
await client.groups.updateSubject({
groupJid: "group-id@g.us",
subject: "New Group Name",
});

// Update group description
await client.groups.updateDescription({
groupJid: "group-id@g.us",
description: "New group description",
});

// Update group picture
await client.groups.updatePicture({
groupJid: "group-id@g.us",
image: "https://example.com/group-pic.jpg",
});
`

#### Group Members

`ts
// Add/remove members
await client.groups.updateMembers({
groupJid: "group-id@g.us",
action: "add",
participants: ["5511999999999"],
});

// Get group members
const members = await client.groups.findMembers({
groupJid: "group-id@g.us",
});

// Leave group
await client.groups.leave({
groupJid: "group-id@g.us",
});
`

#### Group Invites

`ts
// Get invite code
const inviteCode = await client.groups.fetchInviteCode({
groupJid: "group-id@g.us",
});

// Revoke invite code
await client.groups.revokeInviteCode({
groupJid: "group-id@g.us",
});

// Accept invite
await client.groups.acceptInviteCode({
inviteCode: "invite-code-here",
});
`

---

$3

#### Profile Information

`ts
// Get profile
const profile = await client.profile.fetchProfile({
number: "5511999999999",
});

// Get business profile
const businessProfile = await client.profile.fetchBusinessProfile({
number: "5511999999999",
});
`

#### Update Profile

`ts
// Update name
await client.profile.updateName({
name: "My New Name",
});

// Update status
await client.profile.updateStatus({
status: "Hey there! I'm using WhatsApp",
});

// Update picture
await client.profile.updatePicture({
picture: "https://example.com/my-photo.jpg",
});

// Remove picture
await client.profile.removePicture();
`

#### Privacy Settings

`ts
// Get privacy settings
const privacy = await client.profile.fetchPrivacySettings();

// Update privacy settings
await client.profile.updatePrivacySettings({
privacySettings: {
readReceipts: "all",
profile: "contacts",
status: "contacts",
online: "all",
last: "contacts",
groupAdd: "contacts",
},
});
`

---

$3

#### Instance Settings

`ts
// Get settings
const settings = await client.settings.find();

// Update settings
await client.settings.set({
reject_call: true,
msg_call: "Sorry, I can't take calls right now",
groups_ignore: false,
});
`

#### Webhook Configuration

`ts
// Get webhook settings
const webhook = await client.webhook.find();

// Set webhook
await client.webhook.set({
url: "https://your-webhook-url.com/webhook",
webhook_by_events: true,
events: ["MESSAGES_UPSERT", "CONNECTION_UPDATE"],
});
`

---

$3

You can override the default instance for any method:

`ts
// Send message with different instance
await client.messages.sendText(
{
number: "5511999999999",
text: "Hello from work bot!",
},
{ instance: "work-instance" }
);

// Check numbers on personal instance
await client.chats.check(["5511999999999"], { instance: "personal-bot" });

// Create group on specific instance
await client.groups.create(
{
subject: "Team Meeting",
participants: ["5511999999999"],
},
{ instance: "team-bot" }
);
`

---

$3

The SDK provides complete TypeScript support for handling webhooks from the Evolution API.

#### Basic Webhook Setup

`ts
import express from "express";
import {
WebhookData,
WebhookEvent,
WebhookEventSetup,
MessagePayload,
ContactPayload,
ConnectionUpdatePayload,
} from "evolution-api-sdk";

const app = express();
app.use(express.json());

// Webhook endpoint
app.post("/webhook", async (req, res) => {
try {
const webhookData: WebhookData = req.body;
await processWebhook(webhookData);
res.status(200).send("OK");
} catch (error) {
console.error("Webhook processing error:", error);
res.status(500).send("Error");
}
});

app.listen(3000, () => {
console.log("Webhook server running on port 3000");
});
`

#### Processing Webhook Events

`ts
async function processWebhook(webhookData: WebhookData): Promise {
const { event, instance, data } = webhookData;

console.log([WEBHOOK] Event: ${event} | Instance: ${instance});

switch (event) {
case WebhookEvent.MESSAGES_UPSERT:
await handleNewMessage(data as MessagePayload, instance);
break;

case WebhookEvent.MESSAGES_UPDATE:
await handleMessageUpdate(data as MessagePayload, instance);
break;

case WebhookEvent.CONNECTION_UPDATE:
await handleConnectionUpdate(data as ConnectionUpdatePayload);
break;

case WebhookEvent.CONTACTS_UPSERT:
case WebhookEvent.CONTACTS_UPDATE:
await handleContact(data as ContactPayload, instance);
break;

case WebhookEvent.QRCODE_UPDATED:
console.log([WEBHOOK] QR Code updated for instance: ${instance});
break;

default:
console.log([WEBHOOK] Unhandled event: ${event});
}
}
`

#### Message Handling Examples

`ts
async function handleNewMessage(
messageData: MessagePayload,
instance: string
): Promise {
const { key, message, pushName } = messageData;

// Skip messages from groups (optional)
if (key.remoteJid?.includes("@g.us")) {
console.log("Skipping group message");
return;
}

// Skip messages sent by bot itself
if (key.fromMe) {
console.log("Skipping outgoing message");
return;
}

const from = key.remoteJid;
const messageId = key.id;
const contactName = pushName || "Unknown";

console.log(Message from ${contactName} (${from}): ${messageId});

// Process different message types
if (message?.conversation) {
// Text message
const text = message.conversation;
console.log(Text: ${text});

// Auto-reply example
if (text.toLowerCase() === "hello") {
await client.messages.sendText(
{
number: from.replace("@s.whatsapp.net", ""),
text: "Hello! How can I help you?",
},
{ instance }
);
}
} else if (message?.imageMessage) {
// Image message
console.log(Received image from ${contactName});
const imageUrl = message.imageMessage.url;
// Process image...
} else if (message?.audioMessage) {
// Audio message
console.log(Received audio from ${contactName});
// Process audio...
}
}

async function handleMessageUpdate(
messageData: MessagePayload,
instance: string
): Promise {
const { key, status } = messageData;
console.log(Message ${key.id} status updated to: ${status});

// Handle read receipts, delivery confirmations, etc.
switch (status) {
case MessageUpdateStatus.DELIVERY_ACK:
console.log("Message delivered");
break;
case MessageUpdateStatus.READ:
console.log("Message read by recipient");
break;
case MessageUpdateStatus.SERVER_ACK:
console.log("Message sent to server");
break;
}
}

async function handleConnectionUpdate(
connectionData: ConnectionUpdatePayload
): Promise {
const { instance, state, statusReason } = connectionData;

console.log(Instance ${instance} connection state: ${state});

switch (state) {
case "open":
console.log(✅ Instance ${instance} connected successfully);
break;
case "close":
console.log(❌ Instance ${instance} disconnected (${statusReason}));
break;
case "connecting":
console.log(🔄 Instance ${instance} connecting...);
break;
}
}

async function handleContact(
contactData: ContactPayload,
instance: string
): Promise {
const { remoteJid, pushName, profilePicUrl } = contactData;

console.log(Contact update: ${pushName} (${remoteJid}));

// Store or update contact information
// You might want to save this to your database
}
`

#### Advanced Webhook Processing

`ts
class WebhookProcessor {
private messageQueue: MessagePayload[] = [];
private processing = false;

async processWebhook(webhookData: WebhookData): Promise {
const { event, data, instance } = webhookData;

// Add message to queue for batch processing
if (event === WebhookEvent.MESSAGES_UPSERT) {
this.messageQueue.push(data as MessagePayload);
this.processQueue();
}
}

private async processQueue(): Promise {
if (this.processing || this.messageQueue.length === 0) return;

this.processing = true;

try {
// Process messages in batches
const batch = this.messageQueue.splice(0, 10);

for (const message of batch) {
await this.processMessage(message);
// Add delay to avoid rate limiting
await new Promise((resolve) => setTimeout(resolve, 100));
}
} finally {
this.processing = false;

// Continue processing if more messages arrived
if (this.messageQueue.length > 0) {
setTimeout(() => this.processQueue(), 1000);
}
}
}

private async processMessage(message: MessagePayload): Promise {
// Your message processing logic here
console.log(Processing message: ${message.key.id});
}
}
`

#### Available Webhook Events

The SDK supports all Evolution API webhook events:

- WebhookEvent.APPLICATION_STARTUP - API startup
- WebhookEvent.QRCODE_UPDATED - QR code updates
- WebhookEvent.CONNECTION_UPDATE - Connection status changes
- WebhookEvent.MESSAGES_SET - Initial message load
- WebhookEvent.MESSAGES_UPSERT - New messages
- WebhookEvent.MESSAGES_UPDATE - Message status updates
- WebhookEvent.MESSAGES_DELETE - Message deletions
- WebhookEvent.SEND_MESSAGE - Message sending events
- WebhookEvent.CONTACTS_SET - Initial contacts load
- WebhookEvent.CONTACTS_UPSERT - New contacts
- WebhookEvent.CONTACTS_UPDATE - Contact updates
- WebhookEvent.PRESENCE_UPDATE - User presence changes
- WebhookEvent.CHATS_SET - Initial chats load
- WebhookEvent.CHATS_UPDATE - Chat updates
- WebhookEvent.CHATS_UPSERT - New chats
- WebhookEvent.CHATS_DELETE - Chat deletions
- WebhookEvent.GROUPS_UPSERT - New groups
- WebhookEvent.GROUPS_UPDATE - Group updates
- WebhookEvent.GROUP_PARTICIPANTS_UPDATE - Group member changes
- WebhookEvent.NEW_TOKEN - JWT token updates

#### Available Webhook Events to Setup

To setup the WebHook, the constants are these ones:

- WebhookEventSetup.APPLICATION_STARTUP - API startup
- WebhookEventSetup.QRCODE_UPDATED - QR code updates
- WebhookEventSetup.CONNECTION_UPDATE - Connection status changes
- WebhookEventSetup.MESSAGES_SET - Initial message load
- WebhookEventSetup.MESSAGES_UPSERT - New messages
- WebhookEventSetup.MESSAGES_UPDATE - Message status updates
- WebhookEventSetup.MESSAGES_DELETE - Message deletions
- WebhookEventSetup.SEND_MESSAGE - Message sending events
- WebhookEventSetup.CONTACTS_SET - Initial contacts load
- WebhookEventSetup.CONTACTS_UPSERT - New contacts
- WebhookEventSetup.CONTACTS_UPDATE - Contact updates
- WebhookEventSetup.PRESENCE_UPDATE - User presence changes
- WebhookEventSetup.CHATS_SET - Initial chats load
- WebhookEventSetup.CHATS_UPDATE - Chat updates
- WebhookEventSetup.CHATS_UPSERT - New chats
- WebhookEventSetup.CHATS_DELETE - Chat deletions
- WebhookEventSetup.GROUPS_UPSERT - New groups
- WebhookEventSetup.GROUPS_UPDATE - Group updates
- WebhookEventSetup.GROUP_PARTICIPANTS_UPDATE - Group member changes
- WebhookEventSetup.NEW_TOKEN - JWT token updates

#### Configure Webhook URL

Don't forget to configure your webhook URL in the Evolution API:

`ts
// Set your webhook endpoint
await client.webhook.set({
url: "https://your-domain.com/webhook",
webhook_by_events: true,
events: [
WebhookEventSetup.MESSAGES_UPSERT,
WebhookEventSetup.MESSAGES_UPDATE,
WebhookEventSetup.CONNECTION_UPDATE,
WebhookEventSetup.CONTACTS_UPSERT,
],
});
``

API Documentation

Check the official API documentation for more information about their service.

Contributing

Feel free to contribute with suggestions or bug reports at our GitHub repository.

Authors

- @joaotonaco (Original author)
- @gusnips