UZapi n8n Node

Custom n8n node that integrates with the UZapi WhatsApp API, enabling you to start sessions, retrieve status, generate QR codes, and send different message types (text, media, files, Base64, etc.).

---

Table of Contents

1. Features
2. Architecture
3. File Structure
4. Prerequisites
5. Installation
6. Credential Configuration
7. Node Parameters
8. Supported Operations
9. Example Workflow
10. Development
11. Testing
12. Contributing
13. License

---

Features

• Start Session – initialise a WhatsApp session in UZapi.
• Session Status – query the current status of a session.
• Generate QR – fetch & pad the QR code returned by the API.
• Send Messages – text, link previews, images, videos, audio, generic files or Base64‑encoded files.
• Flexible Input – choose between providing a URL, local path or binary input for sendFile64.
• Typed Codebase – full TypeScript with strict typings for operations & properties.
• Modular Design – helpers & operations separated for easy maintenance.

---

Architecture

UZapi.node.ts          ← n8n Node wrapper (entry point)
│
├─ apiClient.ts        ← Thin HTTP wrapper using n8n helpers
├─ operations/         ← One file per UZapi endpoint (startSession, sendText …)
│   └─ index.ts        ← `operationsMap` exports all handlers
├─ credentials/        ← Credential definition & helpers
│
├─ utils/
│   ├─ properties/     ← Node parameter metadata (no code)
│   └─ files/          ← Shared helpers (toDataUri, …)
└─ UZapi.node.json     ← Codex metadata (categories, docs links)

The node delegates every operation to an isolated handler in operations/. Each handler receives the context (IExecuteFunctions), an ApiClient instance, and the item index – mirroring the functional style of native n8n nodes.

---

File Structure

Path	Purpose
nodes/UZapi/UZapi.node.ts	Main node class implementing execute()
nodes/UZapi/apiClient.ts	Reusable wrapper around helpers.requestWithAuthentication
nodes/UZapi/operations/	Endpoint handlers (pure functions)
nodes/UZapi/operations/index.ts	operationsMap exports all handlers
nodes/UZapi/credentials/UZapiApi.credentials.ts	Credential type (base URL)
nodes/UZapi/credentials/uzapiCredentialProperties.ts	Typed credential fields & auth config
nodes/UZapi/utils/properties/	Parameter metadata & option literals
nodes/UZapi/utils/files/fileUtils.ts	Helper to convert local files → data: URIs
nodes/UZapi/UZapi.node.json	Codex definition (categories + docs)

---

Prerequisites

• n8n 1.45 + (self‑hosted or desktop)
• Valid UZapi account / API token (for protected endpoints)
• Node .js ≥ 18 + Yarn/PNPM/NPM if you plan to build locally

---

Installation

1. Clone the repository into your custom directory:

   git clone https://github.com/your‑org/n8n‑uzapi‑node.git
   cd n8n‑uzapi‑node
   

2. Install dependencies & build:

   npm install && npm run build
   

3. Restart n8n – the node UZapi should appear under Miscellaneous.

---

Credential Configuration

Field	Description
Base URL	Root URL of UZapi (default: https://teste.uzapi.com.br:3333).

After saving, reference this credential in your UZapi node instance; authentication headers will be injected automatically.

---

Node Parameters

Parameter	Type	Visibility	Description
Operation	options	Always	Which UZapi endpoint to call.
API Token	string	startSession	Token for auth (if required by your plan).
Session Key	string	Most operations	UUID provided during onboarding.
Session	string	Most operations	Session ID returned by /start.
Número (com DDI)	string	Message sends	Destination in E.164 (e.g. 5511999998888).
Texto	string	sendtext / sendLink	Message body.
URL	string	sendLink	Link to preview.
Descrição (caption)	string	Media & files	Caption for media / document.
Link (path)	string	Media (URL)	Public URL or local path (will be sent as‑is).
Arquivo (binaryPropertyName)	string	sendFile64	If not set, the node falls back to the item’s binary data.

---

Supported Operations

Value	Endpoint	Description
startSession	POST /start	Create / resume a session.
getStatus	POST /getSessionStatus	Retrieve current session state.
generateQr	GET /getQrCode	Download QR (binary), add padding & output as binary field qrImage.
sendtext	POST /sendText	Plain text message.
sendLink	POST /sendLink	Text + url with preview.
sendImage	POST /sendImage	Image by URL/path with caption.
sendFile	POST /sendFile	Document by URL/path with caption.
sendAudio	POST /sendAudio	Audio file by URL/path with caption.
sendVideo	POST /sendVideo	Video file by URL/path with caption.
sendFile64	POST /sendFile64	File via data URI (handles binary → base64 automatically).

---

The project uses ESLint with @typescript-eslint. All source lives in src/ and compiles to dist/.

Releasing a new version

1. Bump version in package.json.
2. Run npm run build.
3. Publish the package or copy dist/ into your n8n instance.

---

Testing

Right now the node is covered by integration tests that hit the UZapi sandbox. Run them with:

npm test

Note: Provide environment variables UZAPI_BASE_URL, UZAPI_SESSION_KEY, UZAPI_SESSION etc. for the tests to interact with a real account.

---

Contributing

Pull Requests are welcome! Please open an issue first to discuss your feature or bug‑fix. Make sure to:

• Follow the existing code style (Prettier + ESLint).
• Add / update tests.
• Update this documentation if behaviour changes.

---

License

MIT © 2025 UZapi