WhatsApp Smart Assistant — Setup Guide

What it does

WhatsApp Smart Assistant turns your WhatsApp inbox into an AI-powered sales agent.

It answers customer questions in Arabic or English using your actual business knowledge

(menu, prices, FAQs, policies), scores every lead automatically, and alerts you on

Telegram the moment a hot lead appears or a customer needs a human. When it isn't

confident enough to reply, it routes straight to you instead of guessing.

Capabilities at a glance:

• Handles text, voice (Gemini transcription), image, and document messages
• Searches your business knowledge base (RAG) for accurate product/price answers
• Detects buying intent and scores every lead 0–10
• Sends Telegram notifications for hot leads, new conversations, and handoff requests
• Tags contacts automatically (hot_lead, warm_lead, cold_lead, handoff)
• Fetches conversation history from nashir.ai — zero database setup required

---

What you need

> No WhatsApp token needed. Media (voice notes, images, documents) is fetched

> through nashir.ai/api/v1/media/:id using your Nashir API credential. nashir.ai

> handles the Meta auth server-side, so you never have to copy a Meta System User

> token into n8n.

---

5-Minute Setup

Step 1 — Install the nashir.ai n8n package

In your n8n instance:

Settings → Community Nodes → Install

Enter package name: n8n-nodes-nashir

This template requires v0.3.1 or higher (introduces the Telegram Send

Notification operation used by the Handoff Alert node). If you already have

the package installed on an older version:

• n8n UI → Settings → Community Nodes
• Find n8n-nodes-nashir → click Update
• Restart n8n if prompted

Step 2 — Import the workflow

Workflows → Import from file → select whatsapp-smart-assistant.json

Step 3 — Customize the AI personality

There is no separate "config" node — every value lives at the place it's

actually used.

#### Business personality and AI behaviour

Open the AI Agent node. The system prompt is plain English with editable

placeholders:

• Replace [Your Business Name] with your real business name
• Replace [describe your business...] with your category (restaurant, clinic,

boutique, online store, etc.)

• Adjust the tone instructions (warm, professional, casual)
• Modify the business-hours line to match yours
• Add or remove buying-intent keywords if your industry uses different terms

The conversation history is injected automatically — don't remove the

${$json.conversation_context …} line.

#### Handoff sensitivity

Open the Confidence Gate node. The default threshold is 0.6 — the AI

escalates to a human when its confidence drops below this.

• Lower to 0.4 if you want the AI to handle more questions itself
• Raise to 0.8 if you want it to escalate more often

#### Buying-intent keyword detection

Open the Keyword Detection node. The Arabic and English keyword lists are

hardcoded JS arrays at the top of the jsCode — edit them in place to match

your industry vocabulary. The match feeds the lead-tagging logic at the end of

the workflow.

#### Handoff acknowledgement message

Open the Send Handoff Acknowledgment node. The bilingual default is

inlined directly in the Content field — edit the text to change what the

customer sees while the team is alerted.

Step 4 — Connect credentials

You need four credential sets:

Nashir API

1. In n8n: Credentials → New → search "Nashir API"
2. Paste your API key from nashir.ai → Settings → API
3. Assign to: all nodes labelled "Nashir", and also to Download Voice Note,

Download Image, and Download Document (the HTTP Request nodes use the same

Nashir API credential to call the media proxy).

OpenAI

1. Credentials → New → OpenAI
2. Paste your OpenAI API key
3. Assign to: OpenAI Chat Model, Lead Scoring, OpenAI Embeddings

Gemini (Query Auth)

1. Credentials → New → Query Auth
2. Name: "Gemini API Key"; parameter name: key; value: your Google AI Studio API key
3. Assign to: Gemini Voice Transcribe, Gemini Vision, Gemini Document

Supabase

1. Credentials → New → Supabase
2. Enter your Supabase project URL and service role key
3. Assign to: Supabase Vector Store

Step 5 — Upload your knowledge base

Go to nashir.ai/knowledge-base and upload your business content for this

business — PDF, DOCX, XLSX, or TXT. The workflow reads from your KB

automatically on every customer message; no database setup on your end.

What to upload:

• Product or menu list with prices
• Service descriptions
• Business location and hours
• FAQ document
• Return / refund policy
• Delivery zones and fees

