skill-evolution-api

name	skill-evolution-api
description	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.
category	communication
risk	medium
source	evolution-api-local-patterns

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