> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp data

> What data Kapso stores and how to access it

## Overview

| Data             | Dashboard | Webhooks | WhatsApp API            | Platform API      |
| ---------------- | --------- | -------- | ----------------------- | ----------------- |
| Conversations    | Yes       | Yes      | -                       | Yes (status only) |
| Messages         | Yes       | Yes      | Yes (delivery status)   | -                 |
| Media            | Yes       | Yes      | Yes (retrieve/download) | Yes (upload)      |
| Contacts         | Yes       | -        | -                       | -                 |
| Calls            | Yes       | Yes      | -                       | -                 |
| Referrals (CTWA) | Yes       | Yes      | -                       | -                 |
| Broadcasts       | Yes       | -        | -                       | Yes (list/get)    |

## Identity fields

WhatsApp identity is no longer phone-only.

Kapso can now store and expose:

* `wa_id` or `phone_number`
* `business_scoped_user_id`
* `parent_business_scoped_user_id`
* `username`

Depending on the payload and rollout stage, phone-based fields can be `null` while BSUID fields are present.

For migration details:

* [Business-scoped user IDs](/docs/whatsapp/business-scoped-user-ids)

## Conversations

**Fields**: phone\_number, business\_scoped\_user\_id, parent\_business\_scoped\_user\_id, username, status (active/ended), last\_active\_at, metadata, assignee

**Access**:

* Dashboard: WhatsApp > Data > Conversations
* Webhooks: [`message.received`](/docs/platform/webhooks/message-events#whatsappmessagereceived), [`message.status_updated`](/docs/platform/webhooks/message-events#status-history)
* Platform API: [PATCH /conversations/:id](/api/platform/v1/conversations/update-conversation-status) (close/reopen)

## Messages

**Fields**: content, message\_type, direction (inbound/outbound), status (pending/sent/delivered/read/failed), metadata, additive identity fields on the message payload (`business_scoped_user_id`, `parent_business_scoped_user_id`, `username` or Meta-style `from_user_id` / `to_user_id`)

**Message types**: text, image, video, audio, document, location, interactive, template, reaction, contacts

**Access**:

* Dashboard: WhatsApp > Data > Messages
* Webhooks: [`message.received`](/docs/platform/webhooks/message-events#whatsappmessagereceived), [`message.status_updated`](/docs/platform/webhooks/message-events#status-history)
* WhatsApp API: `GET /{phone_number_id}/message_history` (delivery status only, not content)

## Media

**Stored**: File attachments on messages (images, videos, audio, documents)

**Audio transcripts**: Automatic transcription with provider info, detected language, and duration

**Access**:

* Dashboard: WhatsApp > Data > Media
* WhatsApp API: [GET /{media_id}](/api/meta/whatsapp/media/get-media-url) (get download URL), then fetch the URL to download
* Platform API: [POST /media](/api/platform/v1/media/upload-media) (upload files for sending)

## Contacts

**Fields**: wa\_id, business\_scoped\_user\_id, parent\_business\_scoped\_user\_id, username, profile\_name, display\_name, metadata, notes

**Access**:

* Dashboard: WhatsApp > Data > Contacts

## Calls

**Fields**: call\_id, direction (incoming/outgoing), status (ringing/accepted/missed/declined/ended), duration\_seconds, started\_at, ended\_at, user\_wa\_id, business\_scoped\_user\_id, parent\_business\_scoped\_user\_id, username

**Access**:

* Dashboard: WhatsApp > Data > Calls
* Webhooks: Delivered via WhatsApp call events

## Referrals (CTWA)

Click-to-WhatsApp ad data captured when users message from Meta ads.

**Fields**: source\_type (ad/post/organic), source\_id, source\_url, ctwa\_clid, headline, body, media\_type

**Access**:

* Dashboard: WhatsApp > Data > Ads (CTWA)
* Webhooks: Included in [`message.received`](/docs/platform/webhooks/message-events#whatsappmessagereceived) payload when present

## Broadcasts

**Fields**: name, template, status (draft/sending/completed/failed), recipient counts, delivery stats

**Access**:

* Dashboard: WhatsApp > Outbound > Broadcasts
* Platform API: [GET /whatsapp/broadcasts](/api/platform/v1/broadcasts/list-broadcasts), [GET /whatsapp/broadcasts/{id}](/api/platform/v1/broadcasts/get-broadcast), [GET /whatsapp/broadcasts/{id}/recipients](/api/platform/v1/broadcasts/list-recipients)

## Retention

**Default**: Everything above is kept indefinitely.

**Retention window**: Paid projects can set one in Project settings > Message retention — 30 days, 90 days, 6 months, 12 months, or a custom number of days. Free projects keep everything.

**Deleted**: Ended conversations whose last activity is older than the window, along with their messages, media, audio transcripts, referrals, flow executions, webhook deliveries, broadcast recipient rows, and the project events recorded against them. Agent execution transcripts go once nothing else references them. Messages that never belonged to a conversation are deleted on the same window, measured from when they were created.

**Kept**: Contacts, broadcasts and their delivery counts, and template statistics. Calls are unlinked from a deleted conversation but not deleted themselves. Project events that are not tied to a deleted conversation follow the retention window from your plan, not this one.

**Message logs**: The searchable log of messages is kept for 30 days, or for your retention window if that window is shorter. Deleting a conversation removes its log entries at the same time.

**Applying a change**: Shortening a window takes effect after 48 hours, and project owners are emailed when it is scheduled. Lengthening it, or going back to keeping everything, applies immediately.

Deleted conversations cannot be recovered.