Per-file cap: 5 MB. Plan-tier storage ceilings: Free 5 MB · Base 10 MB · Plus 25 MB.

Step 6 — Select WhatsApp account

Open the Send WhatsApp Reply node and select your WhatsApp account from the

Account dropdown. This requires at least one connected WhatsApp account in nashir.ai.

Step 7 — Configure webhook forwarding

1. Click the Webhook node and copy the Production URL
2. In nashir.ai: Settings → Integrations → Webhooks
3. Click Add Webhook
4. Paste the URL
5. Enable event: message.received
6. Save

Step 8 — Activate

Toggle the workflow to Active in the top-right corner.

---

Configuring Telegram handoff alerts

When the AI decides a conversation needs human help, the workflow sends a

Telegram alert. The alert fires only on the handoff branch — you won't be

paged for normal AI replies.

1. Connect your Telegram to nashir.ai (one-time):

- Go to nashir.ai → Social Accounts → Connect Telegram

- Follow the bot-setup flow (nashir handles the BotFather + chat-id discovery)

- Connect a personal DM, group, or channel — wherever you want alerts to land

1. In the imported workflow:

- Open the Telegram Handoff Alert node

- Select your Nashir API credential

- Pick your connected Telegram account from the Account dropdown

- Save

1. Test:

- Send "I want to talk to a human" to your WhatsApp number

- You'll get a Telegram alert on the connected account

- The AI auto-pauses for that contact for 1 hour

How the pause works

• Confidence Gate routes to handoff → Pause AI (1h) calls

POST /api/v1/ai/pause with duration_seconds: 3600

• Every new customer or agent message during the paused window slides

ai_auto_resume_at forward to NOW + 2 h, so the AI never barges back

in mid-conversation

• After 2 h of silence the pause expires and the AI takes over again
• You can also manually pause/resume any conversation via

POST /api/v1/conversations/:phone/ai-toggle

---

Credentials Summary

---

How the flow works

Webhook (POST /smart-business-assistant)
  └─ Filter Event — only process message.received events
            └─ Get AI Status — check if AI is enabled for this contact
                 └─ Check AI Enabled — stop if AI is paused for this conversation
                      └─ Switch Media Type
                           ├─ text      → Text Pass-through (set message_content)
                           ├─ audio     → Download Voice Note → Gemini Voice Transcribe
                           ├─ image     → Download Image → Gemini Vision (describe + OCR)
                           ├─ document  → Download Document → Gemini Document (extract text)
                           └─ other     → pass through
                                └─ Merge (reconverge all branches)
                                     └─ Get Conversation History (last 20 messages)
                                          └─ Format History (consolidate all data)
                                               └─ AI Agent (GPT-4o-mini + RAG tool)
                                                    └─ Parse AI Response
                                                         └─ Confidence Gate
                                                              ├─ TRUE (low confidence / needs human)
                                                              │    └─ Lead Scoring ──┐
                                                              └─ FALSE (confident)   │
                                                                   ├─ Send WhatsApp  │
                                                                   └─ Lead Scoring ──┤
                                                                                     └─ Keyword Detection
                                                                                          └─ Notification and Telegram
                                                                                               └─ Tag Contact

---

Voice/Image/Document handling

How media downloads work

All three media branches share the same two-step pattern:

Switch Media Type ──┬─ audio    → Download Voice Note → Gemini Voice Transcribe
                    ├─ image    → Download Image      → Gemini Vision
                    └─ document → Download Document   → Gemini Document

The Download * nodes are HTTP Request nodes that hit

https://nashir.ai/api/v1/media/{{ media_id }} using your Nashir API

credential (predefinedCredentialType: nashirApi). nashir.ai resolves the

Meta media id to a short-lived URL, downloads the binary using your stored

WhatsApp access token, and streams it back to n8n. You don't need to manage

Meta tokens in n8n at all.

Each Download node exposes the binary on the data property. The matching

Gemini node then sends it as base64 via inline_data.data = {{ $binary.data.data }}.

Voice messages (Gemini)

Voice notes are tagged media_type: audio by Meta. Gemini Voice Transcribe

