> ## 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.

# Kapso extensions

> Get extra fields with both REST API and TypeScript SDK

Kapso returns Meta-compatible objects by default. Opt in to extra fields using `fields=kapso(...)` on list endpoints.

Works with:

* **REST API**: Add `?fields=kapso(...)` query parameter
* **TypeScript SDK**: Pass `fields` option with helper functions or string

These extensions add valuable context like message direction, media URLs, conversation details, and more.

## Usage

### TypeScript SDK

The SDK includes helper functions for common field sets:

```ts theme={null}
import {
  buildKapsoFields,
  buildKapsoMessageFields
} from '@kapso/whatsapp-cloud-api';

// All default Kapso message fields
const page = await client.messages.query({
  phoneNumberId: '123',
  limit: 20,
  fields: buildKapsoFields()
});

// Subset of fields
const subset = await client.messages.query({
  phoneNumberId: '123',
  limit: 20,
  fields: buildKapsoMessageFields('flow_response', 'flow_token')
});

// Or use string format
const messages = await client.messages.query({
  phoneNumberId: '123',
  limit: 20,
  fields: 'kapso(default)'
});
```

### REST API

Add the `fields` query parameter:

```bash theme={null}
# All default Kapso fields
GET /v24.0/{phone_number_id}/messages?fields=kapso(default)

# Specific fields only
GET /v24.0/{phone_number_id}/messages?fields=kapso(direction,media_url,contact_name)

# Omit Kapso fields (Meta-only)
GET /v24.0/{phone_number_id}/messages?fields=kapso()
```

**Available selectors:**

* `kapso(default)` or `kapso(*)` or `kapso(all)` - All default Kapso fields
* `kapso(field1,field2,...)` - Specific fields only
* `kapso()` - Omit Kapso fields entirely

## Message fields

| Field                      | Description                                                                                   |
| -------------------------- | --------------------------------------------------------------------------------------------- |
| `direction`                | Inbound or outbound based on the business number.                                             |
| `status`                   | Server-side message status when available.                                                    |
| `processing_status`        | Internal processing status when available.                                                    |
| `phone_number`             | Business phone number for the message.                                                        |
| `has_media`                | True when a media blob is attached.                                                           |
| `media_data`               | URL, filename, content type, and byte size for stored media.                                  |
| `media_url`                | Direct URL to the attached media. Inbound: immediate. Outbound: appears shortly after send.   |
| `whatsapp_conversation_id` | Internal conversation identifier.                                                             |
| `contact_name`             | Display name when known.                                                                      |
| `message_type_data`        | Per-type hints such as caption, sticker info, or location values.                             |
| `content`                  | Original message fragment stored by Kapso (for example, entire interactive/catalog payloads). |
| `flow_response`            | Parsed Flows response JSON.                                                                   |
| `flow_token`               | Token from a Flows response when present.                                                     |
| `flow_name`                | Name from a Flows response when present.                                                      |
| `order_text`               | Optional note from order messages.                                                            |

## Conversation fields

Use these with conversations endpoint.

| Field                    | Description                                                               |
| ------------------------ | ------------------------------------------------------------------------- |
| `contact_name`           | Display name for the contact linked to the conversation.                  |
| `messages_count`         | Total number of stored messages in the conversation.                      |
| `last_message_id`        | WAMID of the most recent message in the conversation.                     |
| `last_message_type`      | Type of the most recent message (for example text, image, reaction).      |
| `last_message_timestamp` | ISO 8601 timestamp of the most recent message.                            |
| `last_message_text`      | Text or caption preview when available (may be empty for non-text types). |
| `last_inbound_at`        | ISO 8601 timestamp of the most recent inbound message.                    |
| `last_outbound_at`       | ISO 8601 timestamp of the most recent outbound message.                   |

## Examples

### All Kapso fields

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  await client.messages.query({
    phoneNumberId: '123',
    limit: 20,
    fields: buildKapsoFields()
  });
  ```

  ```bash REST API theme={null}
  GET /v24.0/123/messages?fields=kapso(default)
  ```
</CodeGroup>

### Subset of fields

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  await client.messages.query({
    phoneNumberId: '123',
    limit: 20,
    fields: 'kapso(flow_response,flow_token,media_url)'
  });
  ```

  ```bash REST API theme={null}
  GET /v24.0/123/messages?fields=kapso(flow_response,flow_token,media_url)
  ```
</CodeGroup>

### Omit Kapso fields

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  await client.messages.query({
    phoneNumberId: '123',
    limit: 20,
    fields: 'kapso()'
  });
  ```

  ```bash REST API theme={null}
  GET /v24.0/123/messages?fields=kapso()
  ```
</CodeGroup>

## Webhooks

The SDK includes a normalization helper for Meta webhooks. It returns the same structure as history queries and sets `kapso.direction`. SMB echoes are tagged with `kapso.source = "smb_message_echo"`. Other webhook fields are available under `events.raw.<fieldName>`.

```ts theme={null}
import { normalizeWebhook, verifySignature } from '@kapso/whatsapp-cloud-api/server';

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySignature({
    appSecret: process.env.META_APP_SECRET!,
    rawBody: req.body,
    signatureHeader: req.headers['x-hub-signature-256'] as string
  })) return res.status(401).end();

  const events = normalizeWebhook(JSON.parse(req.body.toString('utf8')));
  events.messages.forEach(m => console.log(m.type, m.kapso?.direction));
  res.sendStatus(200);
});
```