WhatsApp Cloud API

Lyntaris connects your deployment to Meta WhatsApp Business Cloud API: verified webhooks, inbound messages in the on-device messaging experience, outbound sends through Meta’s Graph API, and—when enabled—automatic AI replies powered by Flowise Primary (RAG) - WhatsApp (the same Agentflow V2 pattern as Primary (RAG) - Web Text, tuned for the WhatsApp channel).

What you get

Capability Description
Webhook endpoint Meta calls your public HTTPS URL; Lyntaris forwards traffic to the local Unity client through a Cloudflare tunnel (same packaging model as Render Streaming and API tunnels).
Verification GET challenge for Meta’s webhook setup using your verify token.
Inbound messages Text, interactive replies, and common media types are normalized and shown in the DreamOS-style messaging UI (per-sender chats).
Read receipts Optional “mark as read” so senders see blue checks when the business number matches the configured Phone number ID.
Outbound send Graph API messages using your permanent access token and Phone number ID.
AI auto-reply Inbound user text can trigger a non-streaming Flowise prediction against the Primary (RAG) - WhatsApp agent flow; the assistant reply is sent back on WhatsApp automatically.

How the pieces connect

  1. Meta delivers webhooks to your Callback URL (HTTPS, publicly reachable).
  2. Cloudflared exposes a hostname such as {your-stack}-whatsapp.{your-domain} to the local webhook port on the machine running the Lyntaris Unity client.
  3. The Lyntaris client validates and parses payloads, updates the messaging UI, and—if auto-reply is enabled—calls Flowise over your existing Lyntaris / Flowise base URL (POST /api/v1/prediction/{FLOW_ID}), then sends the returned text to the user via Graph API.

Flowise holds the Primary RAG graph (retrieval, tools, orchestrator prompts). The Unity side does not call OpenAI (or other LLM vendors) directly for this path; it runs the configured Agentflow V2 prediction the same way other Lyntaris prediction integrations do. For generic prediction and auth patterns, see Embed Chat Widget & API.

Meta: what you need

  • A Meta Business account and a WhatsApp Business Account (WABA).
  • A WhatsApp Business App or Cloud API phone number attached to your app.
  • Phone number ID and a permanent System User access token with messaging permissions (from Meta Developer → your app → WhatsApp → API Setup).
  • A custom verify string you choose (must match Lyntaris configuration exactly).

Subscribe webhook fields relevant to messages (and optionally message_status) per Meta’s current dashboard.

Configure the webhook in Meta

  1. Set Callback URL to your tunnel URL including the path, for example:

    https://{your-stack}-whatsapp.{your-domain}/webhook
  2. Set Verify token to the same value you enter in Lyntaris (see below).
  3. Complete verification (Meta sends a GET; Lyntaris responds with the challenge when the token matches).

The exact hostname is produced by your Lyntaris deployment packaging (company + AI slug and public domain). In the Unity service configuration asset, the Inspector can show a copy-ready webhook URL once Platform public domain and identity fields are set.

Configure Lyntaris (service configuration)

In your active Ai Service Configuration (ScriptableObject) — the same asset that drives Docker env generation for Flowise and related services — set:

Setting (conceptual) Purpose
WhatsApp Phone number ID From Meta API Setup; used in Graph API paths.
WhatsApp access token Permanent token for Authorization: Bearer.
Webhook verify token Must match Meta’s verify token.
WhatsApp webhook port Local port the Unity listener binds to. Often auto-derived from your company slug when left at default; must match the tunnel service port in Cloudflared config.
Platform public domain Used to display the public webhook URL (no hardcoded domains in client code).

Optional, for operations or hotfixes:

Setting Purpose
WhatsApp Primary RAG flow ID If set, Lyntaris uses this Flowise flow UUID for auto-reply instead of resolving Primary (RAG) - WhatsApp from the synced catalog. Leave empty for normal operation.

If Phone number ID or access token is missing, the WhatsApp agent disables itself at startup.

Inbound messages and the messaging UI

  • Messages are grouped per sender phone number (chats in the sidebar).
  • You can open a chat by number, persist sidebar entries, and (when enabled) send from the compose field back through Graph API if the active chat looks like a phone number.
  • Notifications can surface new WhatsApp messages when configured.

Media and non-text types are mapped to short placeholder text in the thread so operators see that something arrived; fine-grained media handling may evolve with product updates.

Automatic AI replies (Primary RAG - WhatsApp)

For kiosk / Call Center (CC) style builds that include WhatsApp, Lyntaris can answer inbound user text with the Flowise agent named Primary (RAG) - WhatsApp. This is the WhatsApp-specific sibling of Primary (RAG) - Web Text on Flowise: same overall Agentflow V2 Primary RAG architecture (orchestrator prompts, retrieval, optional tools), with channel tagging so prompts and orchestrator markdown follow the WhatsApp pipeline.

Behaviour

  1. A user sends a WhatsApp message; the client receives the webhook and shows it in the UI.
  2. The WhatsApp Flowise reply bridge sends the message text to Flowise:

    POST /api/v1/prediction/{FLOW_ID} with streaming: false.
  3. The JSON response includes assistant text; the client sends that string back with Graph API send message.
  4. Conversation memory in Flowise is keyed per sender: chatId / sessionId use a stable prefix plus the sender’s digits so each WhatsApp user keeps their own thread.

The prediction request also sets overrideConfig.lyntarisPromptingPipeline to the WhatsApp pipeline key so orchestrator variables stay aligned with the seeded graph (see Flowise orchestrator / prompting docs for how pipeline folders map to $flow.* variables).

Requirements

  • Flowise must expose the Primary (RAG) - WhatsApp flow (Lyntaris primary seed on the server creates it when missing, together with Web Text and Mail variants).
  • The Unity client must sync chat-input flows from Flowise so the local catalog includes the WhatsApp pipeline (Lyntaris also syncs the watsapp pipeline alongside the scene’s main pipeline, e.g. Call Center cc).
  • Flowise needs working retrieval / vector configuration if you expect RAG answers (same operational requirements as other Primary RAG deployments).
  • API access from the Unity machine to Flowise must allow prediction calls (API key or basic auth, per your deployment).

Operations

  • Disable auto-reply on the bridge component in the scene if you only want human or flow-tool-driven replies.
  • Throttle: one in-flight prediction per sender at a time to avoid overlapping turns.
  • Console: filtered logs under the Lyntaris text-channel Flowise category help support teams separate WhatsApp prediction noise from general logs.

For SMS, a parallel bridge can use Primary (RAG) - Web Text until a dedicated SMS seed exists; see SMS and Telnyx.

Outbound from operators

When the integration option is on, text typed in the messaging compose field can be sent through the WhatsApp Cloud API for the selected chat, if the chat title resolves as a phone number—useful for human replies without leaving the Lyntaris UI.

Tunnel and security

  • The WhatsApp tunnel is a dedicated hostname (e.g. {stack}-whatsapp.{domain}) pointing at 127.0.0.1 on your webhook port, with httpHostHeader set so the local listener accepts proxied requests.
  • Tokens and IDs belong in service configuration, not in C# scripts or checked-in secrets.

Development vs production (Meta)

  • Development / test: Meta only delivers webhooks for phone numbers you add as test recipients in the app’s WhatsApp configuration.
  • Production: After app review and going live, webhooks apply to your production business number; requirements depend on Meta’s policies (business verification, etc.).

results matching ""

    No results matching ""