B Blengi docs
/

Run your workspace

WhatsApp notifications

WhatsApp notifications deliver the moments that matter — a new lead, a visitor asking for a human, a new conversation, or a widget error — straight to your team's phones over WhatsApp, powered by Telnyx. They sit alongside email and Web Push: each operator opts in with their own number.

Every message is a pre-approved template
WhatsApp only lets a business message you outside a 24-hour reply window using a Meta-approved template (never free text). So each trigger maps to a UTILITY template that Meta reviews once (≈24–48h). Until they're approved, the channel stays silent.

What triggers a WhatsApp message

  • New lead captured — to every workspace owner/admin. Low volume, high value.
  • Human handoff requested — to operators available for live chat. Time-critical.
  • New conversation — the first message of a new conversation. High volume — see the cost note below.
  • Widget / system error — to super_admins when the Widget Monitor records an error-severity event.
WhatsApp bills per conversation
WhatsApp charges per 24-hour conversation. New-lead, handoff and widget-error are low volume — fine. New-conversation fires on every first message, so enabling it workspace-wide can run up the Telnyx bill. It's gated behind the same per-user opt-in so turning it on is always a deliberate choice.

One-time setup

  1. Telnyx API key — Telnyx Portal → Keys & Credentials → API Keys. Copy the KEY… value.
  2. Connect WhatsApp — Telnyx Portal → Messaging → WhatsApp → Embedded Signup. Connect your Meta Business account, verify the sender number, and complete the business profile + display name (required before templates).
  3. Link the sender to a messaging profile — Telnyx Portal → Messaging Suite → WhatsApp Messaging → Manage Numbers. Assign your WhatsApp sender to a messaging profile. This is required for API sending: a sender that is "Connected" but unlinked is rejected with [10004] Invalid source number.
  4. Save credentials — in Pitchbar, go to Settings → System → WhatsApp (Telnyx) and paste the API key, the sender number (E.164), and the WABA ID. The key is encrypted at rest; only a "set" indicator is ever sent back to the browser.
  5. Submit templates — click Submit templates for review in the WhatsApp section (no shell needed). It submits one template per trigger × the languages your staff use, then records those languages. Developers can also run the command below.
  6. View templates — click View templates beside Submit to read the exact content that gets submitted (each trigger's body + button, per language) and its live Meta approval status (approved / pending / rejected) without leaving the page. If the credentials can't reach Telnyx, the panel still shows the template content and notes that the status is unavailable.
  7. Enable — once Meta approves (the View templates panel shows approved), flip on Enable WhatsApp delivery in System Settings.
  8. Operators opt in — each team member adds their number and toggles delivery on under Profile → Notifications. It's off by default — nobody is enrolled automatically.
php artisan pitchbar:whatsapp-templates              # discover staff locales + submit
php artisan pitchbar:whatsapp-templates --locales=nl,en
php artisan pitchbar:whatsapp-templates --list       # check Meta approval status
php artisan pitchbar:whatsapp-test --email=ops@acme.com

Languages

Each operator receives the template in their own interface language when one has been submitted for it, falling back to the install's default language otherwise. The template command discovers the distinct locales of your staff (or takes an explicit --locales list) and submits exactly those — so you don't file a separate Meta review for languages nobody uses.

Off the visitor hot path
Every WhatsApp message is sent from a queued job (the analytics queue), never from inside the live SSE stream — a notification never slows a visitor's reply.

Testing

Use the Send test button in the System Settings WhatsApp section (any number) or in Profile → Notifications (your own saved number). Both report the real Telnyx result — an accepted send, or a rejection with the reason — rather than a misleading "sent". The pitchbar:whatsapp-test command does the same from the CLI. The reason now carries Telnyx's error code and the exact field it rejected (e.g. [10004] Invalid source number (field: from)), and a failed template lookup reports the real error instead of a misleading "no templates found".

Troubleshooting

[10004] Invalid source number on send
The WhatsApp sender (E.164) is rejected as a valid message source even though the portal shows it Connected. Two distinct things must both be true, and "Connected" only covers the first:
  1. Meta has approved the sender — the templates are Approved (not pending), the sender has an approved Display Name, and the business profile is verified.
  2. The WhatsApp sender is linked to a Telnyx messaging profile. Unlike what you might expect, a WhatsApp sender used for API sending must be assigned to a messaging profile so Telnyx can resolve it from the from field. Do it in the Telnyx portal under Messaging Suite → WhatsApp Messaging → Manage Numbers (portal.telnyx.com/#/messaging/whatsapp/manage-numbers): confirm your sender is listed and explicitly assigned to your WhatsApp messaging profile, then re-test.
WhatsApp senders live on that Manage Numbers screen, not under My Numbers (standard phone inventory). If the sender is Connected but the portal exposes no control to attach the profile, ask Telnyx support to link it on their backend.
Templates rejected on submit
Open View templates and the Telnyx portal's Message Templates screen — it shows Meta's specific rejection reason per template (category, formatting, or variable placement). Fix and re-submit.