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

# Sending Media Messages

> Send images, videos, audio, documents, stickers, locations, and contacts via WhatsApp

Send rich media content including images, videos, audio files, documents, stickers, location information, and contact cards.

## Sending Images

```bash icon="terminal" title="Send Image" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "image",
    "media": {
      "mediaId": "media_abc123",
      "caption": "Check out this image!"
    }
  }'
```

## Sending Videos

```bash icon="terminal" title="Send Video" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "video",
    "media": {
      "mediaId": "media_xyz789",
      "caption": "Watch this video"
    }
  }'
```

## Sending Audio

```bash icon="terminal" title="Send Audio" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "audio",
    "media": {
      "mediaId": "media_audio456"
    }
  }'
```

<Note>
  Audio messages do not support captions.
</Note>

## Sending Documents

```bash icon="terminal" title="Send Document" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "document",
    "media": {
      "mediaId": "media_doc789",
      "filename": "Monthly_Report.pdf",
      "caption": "Here is your monthly report"
    }
  }'
```

## Sending Stickers

Send WebP stickers (static or animated):

```bash icon="terminal" title="Send Sticker" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "sticker",
    "sticker": {
      "mediaId": "media_sticker123"
    }
  }'
```

### Sticker Requirements

| Type     | Format | Max Size | Dimensions |
| -------- | ------ | -------- | ---------- |
| Static   | WebP   | 100 KB   | 512x512 px |
| Animated | WebP   | 500 KB   | 512x512 px |

<Warning>
  Stickers must be exactly 512x512 pixels in WebP format. Other formats or dimensions will be rejected.
</Warning>

## Sending Location

Share a location with coordinates:

```bash icon="terminal" title="Send Location" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "location",
    "location": {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "name": "Chirp HQ",
      "address": "123 Main St, San Francisco, CA"
    }
  }'
```

### Location Fields

| Field       | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `latitude`  | number | Yes      | Latitude coordinate             |
| `longitude` | number | Yes      | Longitude coordinate            |
| `name`      | string | No       | Location name (shown as title)  |
| `address`   | string | No       | Full address (shown below name) |

## Sharing Contacts

Share one or more contacts using the vCard format:

```bash icon="terminal" title="Send Contact" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "contacts",
    "contacts": {
      "contacts": [
        {
          "name": {
            "formattedName": "John Doe",
            "firstName": "John",
            "lastName": "Doe"
          },
          "phones": [
            { "phone": "+15551234567", "type": "CELL" },
            { "phone": "+15559999999", "type": "WORK" }
          ],
          "emails": [
            { "email": "john@example.com", "type": "WORK" }
          ],
          "org": {
            "company": "Acme Inc",
            "title": "Senior Engineer"
          }
        }
      ]
    }
  }'
```

### Contact Fields

| Field                | Type   | Required | Description                  |
| -------------------- | ------ | -------- | ---------------------------- |
| `name.formattedName` | string | Yes      | Full display name            |
| `name.firstName`     | string | No       | First name                   |
| `name.lastName`      | string | No       | Last name                    |
| `name.middleName`    | string | No       | Middle name                  |
| `name.prefix`        | string | No       | Name prefix (Dr., Mr., etc.) |
| `name.suffix`        | string | No       | Name suffix (Jr., III, etc.) |
| `phones`             | array  | No       | Phone numbers                |
| `emails`             | array  | No       | Email addresses              |
| `addresses`          | array  | No       | Physical addresses           |
| `org`                | object | No       | Organization information     |
| `urls`               | array  | No       | Website URLs                 |
| `birthday`           | string | No       | Birthday (YYYY-MM-DD format) |

### Phone Types

Valid phone types: `CELL`, `MAIN`, `IPHONE`, `HOME`, `WORK`

### Email/Address Types

Valid types: `HOME`, `WORK`

## Uploading Media

Before sending media, you must upload it using the Media API:

```bash icon="terminal" title="Upload Media" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/media \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -F "file=@/path/to/image.jpg"
```

```json icon="code" title="Upload Response" theme={null}
{
  "id": "media_abc123",
  "mimeType": "image/jpeg",
  "fileSize": 102400
}
```

Use the returned `id` as the `mediaId` when sending messages.

## Media Requirements

### Supported Formats

| Type     | Formats                              | Max Size                           |
| -------- | ------------------------------------ | ---------------------------------- |
| Image    | JPEG, PNG                            | 5 MB                               |
| Video    | MP4, 3GPP                            | 16 MB                              |
| Audio    | AAC, MP3, OGG, AMR                   | 16 MB                              |
| Document | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX | 100 MB                             |
| Sticker  | WebP                                 | 100 KB (static), 500 KB (animated) |

## Response

```json icon="code" title="Response" theme={null}
{
  "id": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "from": "+15551234567",
  "to": "+15559876543",
  "type": "image",
  "status": "queued",
  "timestamp": "2024-01-15T12:00:00.000Z"
}
```