Description

—

✨ Por que esse pacote

A maioria dos nodes WhatsApp pra n8n cobre 4 ou 5 endpoints e te deixa na mão quando você quer fazer algo sério — enviar carrossel, gerenciar grupos, disparar campanhas em massa, plugar agentes de IA, registrar webhook automaticamente. Esse aqui cobre toda a superfície da uazapiGO V2 em dois nodes únicos:

• 🟢 Uazapi — node de ação declarativo cobrindo 12 resources e 93 operations (enviar texto, mídia, menus, pix, gerenciar chats, grupos, contatos, labels, perfil business, catálogos, disparos em massa, CRM, chatbot, instâncias admin)
• 🟣 Uazapi Trigger — node de gatilho com dois modos:

– Webhook — registra automaticamente o webhook na sua instância uazapi quando o workflow ativa, e remove ao desativar
– SSE — conexão long-lived com reconexão exponencial, sem precisar expor URL pública

—

🚀 Instalação

Via n8n Community Nodes (recomendado)

1. Abra o n8n
2. Settings → Community Nodes → Install
3. Cole @saraivadev/n8n-nodes-uazapi e confirme
4. Reinicie se solicitado

Via CLI (self-hosted)

cd ~/.n8n/custom        # ou onde sua instância carrega custom nodes
npm install @saraivadev/n8n-nodes-uazapi
reinicie o n8n

Docker

Adicione ao docker-compose.yml:

environment:
  - N8NCOMMUNITYPACKAGES=@saraivadev/n8n-nodes-uazapi

—

🔑 Credentials

Crie uma credencial Uazapi API com 3 campos:

| Campo | Obrigatório | Descrição |
|—|:—:|—|
| Base URL | ✅ | Ex: https://saraivaai.uazapi.com (sem barra no fim) |
| Instance Token | ✅ | Token da instância — header token |
| Admin Token | ⚪ | Token administrativo — header admintoken. Só é usado pelo resource Admin (override automático). |

O botão “Test” bate em GET /instance/status pra validar.

—

📦 Resources & Operations

📱 Message — 17 operations

| Operation | Endpoint | Descrição |
|—|—|—|
| Send Text | POST /send/text | Texto simples com link preview opcional |
| Send Media | POST /send/media | image / video / document / audio / myaudio / ptt / ptv / sticker |
| Send Contact | POST /send/contact | vCard contact |
| Send Location | POST /send/location | Lat/long com nome e endereço |
| Send Menu | POST /send/menu | button / list / poll / carousel |
| Send Carousel | POST /send/carousel | Carrossel multi-card |
| Send Location Request | POST /send/location-button | Botão pedindo localização |
| Send Payment Request | POST /send/request-payment | PIX, boleto, link de pagamento |
| Send PIX Button | POST /send/pix-button | Botão de PIX rápido |
| Send Status | POST /send/status | Stories (text / image / video / audio) |
| Send Presence In Chat | POST /message/presence | composing / recording / paused |
| React | POST /message/react | Emoji em mensagem |
| Edit | POST /message/edit | Edita texto de mensagem enviada |
| Delete | POST /message/delete | Apaga mensagem |
| Mark As Read | POST /message/markread | Marca múltiplas como lidas |
| Find | POST /message/find | Busca por filtros |
| Download Media | POST /message/download | Download + transcrição opcional via OpenAI |

