Evolution V2 Compatibility Layer — API Reference

The Pilot Status Evolution V2 API Layer is a transparent compatibility bridge for applications built on Evolution API V2. Changing your base URL to the Pilot Status layer endpoint is all it takes to move your infrastructure — your request bodies, response parsing, webhook handlers, and authentication headers all stay exactly as they are.

Base URL

Update your base URL environment variable or HTTP client configuration to the following:

https://pilotstatus.com.br/api/layer/evolution-v2/

Every path you currently call on your Evolution V2 server appends to this base URL without any modification.

Authentication

Pass your Pilot Status API key in the apikey header, exactly as Evolution V2 expects:

apikey: YOUR_API_KEY

You do not need to change any authentication logic in your application — only the API key value itself needs to be replaced with your Pilot Status key.

Supported operations

Every operation below is accepted in Evolution V2 format and executed against your Pilot Status number. In each path, {instance} is the last path segment and resolves to the display name you gave the number in the Pilot Status dashboard. Send and message operations are load-balanced across the number’s connected instances (sendReaction is the exception — it is not balanced). Any path that is not in this catalog returns 404; global (server-wide) paths return 403 — see Blocked (global) below.

Instance

Method	Path
`POST`	`/instance/restart/{instance}`
`GET`	`/instance/connect/{instance}`
`GET`	`/instance/connectionState/{instance}`
`POST`	`/instance/setPresence/{instance}`
`DELETE`	`/instance/logout/{instance}`
`DELETE`	`/instance/delete/{instance}`

Message

Send messages of every type through a connected number. Every path ends with /{instance}, the number’s display name (a path param — never put it in the body).

POST /message/sendTemplate/{instance} — Send template

Sends an approved WhatsApp template message to a recipient.

Field	Type	Required	Description
`number`	string	No	Recipient phone in E.164 without `+`, or a JID.
`name`	string	Yes	Approved template name.
`language`	string	Yes	Template language/locale code (e.g. `pt_BR`).
`components`	array	No	Template components (header/body/button parameters).
`webhookUrl`	string	No	Optional per-message webhook URL for status callbacks.

{
  "number": "5511999999999",
  "name": "order_confirmation",
  "language": "pt_BR",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Ismael" }
      ]
    }
  ],
  "webhookUrl": "https://example.com/webhooks/template"
}

POST /message/sendText/{instance} — Send text

Sends a plain text message, optionally with a link preview and mentions.

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`text`	string	Yes	Message body text.
`linkPreview`	boolean	No	Whether to render a preview for URLs in the text.
`delay`	integer	No	Delay before sending, in milliseconds.
`quoted`	object	No	Message to quote/reply to (`key`, `message`).
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "text": "Hello from Pilot Status!",
  "linkPreview": true,
  "delay": 1200,
  "mentioned": ["5511988888888"]
}

POST /message/sendMedia/{instance} — Send media

Sends an image, video, document, or audio file by public URL (base64 and multipart file upload are also supported).

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`mediatype`	string	Yes	One of `image`, `document`, `video`, `audio`.
`media`	string	Yes	Public URL (or base64) of the media file.
`mimetype`	string	No	MIME type of the media (e.g. `image/png`).
`fileName`	string	No	File name, used for documents.
`caption`	string	No	Caption text shown with the media.
`delay`	integer	No	Delay before sending, in milliseconds.
`quoted`	object	No	Message to quote/reply to (`key`, `message`).
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "mediatype": "image",
  "media": "https://media.pilotstatus.com.br/example.png",
  "mimetype": "image/png",
  "fileName": "example.png",
  "caption": "Check this out"
}

POST /message/sendPtv/{instance} — Send video note

Sends a PTV (round video note) by public URL (base64 and multipart file upload are also supported).

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`video`	string	Yes	Public URL (or base64) of the video file.
`delay`	integer	No	Delay before sending, in milliseconds.
`quoted`	object	No	Message to quote/reply to (`key`, `message`).
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "video": "https://media.pilotstatus.com.br/note.mp4",
  "delay": 800
}

POST /message/sendWhatsAppAudio/{instance} — Send voice audio

Sends a WhatsApp voice/PTT audio by public URL (base64 and multipart file upload are also supported).

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`audio`	string	Yes	Public URL (or base64) of the audio file.
`delay`	integer	No	Delay before sending, in milliseconds.
`quoted`	object	No	Message to quote/reply to (`key`, `message`).
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "audio": "https://media.pilotstatus.com.br/voice.ogg"
}

POST /message/sendStatus/{instance} — Send status

Publishes a status (story) as text or media by public URL (media file upload is also supported).

Field	Type	Required	Description
`type`	string	Yes	One of `text`, `image`, `audio`, `video`.
`content`	string	Yes	Status text, or the public URL of the media.
`caption`	string	No	Caption for media statuses.
`backgroundColor`	string	No	Background color for text statuses (e.g. `#25D366`).
`font`	integer	No	Font index for text statuses (0–5).
`statusJidList`	string[]	No	Recipient JIDs (numeric strings) allowed to see the status.
`allContacts`	boolean	No	Publish to all contacts instead of a JID list.