sends the ogg/opus binary to gemini-2.5-flash:generateContent and returns the

transcription at candidates[0].content.parts[0].text — Format History picks

this up via its merge-data fallback chain. Arabic and English are handled

natively, no post-processing needed.

Image messages (Gemini Vision)

Download Image fetches the JPEG; Gemini Vision describes the image and

extracts visible text. Same Gemini API key as voice/document.

Document messages (Gemini Document)

Download Document fetches the PDF; Gemini Document extracts and summarizes

the text content.

---

Customization ideas

Change AI model: In the OpenAI Chat Model sub-node, swap gpt-4o-mini for

gpt-4o for higher accuracy, or change to a different provider (Claude, Gemini)

by replacing the Chat Model sub-node.

Adjust confidence threshold: Increase HUMAN_HANDOFF_THRESHOLD (e.g. to 0.8)

for more aggressive human routing. Decrease it (e.g. to 0.4) to let the AI handle more.

Add more tools: Connect additional Tool sub-nodes to the AI Agent:

• Calculator tool for price calculations
• HTTP Request tool for live inventory lookups
• Code tool for date/availability checks

Multi-language support: The system prompt detects language automatically. Add

a language-specific greeting by modifying the system message in the AI Agent node.

Business hours enforcement: The system prompt already includes business hours.

To hard-block after-hours replies, add an If node before the AI Agent that checks

the current time against BUSINESS_HOURS_START/END.

Replace OpenAI with Claude: Replace the OpenAI Chat Model sub-node with

@n8n/n8n-nodes-langchain.lmChatAnthropic using claude-haiku-4-5 for fast replies.

---

Troubleshooting

Webhook not receiving messages

• Confirm the workflow is Active (not just saved)
• Check nashir.ai → Settings → Webhooks → last delivery status
• Test manually: curl -X POST YOUR_WEBHOOK_URL -H "Content-Type: application/json" -d '{"event":"message.received","data":{"phone":"+1234567890","content":"Hello","media_type":"text"}}'

AI replies are empty or garbled

• Check OpenAI credential is assigned to the OpenAI Chat Model node
• Verify the Format History node output has message_content populated
• Check n8n execution logs for the AI Agent node

Knowledge base returning no results

• Confirm you've uploaded content at nashir.ai/knowledge-base for the right business
• Confirm OpenAI Embeddings credential is assigned to the AI Agent's tool node
• Verify the Supabase credential uses the service role key (not anon key)

Telegram notifications not sending

• Open the Telegram Handoff Alert node and confirm a Nashir API credential is selected
• Confirm an Account is picked from the dropdown (your nashir.ai-connected Telegram chat)
• Check n8n execution logs for the Telegram Handoff Alert node — Telegram errors are logged

AI always routes to human (needs_human: true)

• Open the Confidence Gate node and lower the threshold from 0.6 (try 0.4 or 0.5)
• Add more content at nashir.ai/knowledge-base
• Check that the AI Agent's Supabase Vector Store credential is connected

Voice/image/document not processed

• Confirm the Download node (Voice Note / Image / Document) has the Nashir API

credential attached. The HTTP Request nodes use predefinedCredentialType: nashirApi.

• Confirm the matching Gemini node has the Gemini API key query-auth credential.
• Check that body.data.media_id is present in the webhook payload — if it's null,

nashir didn't extract it from Meta's webhook (check backend logs for

[webhook] WA media:).

• 502 from /api/v1/media/:id usually means Meta's token on the social_accounts row

is expired — refresh by reconnecting the WhatsApp account in nashir.ai.

---

Environment checklist before go-live

• [ ] BUSINESS_NAME set correctly
• [ ] TELEGRAM_BOT_TOKEN and CHAT_ID tested (send /start to your bot first)
• [ ] Knowledge base populated at nashir.ai/knowledge-base (at least 5 items recommended)
• [ ] WhatsApp account selected in Send WhatsApp Reply node
• [ ] All three credentials assigned and tested
• [ ] Webhook URL added in nashir.ai and event enabled
• [ ] Tested with a real WhatsApp message before going live

---

*Template version 1.0 — nashir.ai WhatsApp Smart Assistant*

*n8n-nodes-nashir v0.3.0+ required*