uzapi-business

Package Information

Released: 5/11/2025
Downloads: 10 weekly / 29 monthly
Latest Version: 0.1.2
Author: dotyocode

Available Nodes

UZapi Business icon
UZapi Business
Interage com a API da UZapi Business (WhatsApp Business)

Documentation

WhatsApp Business n8n Node

Custom n8n node integrating with the WhatsApp Business API via UZapi.
Enables session management (initialization and QR code generation) and sending any supported Cloud-API message type (text, image, audio, video, document, sticker, location, contacts, template, interactive).

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 & Testing
  11. Contributing
  12. License

Features

  • Session Management

    • Create or resume a WhatsApp Business session
    • Generate and deliver QR codes for authentication

  • Universal Messaging

    • Send text, image, audio, video, document, sticker, location, contacts, template, interactive messages
    • Automatic Base64 encoding for binary media

  • Centralized Credentials

    • Store Base URL, API Token, Username, Version, and Phone Number ID securely in n8n
    • Automatic injection of Authorization: Bearer <API_TOKEN> header

  • Modular Design

    • One operation handler per endpoint
    • Full TypeScript with strict typings

  • Flexible Inputs

    • Use public URLs or local file paths for media
    • Configure typing and send delays for messages

Architecture

nodes/UZapi/UZapi.node.ts            ← Main node class
└── credentials/
    └── uzapi.credentials.ts         ← Define Base URL, API Token, Username, Version, PhoneNumberId
└── apiClient.ts                     ← HTTP wrapper calling UZapi endpoints
└── operations/
    ├── generateQr.ts                ← Create instance & poll QR code
    ├── sendText.ts                  ← All Cloud-API message types
    └── …                             ← Other handlers (sendLink, sendImage, etc.)
└── utils/
    └── properties.ts                ← Node parameter definitions
└── options/
    └── options.ts                   ← Dropdown values for operations
└── UZapi.node.json                  ← Node metadata (UI grouping, docs links)

File Structure

Path Purpose
nodes/UZapi/credentials/uzapi.credentials.ts Define Base URL, API Token, Username, Version, PhoneID
nodes/UZapi/apiClient.ts HTTP client wrapper
nodes/UZapi/operations/*.ts Handlers for each API operation
nodes/UZapi/utils/properties.ts Parameter metadata & display options
nodes/UZapi/options/options.ts Values for Operation dropdown
nodes/UZapi/UZapi.node.json Node manifest (UI grouping, icons, docs links)

Prerequisites

  • n8n 1.45+ (self-hosted or desktop)
  • Valid UZapi account enabling WhatsApp Business Cloud API
  • Node.js ≥ 18, npm/Yarn/PNPM for local development

Installation

  1. Clone into your n8n custom nodes directory:

    git clone https://github.com/Autotic/n8n-nodes-uzapibusiness.git

  2. Install dependencies and build:

    npm install
npm run build

  3. Restart n8n → the UZapi node appears under Miscellaneous

Credential Configuration

In n8n, create new credentials of type UZapi API with these fields:

Field Description
Base URL API base URL (e.g., https://api.uzapi.com.br)
API Token Your UZapi Bearer token (masked)
Username Your UZapi username for path construction
API Version API version (e.g., v1)
Phone Number ID WhatsApp number ID for sending messages

The node will add the header:

Authorization: Bearer {{$credentials.apiToken}}

automatically to every request.

Node Parameters

Parameter Type Visible for Description
Operation options Always Which API endpoint to invoke
App Version options generateQr Version for new instance
Phone Number string generateQr Your WhatsApp number (E.164)
Authentication Method hidden generateQr Fixed to PairingCode
Auto Reject Calls boolean generateQr Reject incoming calls automatically?
Answer Missed Call string generateQr Message for missed calls
Webhook URL string generateQr Public URL to receive QR callbacks
Resources json generateQr CPU/memory settings for instance
Delay Typing number sendtext Simulate typing delay (ms)
Delay Message number sendtext Delay after typing before send (ms)
Número (com DDI) string Any send* operation Destination number (E.164)
Message Type options sendtext Select message subtype
Texto string sendtext + type text Text body
Link do arquivo string sendtext + media types Public URL or path to media
Caption, Filename, Latitude, Longitude, Location Name/Address, Contacts JSON, Template Components, Interactive Object various Specific sendtext subtypes Media-specific fields

Supported Operations

Este node usa as seguintes operações:

Operation HTTP Method & Path Description
generateQr POST /instance/add Cria ou retoma sessão e recebe callback QR
sendtext POST /{username}/{version}/{phoneId}/messages Envia todo tipo de mensagem (texto, imagem, áudio, vídeo, documento, sticker, localização, contatos, template, interativo)

Example Workflow

  1. Generate QR

    • Operation: generateQr
    • Phone Number: 5511999998888
    • Webhook URL: https://your-domain/webhook/receive-qr

  2. Send Text

    • Operation: sendtext
    • Número: 5511999998888
    • Message Type: text
    • Texto: Hello from n8n!
    • Delay Typing: 500
    • Delay Message: 200

  3. Send Image

    • Operation: sendtext
    • Message Type: image
    • Link do arquivo: https://.../image.jpg
    • Caption: Check this out!

Development & Testing

  • Build: npm run build → outputs to dist/

  • Lint: npm run lint (ESLint + Prettier)

  • Tests: run against sandbox environment

    UZAPI_BASE_URL=... UZAPI_USERNAME=... UZAPI_PHONEID=... UZAPI_APITOKEN=... npm test

Contributing

  1. Fork the repository
  2. npm install
  3. Create a feature branch
  4. Implement & test
  5. Submit a pull request referencing an issue

License

MIT © 2025 UZapi

Discussion