OpenParable
Skip to content
← Back to skills

Int Evolution API

Apps & Automation
int-evolution-api

Int Evolution API is an Agent Skill for apps & automation published in the evolution-foundation/evo-nexus repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Manage WhatsApp instances and send messages via the Evolution API. Use when you need to list/create/connect instances, send messages (text, media, location, contact, buttons, lists, polls), query chats/contacts, manage groups, or configure webhooks. Calls the Evolution API REST endpoints directly.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/evolution-foundation/evo-nexus/blob/HEAD/.claude/skills/int-evolution-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/int-evolution-api, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Evolution API

Interact with your Evolution API instance to manage WhatsApp connections, send messages, query chats, manage groups, and configure webhooks.

Setup (one-time)

  1. Get your API URL and global API key from your Evolution API instance.
  2. Set environment variables:
    EVOLUTION_API_URL=https://api.evolution-api.com
    EVOLUTION_API_KEY=your-global-api-key
    

Instance Management

List all instances

python3 scripts/evolution_api_client.py instances

Create a new instance

python3 scripts/evolution_api_client.py create_instance my-instance
python3 scripts/evolution_api_client.py create_instance my-instance --qrcode

Connect instance (returns QR code)

python3 scripts/evolution_api_client.py connect my-instance

Get connection state

python3 scripts/evolution_api_client.py connection_state my-instance

Restart an instance

python3 scripts/evolution_api_client.py restart my-instance

Logout and disconnect

python3 scripts/evolution_api_client.py logout my-instance

Delete an instance

python3 scripts/evolution_api_client.py delete_instance my-instance

Set presence

python3 scripts/evolution_api_client.py set_presence my-instance --presence available

Summary of all instances

python3 scripts/evolution_api_client.py summary

Send Messages

Send text

python3 scripts/evolution_api_client.py send_text my-instance 5511999999999 "Hello, world!"

Send media (image, video, audio, document)

python3 scripts/evolution_api_client.py send_media my-instance 5511999999999 --type image --url https://example.com/photo.jpg --caption "Check this out"

Send location

python3 scripts/evolution_api_client.py send_location my-instance 5511999999999 --lat -23.5505 --lng -46.6333 --name "Sao Paulo"

Send contact card

python3 scripts/evolution_api_client.py send_contact my-instance 5511999999999 --name "John Doe" --phone 5511888888888

Send buttons

python3 scripts/evolution_api_client.py send_buttons my-instance 5511999999999 --text "Choose an option" --buttons '[{"buttonId":"1","buttonText":{"displayText":"Option 1"}}]'

Send list

python3 scripts/evolution_api_client.py send_list my-instance 5511999999999 --title "Menu" --sections '[{"title":"Section 1","rows":[{"title":"Item 1","rowId":"1"}]}]'

Send poll

python3 scripts/evolution_api_client.py send_poll my-instance 5511999999999 --name "Favorite color?" --values "Red,Blue,Green"

React to a message

python3 scripts/evolution_api_client.py send_reaction my-instance --key '{"remoteJid":"[email protected]","fromMe":false,"id":"MSG_ID"}' --reaction "👍"

Send template message

python3 scripts/evolution_api_client.py send_template my-instance 5511999999999 "Template text here"

Chat Operations

Find chats

python3 scripts/evolution_api_client.py find_chats my-instance
python3 scripts/evolution_api_client.py find_chats my-instance --where '{"id":"[email protected]"}' --take 10

Find messages

python3 scripts/evolution_api_client.py find_messages my-instance --where '{"key":{"remoteJid":"[email protected]"}}' --take 20

Mark messages as read

python3 scripts/evolution_api_client.py mark_read my-instance --messages '[{"remoteJid":"[email protected]","fromMe":false,"id":"MSG_ID"}]'

Archive/unarchive chat

python3 scripts/evolution_api_client.py archive_chat my-instance 5511999999999 --archive true

Update profile name

python3 scripts/evolution_api_client.py update_profile_name my-instance "New Name"

Update profile status

python3 scripts/evolution_api_client.py update_profile_status my-instance "Available for business"

Contacts

Find contacts

python3 scripts/evolution_api_client.py find_contacts my-instance --where '{"id":"[email protected]"}'

Check numbers on WhatsApp

python3 scripts/evolution_api_client.py check_numbers my-instance --numbers 5511999999999,5511888888888

Group Operations

Create group

python3 scripts/evolution_api_client.py create_group my-instance --subject "My Group" --participants 5511999999999,5511888888888

Get group info

python3 scripts/evolution_api_client.py group_info my-instance --jid [email protected]

List group participants

python3 scripts/evolution_api_client.py group_participants my-instance --jid [email protected]

Add/remove/promote/demote participants

python3 scripts/evolution_api_client.py update_participant my-instance --jid [email protected] --action add --participants 5511999999999

Webhook Management

List webhooks

python3 scripts/evolution_api_client.py webhooks my-instance

Set webhook

python3 scripts/evolution_api_client.py set_webhook my-instance --url https://example.com/hook --events messages.upsert,connection.update

Delete webhook

python3 scripts/evolution_api_client.py delete_webhook my-instance

Output

All output is JSON to stdout. Use --json flag for raw JSON on any command (default behavior).

Notes

  • Phone numbers use country code format without + (e.g. 5511999999999).
  • Group JIDs follow the pattern [email protected].
  • The connect endpoint returns a QR code as base64 PNG in the response.
  • The summary command is composite: it calls fetchInstances then connectionState for each instance.