# Skill Evolution API

> Use for WhatsApp automation with Evolution API, including instance lifecycle, QR pairing, inbound and outbound messages, webhooks, consent, tenant isolation, queues, idempotency, rate limits, retries, audit logs, and reliable delivery.

- Skill: `iapro-community/skill-evolution-api-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iapro-community/skill-evolution-api-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iapro-community/skill-evolution-api-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: IAPro-Community (https://skillmd.com/u/iapro-community)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/iapro-community/skill-evolution-api-2

---


# Evolution API

Use this skill when integrating WhatsApp through Evolution API. Treat every message as sensitive customer communication.

## Core Workflow

1. Confirm the tenant, WhatsApp account owner, business purpose, user consent model, and allowed message categories.
2. Keep Evolution API keys, webhook secrets, and instance credentials server-side only.
3. Model each instance as tenant-owned state with lifecycle, QR pairing state, webhook status, heartbeat, and disconnect reason.
4. Queue outbound sends. Apply per-instance, per-tenant, and per-contact rate limits before enqueueing.
5. Assign every outbound request a stable idempotency key based on tenant, instance, recipient, template or body hash, and campaign or workflow ID.
6. Treat webhooks as at-least-once delivery. Verify signature when available, dedupe by provider message ID, and make handlers idempotent.
7. Persist delivery, read, inbound, disconnect, reconnect, and pairing events as append-only state transitions.
8. Redact message bodies in logs unless a support or audit policy explicitly requires short-lived encrypted retention.
9. Surface recoverable admin states: QR expired, disconnected, webhook failing, send queued, send failed, rate limited, and consent missing.

## Consent and Compliance

- Require explicit opt-in before sending non-transactional messages.
- Store consent source, timestamp, contact identity, tenant, scope, and revocation timestamp.
- Stop queued campaign or automation messages immediately when consent is revoked.
- Keep templates, campaign labels, and operator identity attached to sends for audit.

## Minimal Data Model

- `whatsapp_instances`: tenant ID, owner ID, instance name, status, QR state, webhook status, last heartbeat, disconnect reason.
- `whatsapp_contacts`: tenant ID, normalized number, profile name, consent state, consent scope, last inbound time.
- `message_events`: tenant ID, instance ID, provider message ID, idempotency key, direction, status, retry count, error class, timestamps.
- `message_threads`: tenant ID, contact ID, assignment state, last message time, unread count.

## Verification

- Test QR pairing, reconnect, disconnect, outbound queueing, duplicate outbound retry, inbound webhook dedupe, revoked consent, and rate-limit behavior.
- Confirm API keys and message bodies are absent from client bundles and normal logs.
- Replay the same webhook payload twice and verify only one business effect occurs.

## Related Skills

- `skill-saas-admin-dashboard`
- `skill-unified-analytics`
- `skill-security-hooks`