---
title: WhatsApp
subtitle: Understand how WhatsApp accounts, templates, inbox threads, and sends work in OrcaPulse
slug: documentation/whatsapp
---

# WhatsApp

This page documents how WhatsApp works in the current OrcaPulse project: account onboarding, approved templates, inbound webhook handling, thread-based inbox views, direct and bulk sends, and workflow-linked outbound automation.

## What this WhatsApp integration covers

WhatsApp is a dedicated channel system in the current OrcaPulse project, not only a generic message step. The codebase includes account onboarding, sender registration, template management, inbound webhook processing, message storage, and a working inbox for ongoing conversation review.

This makes WhatsApp one of the clearest examples of a channel-specific operating flow already present in the product.

## Accounts and onboarding

WhatsApp account setup is already modeled directly in the backend. Accounts track phone number, display name, sender details, status, and onboarding or reconnect logic. The product can reuse existing senders, recover pending onboarding state, and connect new numbers through a retry-safe flow.

This matters because workflow and inbox behavior depend on a real active account, not just on a text field with a number.

- Account records: WhatsApp accounts are stored with operational metadata, not only a raw sender number.
- Reconnect support: the onboarding flow can reuse or recover existing sender state where possible.
- Status-aware setup: account activation and message operations depend on the account being in a usable state.

## Templates and sending

Template handling is a major part of the current WhatsApp implementation. The project supports template creation, approval-state tracking, activation toggling, deletion, and usage counting. Approved templates can then be used for outbound sends.

Sending is available in both direct and bulk forms. The backend supports sending with an approved template or a direct session-style body, and message records are stored after send attempts.

- Approved-template path: outbound sends can use approved template IDs and content SIDs.
- Direct session messages: thread replies can also send a direct message body when allowed.
- Bulk sends: the channel already supports multi-recipient template sends.
- Usage tracking: template usage counts and last-used timestamps are updated as sends happen.

## Inbound messages and inbox flow

The WhatsApp channel already has inbound webhook handling. Incoming messages are validated, matched to the right account, normalized into conversation IDs, and then stored as message records for later inbox review.

On the front end, the WhatsApp inbox groups these records into conversations for the selected account and lets operators inspect message history for each thread.

- Webhook ingestion: inbound WhatsApp traffic becomes stored message records instead of being handled ephemerally.
- Conversation grouping: messages are organized by conversation ID, usually the normalized contact number.
- Account-scoped inbox: operators switch by WhatsApp account and then browse that account’s threads.
- Unread awareness: the inbox keeps enough state to support unread-count and read-status style workflows.

## Conversation history and control

WhatsApp threads in OrcaPulse are not just a send log. Operators can load conversation history, send from inside the thread, mark threads as read, and delete conversation records when needed. This makes WhatsApp a working inbox, not only an outbound utility.

The stored message model also preserves direction, sender, body, template usage, and account context so teams can understand how the thread evolved over time.

- Thread history: message records are sorted into readable conversation sequences.
- Direct thread send: replies can be sent from the selected conversation view itself.
- Read and delete controls: operators can clean up or manage thread state as part of daily use.
- Operational context: account, direction, and template metadata stay attached to the stored conversation.

## Workflow usage and outbound automation

WhatsApp is also a workflow action in the broader OrcaPulse system. The workflow builder supports WhatsApp steps, and those steps depend on a configured WhatsApp integration plus an approved template.

This means WhatsApp is both a channel inbox and an automation action. Teams can use it for thread-based response as well as downstream follow-up once a lead is already moving through a workflow.

- Workflow step support: WhatsApp is one of the real step types supported by the builder and execution flow.
- Template dependency: outbound workflow sends depend on the correct account and approved template being available.
- Channel plus workflow model: the same channel can support both inbox operations and structured follow-up automation.

## Next steps

After WhatsApp, the next useful channel page is usually LinkedIn, especially because the current project already includes LinkedIn lead-gen syncing and social-lead routing behavior there too.