WhatsApp Integration with Baileys: Kantuta POS Guide

Kantuta POS Backend includes a built-in WhatsApp gateway powered by @whiskeysockets/baileys — an open-source, reverse-engineered WhatsApp Web API. This means no paid WhatsApp Business API subscription is required. Instead, you link a real WhatsApp number to the server by scanning a QR code once, and the backend then gains the ability to send text messages, images, and documents programmatically to any WhatsApp contact or group. The linked session is persisted on disk, so subsequent server restarts reconnect automatically without re-scanning.

This integration uses the unofficial WhatsApp Web protocol. Using it for bulk or unsolicited messaging violates WhatsApp’s Terms of Service and may result in your number being temporarily or permanently banned. Use it responsibly — only send messages to customers who have opted in and expect communications from your business.

Setup & QR Code Linking

Start the NestJS Server

The WhatsApp Baileys session initializes automatically when the application boots. No additional configuration is needed beyond having the module registered in AppModule.

npm run start:dev
# or in production
npm run start:prod

Watch the server logs — Baileys will emit a QR code string within a few seconds of startup if no saved session is found.

Retrieve the QR Code

Navigate to the QR view endpoint in your browser (or call it programmatically):Browser-friendly HTML page:

GET /whatsapp/connect/view

Open http://localhost:3000/api/whatsapp/connect/view in a browser. The server renders an HTML page with a scannable QR image.JSON API endpoint (for frontend integration):

GET /whatsapp/connect

Returns JSON with a qrBase64 field (a data:image/png;base64,... string) that you can render in an <img> tag, or a success message if already connected:

{
  "success": true,
  "qrBase64": "data:image/png;base64,iVBORw0KGg..."
}

If already linked:

{
  "success": true,
  "message": "WhatsApp ya está vinculado o el código se está generando de fondo..."
}

Scan with WhatsApp on Your Phone

Open WhatsApp on your phone.
Go to Settings → Linked Devices → Link a Device.
Point your camera at the QR code displayed by the server.
Wait for the pairing confirmation — typically 2–5 seconds.

Once linked, the server logs will confirm the connection and Baileys will persist the session credentials to disk.

Session Persistence on Restart

Baileys saves the authenticated session to a local directory (e.g., ./baileys_auth_info). On subsequent server restarts, the session is restored from disk automatically — no re-scanning required unless the session expires or you unlink the device from WhatsApp.

Sending Messages

All /whatsapp/send* routes are decorated with @Public() — they do not require a JWT Bearer token. Protect access to these endpoints at the network or API-gateway level in production environments.

Send a Text Message

POST /whatsapp/send

Request body:

{
  "code": "591",
  "phone": "71234567",
  "message": "Hola! Tu pedido #45 está listo para recoger."
}

Field	Type	Required	Description
`code`	`string`	✅	Country code, digits only, 2–3 characters (e.g., `591` for Bolivia)
`phone`	`string`	✅	Local phone number, digits only, 8–15 characters (e.g., `71234567`)
`message`	`string`	✅	Text content of the message

The backend concatenates code + phone internally to form the full WhatsApp JID: [email protected]. Never include the + prefix or spaces in either field.

cURL example:

curl -X POST https://api.example.com/whatsapp/send \
  -H "Content-Type: application/json" \
  -d '{
    "code": "591",
    "phone": "71234567",
    "message": "Hola! Tu pedido #45 está listo para recoger."
  }'

Response (200 OK):

{
  "success": true,
  "message": "Mensaje enviado con éxito",
  "data": { ... }
}

Send an Image

POST /whatsapp/send-image

Upload an image file as multipart/form-data. Maximum file size: 5 MB. Form fields:

Field	Type	Required	Description
`code`	`string`	✅	Country code (digits only, 2–3 chars)
`phone`	`string`	✅	Local phone number (digits only, 8–15 chars)
`caption`	`string`	Optional	Caption text displayed below the image
`file`	`binary`	✅	Image file (`.jpg`, `.png`, etc.) — max 5 MB

cURL example:

curl -X POST https://api.example.com/whatsapp/send-image \
  -F "code=591" \
  -F "phone=71234567" \
  -F "caption=Catálogo de productos - Junio 2025" \
  -F "file=@/path/to/catalogo.jpg"

