> For the complete documentation index, see [llms.txt](https://docs.lipachat.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lipachat.com/api/sending-media.md).

# Sending Media

🔒 WhatsApp 24-Hour Session Rule

> Before sending media, make sure the WhatsApp session with the user is **active**.
>
> **If the user has not messaged your business within the last 24 hours, WhatsApp requires the first message to be a *****template message***.
>
> After the customer replies, the 24-hour session opens and you may send media messages using this API.\
> **For sandbox testing**, send your join code to the sandbox number to activate your session.\
> [Learn more](https://app.gitbook.com/o/rJyj7TfON4zeW56KoQjM/s/2JHt6V4YwZLX6ZUdLqMy/~/changes/87/guides/joincodes)

<mark style="color:green;">`POST`</mark> <https://gateway.lipachat.com/api/v1/whatsapp/media>

This API enables users to send Images, Videos, or Audio.

**Headers**

| Name         | Value                                                                           |
| ------------ | ------------------------------------------------------------------------------- |
| Content-Type | `application/json`                                                              |
| apiKey       | Get apiKey from App portal settings tab <https://app.lipachat.com/app/settings> |

**Body**

| Name      | Type   | Description                                                                                                        |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| messageId | string | A unique identifier for the message. This will be used to track the message status and for deduplication purposes. |
| mediaType | string | Pass value as IMAGE, VIDEO, AUDIO, DOCUMENT or STICKER                                                             |
| mediaUrl  | string | URL of an image to be sent. Must be a valid URL starting with https\://...                                         |
| caption   | string | Media caption. Optional.                                                                                           |
| filename  | string | Optional, applies to Document.                                                                                     |
| from      | string | Sandbox number +254110090747 or your own WABA phone number.                                                        |
| to        | string | Receiver phone number. It should start with a country code.                                                        |

{% tabs %}
{% tab title="Curl" %}

```sh
curl --location 'https://gateway.lipachat.com/api/v1/whatsapp/media' \
--header 'apiKey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "messageId": "5d3f62c3-eb8f-4150-8941-bdceb0f429bb",
    "to": "254XXXXX",
    "from": "254110090747",
    "mediaType": "IMAGE",
    "mediaUrl": "https://picsum.photos/id/237/200/300",
    "caption": ""
}'
```

{% endtab %}

{% tab title="Java" %}

```java
// Create an instance of OkHttpClient
OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

// Define the media type for the request
MediaType mediaType = MediaType.parse("application/json");

// Create the request body with the necessary JSON payload using a text block
RequestBody body = RequestBody.create(mediaType, """
{
    "messageId": "5d3f62c3-eb8f-4150-8941-bdceb0f429bb",
    "to": "254XXXXX",
    "from": "254110090747",
    "mediaType": "IMAGE",
    "mediaUrl": "https://picsum.photos/id/237/200/300",
    "caption": ""
}
""");

// Build the request with the required headers
Request request = new Request.Builder()
    .url("https://gateway.lipachat.com/api/v1/whatsapp/media")
    .method("POST", body)
    .addHeader("apiKey", "YOUR_API_KEY")
    .addHeader("Content-Type", "application/json")
    .build();

// Execute the request and get the response
Response response = client.newCall(request).execute();

```

{% endtab %}

{% tab title="Javascript" %}

```ruby
const axios = require('axios');
let data = JSON.stringify({
    "messageId": "5d3f62c3-eb8f-4150-8941-bdceb0f429bb",
    "to": "254XXXXX",
    "from": "254110090747",
    "mediaType": "IMAGE",
    "mediaUrl": "https://picsum.photos/id/237/200/300",
    "caption": ""
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://gateway.lipachat.com/api/v1/whatsapp/media',
  headers: { 
    'apiKey': 'YOUR_API_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}
{% endtabs %}

<details>

<summary>Sample Requests</summary>

Send Image

```json
{
	"messageId": "{{$randomUUID}}",
	"to": "{{YOUR_PHONE_NUMBER}}",
	"from": "{{WA_PHONE_NUMBER}}",
	"mediaType": "IMAGE",
	"mediaUrl": "https://picsum.photos/id/237/200/300",
	"caption": "Test caption"
}
```

Send Video

```json
{
	"messageId": "{{$randomUUID}}",
	"to": "{{YOUR_PHONE_NUMBER}}",
	"from": "{{WA_PHONE_NUMBER}}",
	"mediaType": "VIDEO",
	"mediaUrl": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.mp4",
	"caption": "Test caption"
}
```

Send Audio

```json
{
	"messageId": "{{$randomUUID}}",
	"to": "{{YOUR_PHONE_NUMBER}}",
	"from": "{{WA_PHONE_NUMBER}}",
	"mediaType": "AUDIO",
	"mediaUrl": "https://www2.cs.uic.edu/~i101/SoundFiles/BabyElephantWalk60.wav",
	"caption": "Optional Caption"
}
```

Send Document

```json
{
    "messageId": "{{$randomUUID}}",
    "to": "{{YOUR_PHONE_NUMBER}}",
    "from": "{{YOUR_PHONE_NUMBER}}",
    "mediaType": "DOCUMENT",
    "mediaUrl": "https://media_url.pdf",
    "filename": "insurance_policy.pdf",
    "caption": "Please find attached"
}
```

</details>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
      "timestamp": "2023-08-06T01:27:56.825898971",
      "data": {
            "messageId": "7addc006-07db-4fae-aac5-b285903b41d4",
            "waId": "wamid.HBgMMjU0NzE3NzQ2NTY1FQIAEnRgSRjJGRkMzNkQ0QUVENTIxQ0NBAA==",
            "status": "SENT",
            "statusDesc": "Media sent successfully"
      },
      "status": "success",
      "message": "",
      "errors": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
      "timestamp": "2023-08-06T17:50:35.701+00:00",
      "status": 400,
      "error": "Bad Request",
      "path": "/api/v1/whatsapp/message/text"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
      "timestamp": "2023-08-06T20:49:48.455464058",
      "data": null,
      "status": "success",
      "message": "Invalid credentials",
      "errors": null
}
```

{% endtab %}
{% endtabs %}