Toda operação send/* expõe uma collection Additional Fields com delay, readchat, readmessages, replyid, mentions (array → CSV), forward, tracksource, trackid, async.

🔌 Instance — 11 operations

connect · disconnect · status · updateName · delete · getPrivacy · setPrivacy · updatePresence · getProxy · setProxy · deleteProxy

💬 Chat — 11 operations

find · details · archive · read · mute · pin · delete · block · listBlocked · checkOnWhatsApp · manageLabels

👥 Contact — 4 operations

listAll · listPaginated · add · remove

👨‍👩‍👧‍👦 Group — 13 operations

create · info · inviteInfo · join · leave · list · resetInviteCode · updateAnnounce · updateDescription · updateImage · updateLocked · updateName · manageParticipants (add/remove/promote/demote/approve/reject)

🏷️ Label — 2 operations

list · edit (criar, renomear, recolorir ou deletar label)

🧑 Profile — 2 operations

updateName · updateImage

🏢 Business — 8 operations

getProfile · getCategories · updateProfile · listCatalog · getProduct · deleteProduct · showProduct · hideProduct

📢 Sender (disparo em massa) — 7 operations

| Operation | Para que serve |
|—|—|
| Simple | Disparo simples com lista de números e mensagem única |
| Advanced | Disparo avançado com array de mensagens customizadas |
| Control | Stop / continue / delete de uma folder de campanha |
| Clear Done | Limpa campanhas finalizadas |
| Clear All | Limpa todas as campanhas |
| List Folders | Lista folders por status |
| List Messages | Lista mensagens de uma folder |

📈 CRM — 2 operations

updateFieldsMap · editLead (leadstatus, leadvalue, leadtags, leadfield01..lead_field20)

🤖 Chatbot — 11 operations

updateSettings + CRUD para trigger / agent / knowledge / function / quickReply (cada um com Edit + List)

👑 Admin — 5 operations (requer Admin Token)

createInstance · listInstances · updateInstance · getGlobalWebhook · setGlobalWebhook

> 🛡️ Todas as operações Admin sobrescrevem automaticamente o header token por admintoken. Você não precisa fazer nada além de preencher o Admin Token na credencial.

—

🎯 Exemplos rápidos

Enviar texto simples

Resource: Message
Operation: Send Text
Number: 5511999999999
Text: Olá, tudo bem?

Enviar imagem com legenda e delay

Resource: Message
Operation: Send Media
Number: 5511999999999
Media Type: Image
File: https://exemplo.com/foto.jpg
Text: Olha essa foto
▾ Additional Fields
  Delay (Ms): 2000
  Read Chat: true

Disparo em massa com agendamento

Resource: Sender
Operation: Simple
Numbers: [5511...A, 5511...B, 5511...C]
Type: text
Delay Min: 3 / Delay Max: 7
Scheduled For: 1737240000   # unix timestamp
▾ Message Fields
  Text: Promoção exclusiva esta semana!
  Info: campanha-jan2026

Gatilho de mensagens recebidas (sem loop)

Trigger: Uazapi Trigger
Mode: Webhook
Events: [messages]
Exclude Messages: [wasSentByApi]    ← previne loop com seu próprio envio

—

📡 Uazapi Trigger em detalhe

🔵 Webhook Mode

1. Adicione o Uazapi Trigger ao workflow
2. Selecione Mode = Webhook e os events desejados
3. Ative o workflow — o trigger faz um POST /webhook na sua instância uazapi registrando a URL de produção do n8n
4. Ao desativar, o webhook é removido automaticamente

> Exclude Messages vem com wasSentByApi por padrão — mantenha se o mesmo workflow também envia mensagens, senão você cria um loop infinito.

🟢 SSE Mode

1. Selecione Mode = SSE e os events
2. O node abre uma conexão persistente em ${baseUrl}/sse?token=…&events=…
3. Reconexão com backoff exponencial: 5s → 10s → 20s → 40s → 60s
4. Cada evento vira um item no output

Use SSE quando sua instância n8n não tem URL pública (atrás de NAT, em dev local).

—

🛠️ Scripts (dev)

npm install
npm run dev          # n8n com hot reload
npm run build        # compila TypeScript pra dist/
npm run lint         # n8n-nodes-base lint
npm run lint:fix     # auto-fix

—

🤝 Contribuindo

PRs bem-vindos! Antes de abrir:

1. npm run lint deve passar com zero erros
2. npm run build deve compilar limpo
3. Mantenha descriptions alfabetizadas (regra do eslint-plugin-n8n-nodes-base)
4. Endpoints novos vão num arquivo *Description.ts próprio em nodes/Uazapi/descriptions/
5. Para o resource Admin, todo routing.request precisa de headers: { admintoken: '={{$credentials.adminToken}}' }

—

📜 Licença

MIT © Saraiva.ai

—

🔗 Links

• 📦 npm
• 🐙 GitHub
• 📖 uazapi docs
• 🌐 n8n