> ## 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/event-types#messagereceived), [`message.status_updated`](/docs/platform/webhooks/event-types#messagestatusupdated)
* Platform API: [PATCH /conversations/:id](/api/platform/v1/update-conversation) (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/event-types#messagereceived), [`message.status_updated`](/docs/platform/webhooks/event-types#messagestatusupdated)
* WhatsApp API: [GET /{phone_number_id}/message\_history](/api/meta/whatsapp/get-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/retrieve-media-url) (get download URL), then fetch the URL to download
* Platform API: [POST /media](/api/platform/v1/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/event-types#messagereceived) 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/list-broadcasts), [GET /whatsapp/broadcasts/{id}](/api/platform/v1/get-broadcast), [GET /whatsapp/broadcasts/{id}/recipients](/api/platform/v1/list-broadcast-recipients)