{
  "type": "text",
  "content": "We are online!",
  "backgroundColor": "#25D366",
  "font": 2,
  "allContacts": true
}

POST /message/sendSticker/{instance} — Send sticker

Sends a sticker by public URL (base64 and multipart file upload are also supported).

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`sticker`	string	Yes	Public URL (or base64) of the sticker image.
`delay`	integer	No	Delay before sending, in milliseconds.
`quoted`	object	No	Message to quote/reply to (`key`, `message`).
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "sticker": "https://media.pilotstatus.com.br/sticker.webp"
}

POST /message/sendLocation/{instance} — Send location

Sends a geographic location pin with a name and address.

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`latitude`	number	Yes	Latitude of the location.
`longitude`	number	Yes	Longitude of the location.
`name`	string	Yes	Display name of the place.
`address`	string	Yes	Address of the place.
`delay`	integer	No	Delay before sending, in milliseconds.
`quoted`	object	No	Message to quote/reply to (`key`, `message`).
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "latitude": -23.55052,
  "longitude": -46.633308,
  "name": "Pilot Status HQ",
  "address": "Av. Paulista, 1000, São Paulo"
}

POST /message/sendContact/{instance} — Send contact

Sends one or more contact cards (vCards).

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`contact`	array	Yes	Array of contact objects (see fields below).
`contact[].fullName`	string	Yes	Contact’s full name.
`contact[].phoneNumber`	string	Yes	Contact’s phone number.
`contact[].wuid`	string	No	WhatsApp user id (numeric string).
`contact[].organization`	string	No	Contact’s organization.
`contact[].email`	string	No	Contact’s email address.
`contact[].url`	string	No	Contact’s website URL.

{
  "number": "5511999999999",
  "contact": [
    {
      "fullName": "Ismael Nascimento",
      "wuid": "5511988888888",
      "phoneNumber": "5511988888888",
      "organization": "Pilot Status",
      "email": "contato@pilotstatus.com.br",
      "url": "https://pilotstatus.com.br"
    }
  ]
}

POST /message/sendReaction/{instance} — Send reaction

Reacts to an existing message with an emoji.

Field	Type	Required	Description
`key`	object	Yes	Target message key (`id`, `remoteJid`, `fromMe` — all required).
`reaction`	string	Yes	Emoji to react with.

{
  "key": {
    "id": "BAE5F6A1B2C3D4E5",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false
  },
  "reaction": "👍"
}

POST /message/sendPoll/{instance} — Send poll

Sends a poll with selectable options.

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`name`	string	Yes	Poll question/title.
`selectableCount`	integer	Yes	How many options can be selected (0–10).
`values`	string[]	Yes	Poll options (2–10 unique strings).
`delay`	integer	No	Delay before sending, in milliseconds.
`quoted`	object	No	Message to quote/reply to (`key`, `message`).
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "name": "Which plan do you prefer?",
  "selectableCount": 1,
  "values": ["Starter", "Pro", "Enterprise"]
}

POST /message/sendList/{instance} — Send list

Sends an interactive list message with sections and selectable rows.

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`title`	string	Yes	List title.
`footerText`	string	Yes	Footer text shown below the list.
`buttonText`	string	Yes	Label of the button that opens the list.
`sections`	array	Yes	Array of section objects (see fields below).
`sections[].title`	string	Yes	Section title.
`sections[].rows`	array	Yes	Rows, each with `title`, `rowId` (required) and optional `description`.
`description`	string	No	List description/body text.
`delay`	integer	No	Delay before sending, in milliseconds.
`quoted`	object	No	Message to quote/reply to (`key`, `message`).
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "title": "Our menu",
  "description": "Pick an item",
  "footerText": "Pilot Status",
  "buttonText": "View options",
  "sections": [
    {
      "title": "Drinks",
      "rows": [
        { "title": "Coffee", "description": "Fresh brewed", "rowId": "drink_coffee" },
        { "title": "Tea", "description": "Green tea", "rowId": "drink_tea" }
      ]
    }
  ]
}

POST /message/sendButtons/{instance} — Send buttons