Send a Document

POST /whatsapp/send-document

Upload any file type (PDF, DOCX, ZIP, etc.) as multipart/form-data. Maximum file size: 15 MB. Form fields:

Field	Type	Required	Description
`code`	`string`	✅	Country code (digits only, 2–3 chars)
`phone`	`string`	✅	Local phone number (digits only, 8–15 chars)
`fileName`	`string`	Optional	Display name for the file (e.g., `Factura_Mayo.pdf`). Defaults to the original filename
`file`	`binary`	✅	Document file — max 15 MB

cURL example:

curl -X POST https://api.example.com/whatsapp/send-document \
  -F "code=591" \
  -F "phone=71234567" \
  -F "fileName=Factura_Junio_2025.pdf" \
  -F "file=@/path/to/factura.pdf"

Group Messaging

Send a Message to a Group

POST /whatsapp/send-to-group

Send a text message to a WhatsApp group using its JID. Both fields are required. Request body:

{
  "groupId": "[email protected]",
  "message": "Estimados clientes, el negocio estará cerrado el lunes 2 de junio por feriado."
}

Field	Type	Required	Description
`groupId`	`string`	✅	Full WhatsApp group JID ending in `@g.us`
`message`	`string`	✅	Message text to broadcast

cURL example:

curl -X POST https://api.example.com/whatsapp/send-to-group \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "[email protected]",
    "message": "Estimados clientes, el negocio estará cerrado el lunes 2 de junio por feriado."
  }'

Response (200 OK):

{
  "success": true,
  "message": "Comunicado enviado al grupo con éxito",
  "data": { ... }
}

List All Groups

GET /whatsapp/list-groups

Returns the name and JID of every group the linked WhatsApp number belongs to.

curl -X GET https://api.example.com/whatsapp/list-groups

Response:

{
  "success": true,
  "data": [
    { "id": "[email protected]", "name": "Clientes VIP Kantuta" },
    { "id": "[email protected]", "name": "Equipo de Ventas" }
  ]
}

Use GET /whatsapp/list-groups when setting up group broadcast automations — copy the id field and store it as your groupId for POST /whatsapp/send-to-group. Group JIDs never change even if the group name is updated.

Phone Number Format

Kantuta POS uses a two-field format for phone numbers — code (country code) and phone (local number) — and concatenates them server-side:

code + phone → internal JID
"591" + "71234567" → "[email protected]"

Country	`code`	`phone` example
Bolivia	`591`	`71234567`
Perú	`51`	`987654321`
Argentina	`54`	`1123456789`
México	`52`	`5512345678`

Rules:

Both code and phone must contain digits only — no +, spaces, or dashes.
code must be 2–3 digits.
phone must be 8–15 digits.

Endpoint Reference

Method	Endpoint	Auth	Description
`GET`	`/whatsapp/connect/view`	Public	HTML page with QR code
`GET`	`/whatsapp/connect`	JWT	JSON QR code or connection status
`POST`	`/whatsapp/send`	Public	Send a text message
`POST`	`/whatsapp/send-image`	Public	Send an image (max 5 MB)
`POST`	`/whatsapp/send-document`	Public	Send a document (max 15 MB)
`POST`	`/whatsapp/send-to-group`	Public	Broadcast text to a group
`GET`	`/whatsapp/list-groups`	Public	List all groups the bot is in
`GET`	`/whatsapp/view`	Public	Browser-based send form (debug UI)

Get Started

Core Concepts

Guides

Deployment

WhatsApp Integration with Baileys: Kantuta POS Guide

Setup & QR Code Linking

Sending Messages

Send a Text Message

Send an Image

Send a Document

Group Messaging

Send a Message to a Group

List All Groups

Phone Number Format

Endpoint Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Deployment

Documentation Index

​Setup & QR Code Linking

​Sending Messages

​Send a Text Message

​Send an Image

​Send a Document

​Group Messaging

​Send a Message to a Group

​List All Groups

​Phone Number Format

​Endpoint Reference

Build docs developers (and LLMs) love

Setup & QR Code Linking

Sending Messages

Send a Text Message

Send an Image

Send a Document

Group Messaging

Send a Message to a Group

List All Groups

Phone Number Format

Endpoint Reference