> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting: WhatsApp Flow submissions missing, empty, or stuck in the funnel
> Diagnose a WhatsApp Flow with no submissions landing in the CDP, an empty submissions list even though the funnel shows completions, recipients who cannot open a Flow, and a dashboard panel that disagrees with the API.
# Troubleshooting: WhatsApp Flow submissions missing, empty, or stuck in the funnel
A WhatsApp Flow problem shows up one of four ways: a submitted Flow
never appears on the contact's profile, the funnel shows completions
but the submissions list stays empty, recipients receive a Flow they
cannot open, or the dashboard submissions panel and the API list
disagree. This page covers the Flow-submissions layer only. If the
problem is the Flow's runtime itself — the screen render fails, the
encrypted exchange aborts mid-Flow — the
[Flow execution failures](/troubleshooting/flow-executions-failed)
page is the right playbook; if the WABA or template is down, work
[Troubleshoot a WhatsApp connection](/troubleshooting/whatsapp-connection)
first.
Publish state, phone-number quality, and CDP routing are Meta's or
your own tenant's levers — Orbit relays the submission from Meta's
webhook and writes the row. The CDP event contract and the contact
write-back rules are in [WhatsApp channels — Flow Submissions](/channels/whatsapp#flow-submissions-write-to-the-contact-profile).
## Symptom map
Work the table top-down — it covers the failure modes that account for
nearly every Flow-submission incident.
| Symptom | Most likely cause | What to do |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Submission list rows exist, but `landed_in_cdp` stays `false`** | The contact-resolution step failed — the submitter's phone did not match a contact, or the CDP event ingestion is still in flight | Check the contact-resolution path first (next section). A `contact_id` of `null` on the row blocks the CDP mark; create the contact (or add the phone) and the next submission resolves |
| **Submissions endpoint returns empty, but the funnel shows completions** | The funnel counts screen transitions; only completed final screens write to the submissions list | Compare the funnel's final-screen step count with the list — see the funnel-vs-list section below |
| **Recipients can't open a Flow you sent** | The Flow is stuck in `DRAFT` at Meta, or the WABA phone number's quality rating blocks the send from rendering | Check the Flow's publish state in Meta Business Manager, and the WABA phone number's quality rating |
| **Dashboard submissions panel disagrees with the API for the same window** | The dashboard panel calls the same list endpoint, but its pagination (`limit`/`offset`) and default `since`/`until` window differ from your raw call | Re-issue the API call with the dashboard's filters applied, or page the API with the dashboard's `offset`. The API is the source of truth |
## Check contact resolution first
`landed_in_cdp` only flips `true` when the submission resolves to a
contact. The CDP event lives on the contact record, so a submission
arrives as a row with `contact_id: null` only when the submitter's
phone number did not match any contact in your tenant. To confirm which
side of that branch you are on, fetch one row:
```bash theme={null}
curl -G "https://api.orbit.devotel.io/api/v1/whatsapp/flows/YOUR_FLOW_ID/submissions" \
-H "X-API-Key: $ORBIT_API_KEY" \
--data-urlencode "limit=10"
```
Read `contact_id` and `landed_in_cdp` on each row:
* **`contact_id` is `null`.** The submitter's phone number did not match
any contact. Create the contact (or add the phone number to an
existing contact), then the next submission from that sender resolves
and lands in the CDP.
* **`contact_id` set, `landed_in_cdp` false.** The CDP event emission
has not finished for that submission yet. Allow for ingestion lag
(seconds to a few minutes behind live), then re-read the row. If the
lag clears and `landed_in_cdp` still shows `false`, the write failed —
the escalation payload at the bottom of this page includes the
submission id for that row.
Verify on the contact page: open the contact in the dashboard and find
the `whatsapp_flow_submitted` event in their event feed. The event
carries the raw answers payload, so a Journeys trigger on
`whatsapp_flow_submitted` fires the same as any other behavioral event.
Rows recorded before the CDP wiring shipped show
`landed_in_cdp: false` regardless of resolution. A `false` on an old
row does not mean the event write failed.
## Funnel shows completions but the list is empty
The funnel and the submissions list measure different things:
* **Funnel** — counts screen-to-screen transitions. A recipient who
reaches the final screen appears in the funnel even if they never
tapped Submit on the completion screen.
* **Submissions list** — a row appears only when a recipient completes
the final screen of the Flow.
To match the two, compare the funnel's "final screen completions" step
count with the submissions list on the same window. A funnel spike on
a specific screen with no submissions points to that screen blocking
completion (a validation error, a missing Next action, or a dropped
encrypted exchange — the
[Flow execution failures](/troubleshooting/flow-executions-failed)
page covers those).
## Recipients can't open the Flow
Three reasons account for most open failures:
1. **Publish state.** A Flow saved as `DRAFT` cannot be opened by
recipients — the WhatsApp client refuses it. Publish the Flow in
Meta Business Manager. The Flow status is visible on the Flow's
record alongside the template list.
2. **Phone-number quality.** Meta blocks sends from phone numbers with
a `RED` quality rating. If your send returned success but the
recipient cannot open the message, the WABA phone is usually the
blocker — the WABA's phone-quality rating is on the channel page
(**Settings → Channels → WhatsApp → Phone number**), and the
recovery path is in
[Troubleshoot a WhatsApp connection](/troubleshooting/whatsapp-connection#quality-pauses-two-distinct-classes).
3. **Category restrictions.** Flows in the restricted categories
(regulated goods, health, adult themes) require explicit Meta
allow-listing. Without it the send succeeds but the client refuses
to open. The category rules are in
[WhatsApp content policy](/compliance/whatsapp-content-policy).
If the send failed outright with `WHATSAPP_*` error code, the fix is
the earlier-level playbooks, not this page.
## Dashboard panel vs the API
The dashboard submissions panel on the Flow's detail page reads the
same list endpoint as the API. Divergence is a client-side effect,
not two different queries:
* **Pagination.** The panel requests a page size smaller than the API's
`limit=200` max; a raw call with a larger `limit` returns older rows
the panel has not rendered. Page the API with `offset` to mirror the
panel.
* **Window defaults.** The API defaults to the trailing 90 days for
`since`/`until`; if you pass an explicit `since`, that window
overrides the default. A call against a window the panel is not
showing will disagree with the panel either way. Match the windows
first, then compare counts.
The API `/api/v1/whatsapp/flows/{flowId}/submissions` list endpoint is
the source of truth for what persisted. If the API and the dashboard
disagree even after the windows and pagination are matched, escalate
with the request id from the response header.
## What not to do
* **Do not treat a null `contact_id` as a bug to retry.** The contact
resolution is not a blocking step; the row persists either way. Fix
the contact record so the next submission resolves.
* **Do not page past `limit=200`.** The API caps `limit` at 200. Loop
over `offset` for longer windows; large values are rejected rather
than silently truncated.
* **Do not send a `DRAFT` Flow to recipients.** Until the Flow is
published in Meta Business Manager, recipients receive a message
they cannot open. Check the publish state before a campaign.
* **Do not test a Flow on a phone-quality `RED` number.** Sends fail
silently; work the phone-quality recovery first.
## Escalation payload
If you have worked the page and a completed submission still does not
land in the CDP, email
[whatsapp-support@devotel.io](mailto:whatsapp-support@devotel.io) with
these three items so we can trace the ingestion without a back-and-forth:
1. The **Flow id** (Meta's flow id, or the dashboard URL id).
2. The **submission id** of one row stuck at `landed_in_cdp: false`.
3. The **contact resolution branch** — `contact_id` null vs set — so
we skip the resolution-angle probe and start on the event ingestion
path.
## See also
* [WhatsApp channels — Flow Submissions](/channels/whatsapp#flow-submissions-write-to-the-contact-profile) —
the submissions list fields, the `landed_in_cdp` marker, and the
custom-field write-back rules.
* [Webhook events](/reference/webhook-events) — the
`whatsapp_flow_submitted` event contract, and where Flow events sit
in the event list.
* [Flow execution failures](/troubleshooting/flow-executions-failed) —
when a Flow fails mid-run (blocked screen, dropped encrypted
exchange) before a submission even exists.
* [Troubleshoot a WhatsApp connection](/troubleshooting/whatsapp-connection) —
the publish-state and phone-quality playbooks this page defers to.
* [The CDP event model](/concepts/cdp-event-model) — how
`whatsapp_flow_submitted` on the contact drives segments and
journeys.