Sends an interactive buttons message. Each button type is one of reply, copy, url, call, pix.

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`buttons`	array	No	Array of button objects (see fields below).
`buttons[].type`	string	Yes	Button type: `reply`, `copy`, `url`, `call`, or `pix`.
`buttons[].displayText`	string	No	Text shown on the button.
`buttons[].id`	string	No	Button id (for `reply`).
`buttons[].url`	string	No	URL to open (for `url`).
`buttons[].phoneNumber`	string	No	Phone number to call (for `call`).
`buttons[].currency`	string	No	Currency (for `pix`).
`buttons[].name`	string	No	Merchant/key name (for `pix`).
`buttons[].keyType`	string	No	Pix key type: `phone`, `email`, `cpf`, `cnpj`, `random`.
`buttons[].key`	string	No	Pix key value (for `pix`).
`title`	string	No	Message title.
`description`	string	No	Message body text.
`footer`	string	No	Footer text.
`thumbnailUrl`	string	No	URL of a thumbnail image.
`delay`	integer	No	Delay before sending, in milliseconds.
`quoted`	object	No	Message to quote/reply to (`key`, `message`).
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "title": "How can we help?",
  "description": "Choose an option below",
  "footer": "Pilot Status",
  "buttons": [
    { "type": "reply", "displayText": "Talk to sales", "id": "sales" },
    { "type": "url", "displayText": "Visit site", "url": "https://pilotstatus.com.br" },
    { "type": "call", "displayText": "Call us", "phoneNumber": "5511967435133" }
  ]
}

POST /message/sendCarousel/{instance} — Send carousel

Sends a carousel of cards, each with text, an optional thumbnail, and its own buttons.

Field	Type	Required	Description
`number`	string	Yes	Recipient phone in E.164 without `+`, or a JID.
`cards`	array	No	Array of card objects (see fields below).
`cards[].text`	string	No	Card body text.
`cards[].thumbnailUrl`	string	No	URL of the card thumbnail image.
`cards[].footerText`	string	No	Card footer text.
`cards[].buttons`	array	No	Buttons for the card (same shape as sendButtons).
`title`	string	No	Carousel title.
`description`	string	No	Carousel body text.
`footer`	string	No	Carousel footer text.
`delay`	integer	No	Delay before sending, in milliseconds.
`everyOne`	boolean	No	Mention everyone in the group.
`mentioned`	string[]	No	Array of numeric strings to mention.

{
  "number": "5511999999999",
  "title": "Featured products",
  "description": "Swipe to browse",
  "footer": "Pilot Status",
  "cards": [
    {
      "text": "Starter plan",
      "thumbnailUrl": "https://media.pilotstatus.com.br/starter.png",
      "footerText": "Best for small teams",
      "buttons": [
        { "type": "url", "displayText": "Learn more", "url": "https://pilotstatus.com.br/starter" }
      ]
    }
  ]
}

Chat

Manage chats, messages, contacts, presence and block status for a connected number. In every path, {instance} is the number’s display name (a path parameter), never a body field.

POST /chat/whatsappNumbers/{instance} — Check WhatsApp numbers

Checks whether one or more numbers are registered on WhatsApp.

Field	Type	Required	Description
`numbers`	string[]	Yes	Array of numeric phone strings (E.164 without symbols) to verify.

{
  "numbers": ["5511999999999", "5521988888888"]
}

POST /chat/markMessageAsRead/{instance} — Mark messages as read

Marks one or more messages as read (sends read receipts).

Field	Type	Required	Description
`readMessages`	array	Yes	Array of message key objects to mark as read.
`readMessages[].id`	string	Yes	Message id.
`readMessages[].fromMe`	boolean	Yes	Whether the message was sent by this number.
`readMessages[].remoteJid`	string	Yes	Chat JID the message belongs to.

{
  "readMessages": [
    {
      "id": "BAE5F5A632EAE722",
      "fromMe": false,
      "remoteJid": "5511999999999@s.whatsapp.net"
    }
  ]
}

POST /chat/archiveChat/{instance} — Archive or unarchive chat

Archives or unarchives a chat.

Field	Type	Required	Description
`archive`	boolean	Yes	`true` to archive, `false` to unarchive.
`chat`	string	No	Chat JID to archive.
`lastMessage`	object	No	Reference to the chat’s last message.
`lastMessage.key`	object	No	Message key with `id`, `remoteJid`, `fromMe`.
`lastMessage.messageTimestamp`	integer	No	Unix timestamp of the last message.

{
  "archive": true,
  "chat": "5511999999999@s.whatsapp.net",
  "lastMessage": {
    "key": {
      "id": "BAE5F5A632EAE722",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    },
    "messageTimestamp": 1720540800
  }
}

POST /chat/markChatUnread/{instance} — Mark chat as unread

Marks a chat as unread.

Field	Type	Required	Description
`lastMessage`	object	Yes	Reference to the chat’s last message.
`lastMessage.key`	object	Yes	Message key with `id`, `remoteJid`, `fromMe`.
`lastMessage.messageTimestamp`	integer	No	Unix timestamp of the last message.
`chat`	string	No	Chat JID to mark unread.

{
  "lastMessage": {
    "key": {
      "id": "BAE5F5A632EAE722",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    },
    "messageTimestamp": 1720540800
  },
  "chat": "5511999999999@s.whatsapp.net"
}

DELETE /chat/deleteMessageForEveryone/{instance} — Delete message for everyone

Deletes a message for all participants in the chat.

Field	Type	Required	Description
`id`	string	Yes	Message id to delete.
`fromMe`	boolean	Yes	Whether the message was sent by this number.
`remoteJid`	string	Yes	Chat JID the message belongs to.
`participant`	string	No	Participant JID (for group messages).

{
  "id": "BAE5F5A632EAE722",
  "fromMe": true,
  "remoteJid": "1203630000000000000@g.us",
  "participant": "5511999999999@s.whatsapp.net"
}

POST /chat/getBase64FromMediaMessage/{instance} — Get media as base64

Downloads a media message and returns it as a base64 string.

Field	Type	Required	Description
`message`	object	Yes	Full message object, or an object carrying only `key` so it can be fetched.
`message.key`	object	No	Message key with `id`, `remoteJid`, `fromMe`.
`convertToMp4`	boolean	No	Convert the media to MP4 when applicable.

{
  "message": {
    "key": {
      "id": "BAE5F5A632EAE722",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    }
  },
  "convertToMp4": false
}

POST /chat/updateMessage/{instance} — Edit sent message

Edits the text of a message previously sent by this number.

Field	Type	Required	Description
`number`	string	Yes	Recipient number / chat the message was sent to.
`text`	string	Yes	New message text.
`key`	object	Yes	Key of the message to edit (`id`, `remoteJid`, `fromMe`).

{
  "number": "5511999999999",
  "text": "Edited message text",
  "key": {
    "id": "BAE5F5A632EAE722",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": true
  }
}

POST /chat/sendPresence/{instance} — Send presence update

Sends a presence indicator (typing, recording, etc.) to a chat.

Field	Type	Required	Description
`number`	string	Yes	Recipient number.
`presence`	string	Yes	One of `unavailable`, `available`, `composing`, `recording`, `paused`.
`delay`	number	Yes	Duration in milliseconds to keep the presence active.

{
  "number": "5511999999999",
  "presence": "composing",
  "delay": 2000
}

POST /chat/updateBlockStatus/{instance} — Block or unblock contact

Blocks or unblocks a contact.

Field	Type	Required	Description
`number`	string	Yes	Contact number to block/unblock.
`status`	string	Yes	Either `block` or `unblock`.

{
  "number": "5511999999999",
  "status": "block"
}

GET /chat/findChatByRemoteJid/{instance} — Find chat by JID

Returns the chat matching the given remote JID. Pass remoteJid as a required query parameter (e.g. ?remoteJid=5511999999999@s.whatsapp.net); there is no request body.No request body.

POST /chat/findContacts/{instance} — Find contacts

Searches stored contacts, optionally filtered by a where clause. Send an empty body to return all contacts.

Field	Type	Required	Description
`where`	object	No	Filter with any of `_id`, `id`, `pushName`, `remoteJid`.

{
  "where": {
    "id": "5511999999999@s.whatsapp.net"
  }
}

POST /chat/findMessages/{instance} — Find messages

Searches stored messages, optionally filtered by a where clause and limited by limit.

Field	Type	Required	Description
`where`	object	No	Filter with `_id`, `key` (`id`, `remoteJid`, `fromMe`), or `message`.
`limit`	integer	No	Maximum number of messages to return.

{
  "where": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net"
    }
  },
  "limit": 20
}

POST /chat/findStatusMessage/{instance} — Find message statuses

Searches message delivery/read status updates, optionally filtered by a where clause and limited by limit.

Field	Type	Required	Description
`where`	object	No	Filter with `_id`, `remoteJid`, `id`, `fromMe`, `participant`, or `status`.
`where.status`	string	No	One of `ERROR`, `PENDING`, `SERVER_ACK`, `DELIVERY_ACK`, `READ`, `PLAYED`.
`limit`	integer	No	Maximum number of records to return.

{
  "where": {
    "remoteJid": "5511999999999@s.whatsapp.net",
    "status": "READ"
  },
  "limit": 20
}

POST /chat/findChats/{instance} — Find chats

Returns stored chats, optionally filtered by a where clause. Send an empty body to return all chats.

Field	Type	Required	Description
`where`	object	No	Filter with any of `_id`, `id`, `pushName`, `remoteJid`.

{
  "where": {
    "remoteJid": "5511999999999@s.whatsapp.net"
  }
}

Profile

Read and update the connected number’s own profile (name, status, picture), inspect other users’ profiles, and manage privacy settings. In every path {instance} is the number’s display name — never send it in the body.

POST /chat/fetchProfilePictureUrl/{instance} — Get profile picture URL

Fetches the profile picture URL of a WhatsApp contact.

Field	Type	Required	Description
`number`	string	Yes	Phone number or JID whose profile picture URL to fetch.

{
  "number": "5511999999999"
}

POST /chat/fetchBusinessProfile/{instance} — Get business profile

Fetches the WhatsApp Business profile (category, description, email, website) of a number.

Field	Type	Required	Description
`number`	string	Yes	Phone number or JID of the business account to inspect.

{
  "number": "5511999999999"
}

POST /chat/fetchProfile/{instance} — Get contact profile

Fetches the full profile (name, status, picture, business flag) of a contact.

Field	Type	Required	Description
`number`	string	Yes	Phone number or JID whose profile to fetch.

{
  "number": "5511999999999"
}

POST /chat/updateProfileName/{instance} — Update own display name

Updates the connected number’s own WhatsApp display name.

Field	Type	Required	Description
`name`	string	Yes	New display name for the connected number.

{
  "name": "Pilot Status Support"
}

POST /chat/updateProfileStatus/{instance} — Update own status text

Updates the connected number’s own “about” / status text.

Field	Type	Required	Description
`status`	string	Yes	New status/about text for the connected number.

{
  "status": "Available for support 24/7"
}

POST /chat/updateProfilePicture/{instance} — Update own profile picture

Updates the connected number’s own profile picture from a URL or base64 image.

Field	Type	Required	Description
`picture`	string	Yes	Image as a public URL or a base64-encoded string.

{
  "picture": "https://example.com/avatar.png"
}

DELETE /chat/removeProfilePicture/{instance} — Remove own profile picture

Removes the connected number’s own profile picture. Targets the number identified by the {instance} path parameter.No request body.

GET /chat/fetchPrivacySettings/{instance} — Get privacy settings

Returns the connected number’s current privacy settings. Targets the number identified by the {instance} path parameter.No request body.

POST /chat/updatePrivacySettings/{instance} — Update privacy settings

Updates the connected number’s privacy settings; all six fields are required.

Field	Type	Required	Description
`readreceipts`	string	Yes	Read receipts visibility: `all` or `none`.
`profile`	string	Yes	Profile photo visibility: `all`, `contacts`, `contact_blacklist`, or `none`.
`status`	string	Yes	Status/about visibility: `all`, `contacts`, `contact_blacklist`, or `none`.
`online`	string	Yes	Online presence visibility: `all` or `match_last_seen`.
`last`	string	Yes	Last-seen visibility: `all`, `contacts`, `contact_blacklist`, or `none`.
`groupadd`	string	Yes	Who can add to groups: `all`, `contacts`, `contact_blacklist`, or `none`.

{
  "readreceipts": "all",
  "profile": "contacts",
  "status": "contacts",
  "online": "all",
  "last": "contacts",
  "groupadd": "contacts"
}

Group

Create and manage WhatsApp groups. Every path ends with /{instance}, the number’s display name, passed as a path parameter (never in the body).

POST /group/create/{instance} — Create group

Creates a new WhatsApp group with a subject and an initial list of participants.

Field	Type	Required	Description
`subject`	string	Yes	Group name/subject.
`participants`	string[]	Yes	Phone numbers (digits only) to add as members.
`description`	string	No	Group description.
`profilePicture`	string	No	URL of the group profile picture.
`promoteParticipants`	boolean	No	Promote the added participants to admins.

{
  "subject": "Equipe de Vendas",
  "participants": ["5511999999999", "5511888888888"],
  "description": "Grupo interno da equipe",
  "profilePicture": "https://example.com/group.png",
  "promoteParticipants": false
}

POST /group/updateGroupSubject/{instance} — Update subject

Changes the name/subject of an existing group.

Field	Type	Required	Description
`groupJid`	string	Yes	Group JID (may also be sent as a `groupJid` query parameter).
`subject`	string	Yes	New group subject.

{
  "groupJid": "120363000000000000@g.us",
  "subject": "Novo nome do grupo"
}

POST /group/updateGroupPicture/{instance} — Update picture

Sets the group profile picture from an image URL.

Field	Type	Required	Description
`groupJid`	string	Yes	Group JID (may also be sent as a `groupJid` query parameter).
`image`	string	Yes	URL of the new group picture.

{
  "groupJid": "120363000000000000@g.us",
  "image": "https://example.com/group.png"
}

POST /group/updateGroupDescription/{instance} — Update description

Updates the group’s description text.

Field	Type	Required	Description
`groupJid`	string	Yes	Group JID (may also be sent as a `groupJid` query parameter).
`description`	string	Yes	New group description.

{
  "groupJid": "120363000000000000@g.us",
  "description": "Descrição atualizada do grupo"
}

GET /group/findGroupInfos/{instance} — Get group info

Returns metadata for a single group. Pass the group JID as the groupJid query parameter (e.g. ?groupJid=120363000000000000@g.us).No request body.

GET /group/fetchAllGroups/{instance} — List all groups

Returns every group the number belongs to. The required getParticipants query parameter ("true" or "false") controls whether each group’s participant list is included.No request body.

GET /group/participants/{instance} — List participants

Returns the participant list of a group. Pass the group JID as the groupJid query parameter.No request body.

GET /group/inviteCode/{instance} — Get invite code

Returns the current invite code/link for a group. Pass the group JID as the groupJid query parameter.No request body.

GET /group/inviteInfo/{instance} — Get invite info

Returns the group information behind an invite code. Pass the code as the inviteCode query parameter (e.g. ?inviteCode=F1EX5QZxO181L3TMVP31gY).No request body.

GET /group/acceptInviteCode/{instance} — Accept invite

Joins a group using an invite code. Pass the code as the inviteCode query parameter.No request body.

POST /group/sendInvite/{instance} — Send invite

Sends the group invite link to one or more phone numbers.

Field	Type	Required	Description
`groupJid`	string	Yes	Group JID.
`description`	string	Yes	Message text sent alongside the invite.
`numbers`	string[]	Yes	Phone numbers (digits only) to send the invite to.

{
  "groupJid": "120363000000000000@g.us",
  "description": "Entre no nosso grupo!",
  "numbers": ["5511999999999", "5511888888888"]
}

POST /group/revokeInviteCode/{instance} — Revoke invite

Revokes the current invite link and generates a new one.

Field	Type	Required	Description
`groupJid`	string	Yes	Group JID (may also be sent as a `groupJid` query parameter).

{
  "groupJid": "120363000000000000@g.us"
}

POST /group/updateParticipant/{instance} — Update participants

Adds, removes, promotes, or demotes group participants.

Field	Type	Required	Description
`groupJid`	string	Yes	Group JID (may also be sent as a `groupJid` query parameter).
`action`	string	Yes	One of `add`, `remove`, `promote`, `demote`.
`participants`	string[]	Yes	Phone numbers (digits only) to apply the action to.

{
  "groupJid": "120363000000000000@g.us",
  "action": "add",
  "participants": ["5511999999999"]
}

POST /group/updateSetting/{instance} — Update setting

Updates a group’s messaging and editing permissions.

Field	Type	Required	Description
`groupJid`	string	Yes	Group JID (may also be sent as a `groupJid` query parameter).
`action`	string	Yes	One of `announcement`, `not_announcement`, `locked`, `unlocked`.

{
  "groupJid": "120363000000000000@g.us",
  "action": "announcement"
}

POST /group/updateMemberAddMode/{instance} — Update member add mode

Controls who is allowed to add new members to the group.

Field	Type	Required	Description
`groupJid`	string	Yes	Group JID (may also be sent as a `groupJid` query parameter).
`mode`	string	Yes	One of `admin_add`, `all_member_add`.

{
  "groupJid": "120363000000000000@g.us",
  "mode": "admin_add"
}

POST /group/toggleEphemeral/{instance} — Toggle disappearing messages

Enables or disables disappearing messages for the group.

Field	Type	Required	Description
`groupJid`	string	Yes	Group JID (may also be sent as a `groupJid` query parameter).
`expiration`	integer	Yes	Seconds until messages disappear: `0` (off), `86400` (24h), `604800` (7d), or `7776000` (90d).

{
  "groupJid": "120363000000000000@g.us",
  "expiration": 604800
}

DELETE /group/leaveGroup/{instance} — Leave group

Removes the connected number from the group. Pass the group JID as the groupJid query parameter.No request body.

Label

Manage WhatsApp chat labels for a connected number.

GET /label/findLabels/{instance} — List labels

Returns all labels defined on the number identified by the {instance} path parameter (the number’s display name).No request body.

POST /label/handleLabel/{instance} — Add or remove label

Adds or removes a label on a chat for the number identified by the {instance} path parameter.

Field	Type	Required	Description
`number`	string	Yes	Recipient phone number in international format (non-empty).
`labelId`	string	Yes	Identifier of the label to apply or remove (non-empty).
`action`	string	Yes	Operation to perform; either `add` or `remove`.

{
  "number": "5511999999999",
  "labelId": "1",
  "action": "add"
}

Template

Manage WhatsApp message templates (HSMs) for a connected number. In every path, {instance} is the number’s display name.

POST /template/create/{instance} — Create template

Creates a new message template for the instance.

Field	Type	Required	Description
`name`	string	Yes	Unique template name (lowercase, underscores).
`category`	string	Yes	Template category: `AUTHENTICATION`, `MARKETING`, or `UTILITY`.
`language`	string	Yes	Language/locale code (e.g. `pt_BR`, `en_US`).
`components`	array	Yes	Template component objects (header, body, footer, buttons).
`allowCategoryChange`	boolean	No	Allow Meta to reassign the category during review.
`webhookUrl`	string	No	URL notified about template status changes.

{
  "name": "order_confirmation",
  "category": "UTILITY",
  "language": "pt_BR",
  "allowCategoryChange": true,
  "components": [
    {
      "type": "BODY",
      "text": "Ola {{1}}, seu pedido {{2}} foi confirmado."
    }
  ],
  "webhookUrl": "https://example.com/webhooks/template-status"
}

POST /template/edit/{instance} — Edit template

Updates an existing template identified by its Meta template ID.

Field	Type	Required	Description
`templateId`	string	Yes	Meta template ID to edit.
`category`	string	No	New category: `AUTHENTICATION`, `MARKETING`, or `UTILITY`.
`allowCategoryChange`	boolean	No	Allow Meta to reassign the category during review.
`ttl`	number	No	Time-to-live for authentication templates, in seconds.
`components`	array	No	Replacement template component objects.

{
  "templateId": "1234567890123456",
  "category": "UTILITY",
  "allowCategoryChange": false,
  "ttl": 600,
  "components": [
    {
      "type": "BODY",
      "text": "Ola {{1}}, seu pedido {{2}} esta a caminho."
    }
  ]
}

DELETE /template/delete/{instance} — Delete template

Deletes a template by name (optionally scoped by its HSM ID).

Field	Type	Required	Description
`name`	string	Yes	Name of the template to delete.
`hsmId`	string	No	Specific HSM/template ID to target a single language version.

{
  "name": "order_confirmation",
  "hsmId": "1234567890123456"
}

GET /template/find/{instance} — List templates

Returns all templates registered for the instance. The instance display name is taken from the path.No request body.

Settings & Proxy

Configure per-number behavior settings and outbound proxy for the connected instance.

POST /settings/set/{instance} — Update settings

Sets the behavior settings for the instance named in the {instance} path parameter.

Field	Type	Required	Description
`rejectCall`	boolean	Yes	Automatically reject incoming WhatsApp calls.
`msgCall`	string	No	Message sent to the caller when a call is rejected.
`groupsIgnore`	boolean	Yes	Ignore messages coming from groups.
`alwaysOnline`	boolean	Yes	Keep the connection presence as always online.
`readMessages`	boolean	Yes	Automatically mark incoming messages as read.
`readStatus`	boolean	Yes	Automatically mark status/story updates as read.
`syncFullHistory`	boolean	Yes	Sync the full message history on connect.
`wavoipToken`	string	No	WAVOIP token used to enable voice-call handling.

{
  "rejectCall": true,
  "msgCall": "Sorry, I can't take calls right now.",
  "groupsIgnore": false,
  "alwaysOnline": true,
  "readMessages": false,
  "readStatus": false,
  "syncFullHistory": false,
  "wavoipToken": ""
}

GET /settings/find/{instance} — Read settings

Returns the current settings for the instance named in the {instance} path parameter.No request body.

POST /proxy/set/{instance} — Configure proxy

Sets the outbound proxy for the instance named in the {instance} path parameter.

Field	Type	Required	Description
`enabled`	boolean	Yes	Whether the proxy is enabled for this instance.
`host`	string	Yes	Proxy host name or IP address.
`port`	string	Yes	Proxy port.
`protocol`	string	Yes	Proxy protocol (e.g. `http`, `https`, `socks5`).
`username`	string	No	Username for proxy authentication.
`password`	string	No	Password for proxy authentication.

{
  "enabled": true,
  "host": "proxy.example.com",
  "port": "8080",
  "protocol": "http",
  "username": "proxyuser",
  "password": "proxypass"
}

GET /proxy/find/{instance} — Read proxy

Returns the current proxy configuration for the instance named in the {instance} path parameter.No request body.

Call & Business

Offer a WhatsApp call and read a connected business number’s product catalog and collections.

POST /call/offer/{instance} — Offer a call

Offers a voice or video call to a recipient number for a bounded ringing duration.

Field	Type	Required	Description
`number`	string	Yes	Recipient phone number in international format.
`callDuration`	integer	Yes	How long the call rings, in seconds (1–15).
`isVideo`	boolean	No	`true` for a video call, `false` for voice.

{
  "number": "5511999999999",
  "callDuration": 10,
  "isVideo": false
}

POST /business/getCatalog/{instance} — Fetch product catalog

Fetches the product catalog for a business WhatsApp number.

Field	Type	Required	Description
`number`	string	No	Business phone number whose catalog to fetch; defaults to the instance’s own number.
`limit`	number	No	Maximum number of products to return.

{
  "number": "5511999999999",
  "limit": 50
}

POST /business/getCollections/{instance} — Fetch collections

Fetches the catalog collections for a business WhatsApp number.

Field	Type	Required	Description
`number`	string	No	Business phone number whose collections to fetch; defaults to the instance’s own number.
`limit`	number	No	Maximum number of collections to return.

{
  "number": "5511999999999",
  "limit": 20
}

Integrations / chatbots

Each chatbot integration — evolutionBot, typebot, openai, dify, flowise, n8n, and evoai — exposes the same set of endpoints (replace {name} with the integration name):

Method	Path
`POST`	`/{name}/create/{instance}`
`GET`	`/{name}/find/{instance}`
`GET`	`/{name}/fetch/{id}/{instance}`
`PUT`	`/{name}/update/{id}/{instance}`
`DELETE`	`/{name}/delete/{id}/{instance}`
`POST`	`/{name}/settings/{instance}`
`GET`	`/{name}/fetchSettings/{instance}`
`POST`	`/{name}/changeStatus/{instance}`
`GET`	`/{name}/fetchSessions/{id}/{instance}`
`POST`	`/{name}/ignoreJid/{instance}`

Integration-specific extras:

Method	Path
`POST`	`/typebot/start/{instance}`
`POST` / `GET`	`/openai/creds/{instance}`
`DELETE`	`/openai/creds/{id}/{instance}`
`GET`	`/openai/getModels/{instance}`
`POST`	`/chatwoot/set/{instance}`
`GET`	`/chatwoot/find/{instance}`
`POST`	`/chatwoot/webhook/{instance}`

Event brokers

Each broker — webhook, websocket, rabbitmq, nats, pusher, sqs, and kafka — exposes set/find (replace {name} with the broker name):

Method	Path
`POST`	`/{name}/set/{instance}`
`GET`	`/{name}/find/{instance}`

Storage (S3)

Retrieve media stored in the S3/MinIO bucket for the connected number ({instance} is the number’s display name).

POST /s3/getMedia/{instance} — List stored media

Returns the stored media records for the instance, optionally filtered by the given fields.

Field	Type	Required	Description
`id`	string	No	Media record identifier to filter by.
`type`	string	No	Media type to filter by (e.g. `image`, `video`, `audio`, `document`).
`messageId`	integer	No	Message identifier the media belongs to.

{
  "id": "5f3e1d2c-8b7a-4c6d-9e0f-1a2b3c4d5e6f",
  "type": "image",
  "messageId": 12345
}

POST /s3/getMediaUrl/{instance} — Get presigned media URL

Resolves a media record by id and returns a temporary presigned download URL along with the media metadata.

Field	Type	Required	Description
`id`	string	Yes	Media record identifier (numeric string).
`expiry`	string	No	Lifetime of the presigned URL, in seconds (numeric string, e.g. `"3600"`).

{
  "id": "12345",
  "expiry": "3600"
}

Blocked (global)

Server-wide (global) paths are not part of the migration layer and always return 403. This includes: GET / (root), POST /verify-creds, GET /manager, GET /metrics, GET /assets/*, POST /instance/create, and GET /instance/fetchInstances. Provision and manage your numbers through the Pilot Status dashboard or the native API instead. Any path not listed in this catalog returns 404.

Events

The layer forwards inbound events to the webhook you configured for the number, in Evolution API V2’s own native format (lowercase, dot-separated event names):

Event	Event
`messages.upsert`	`messages.edited`
`messages.update`	`messages.delete`
`send.message`	`send.message.update`
`connection.update`	`qrcode.updated`
`logout.instance`	`contacts.upsert`
`contacts.update`	`chats.upsert`
`chats.update`	`chats.delete`
`presence.update`	`groups.upsert`
`groups.update`	`group-participants.update`
`call`	`typebot.start`
`typebot.change-status`	`labels.edit`
`labels.association`

In addition, Pilot Status can deliver its own normalized events alongside the native ones: the call lifecycle events call.ringing, call.connected, call.ended, and call.missed, plus number lifecycle events number.created, number.connected, number.disconnected, and number.removed.

Example: send text via Evolution V2 layer

The request below is a standard Evolution V2 send-text call routed through the Pilot Status layer. Notice that the request body uses the Evolution V2 format unchanged.

curl -X POST 'https://pilotstatus.com.br/api/layer/evolution-v2/message/sendText/MyInstance' \
  -H 'apikey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "5511999999999",
    "text": "Hello from Pilot Status via API Layer! 👋"
  }'

Replace MyInstance with the display name you assigned your number in the Pilot Status dashboard.

Instance name mapping

In Evolution V2, each instance represents a WhatsApp connection identified by a name. Pilot Status uses the same convention — the instance name in your URL path maps to the display name you assigned your number when connecting it through the Pilot Status dashboard. For example, if you named your number SupportLine in the dashboard, your requests should use:

POST /message/sendText/SupportLine

If you have multiple numbers, each one has its own display name and behaves as a separate instance — consistent with how Evolution V2 manages multiple instances.

For new projects, consider using the native Pilot Status API — it provides full access to all features including official Meta integration and advanced analytics.

For general migration guidance and an overview of all supported providers, see the API Layer overview.

Overview

Messaging

Templates

Numbers

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

Evolution V2 Compatibility Layer — API Reference

Base URL

Authentication

Supported operations

Instance

Message

Chat

Profile

Group

Label

Template

Settings & Proxy

Call & Business

Integrations / chatbots

Event brokers

Storage (S3)

Blocked (global)

Events

Example: send text via Evolution V2 layer

Instance name mapping

​Base URL

​Authentication

​Supported operations

​Instance

​Message

​Chat

​Profile

​Group

​Label

​Template

​Settings & Proxy

​Call & Business

​Integrations / chatbots

​Event brokers

​Storage (S3)

​Blocked (global)

​Events

​Example: send text via Evolution V2 layer

​Instance name mapping

Base URL

Authentication

Supported operations

Instance

Message

Chat

Profile

Group

Label

Template

Settings & Proxy

Call & Business

Integrations / chatbots

Event brokers

Storage (S3)

Blocked (global)

Events

Example: send text via Evolution V2 layer

Instance name mapping