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

# Send WhatsApp Media

> Send an image, video, audio, or document via WhatsApp Business API

Sends a media message (image, video, audio, or document) to a contact through a WABA channel. You can provide a public URL or a base64-encoded file.

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication.
</ParamField>

## Body

<ParamField body="channel_id" type="string" required>
  UUID of the WABA channel to send from.
</ParamField>

<ParamField body="contact_id" type="string" required>
  UUID of the contact to message.
</ParamField>

<ParamField body="media_type" type="string" required>
  Type of media to send. Possible values: `image`, `video`, `audio`, `document`.
</ParamField>

<ParamField body="media_data" type="string" required>
  Either a publicly accessible URL (e.g. `https://example.com/image.jpg`) or a base64-encoded string of the file. If base64, the file is uploaded to storage automatically.
</ParamField>

<ParamField body="content" type="string">
  Optional caption for the media (text displayed below the file).
</ParamField>

<ParamField body="file_name" type="string">
  Original filename for document types (e.g. `invoice.pdf`). Defaults to a generated name based on media type.
</ParamField>

<ParamField body="thread_id" type="string">
  UUID of an existing thread. If provided, `channel_id` and `contact_id` are inferred automatically.
</ParamField>

<ParamField body="save_message" type="boolean" default="true">
  Whether to save the message in the conversation thread. Defaults to `true`.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` if the media was sent successfully.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="Response data">
    <ResponseField name="message_id" type="string">
      Internal UUID of the message record.
    </ResponseField>

    <ResponseField name="provider_id" type="string">
      WhatsApp message ID returned by Meta.
    </ResponseField>

    <ResponseField name="media_url" type="string">
      Public URL where the media file is stored.
    </ResponseField>

    <ResponseField name="thread_id" type="string">
      UUID of the conversation thread.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error Codes

* `400 Bad Request` — Missing required fields, invalid channel type, or invalid media data
* `401 Unauthorized` — Invalid or missing API key
* `404 Not Found` — Contact not found
* `500 Internal Server Error` — Upload or Meta API failure

## Code Examples

<RequestExample>
  ```bash cURL — Send image by URL theme={null}
  curl -X POST "https://api.contactship.ai/v1/waba/send-media" \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "channel_id": "chn_abc123",
      "contact_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "media_type": "image",
      "media_data": "https://example.com/product-catalog.jpg",
      "content": "Check out our latest catalog!"
    }'
  ```

  ```bash cURL — Send document by URL theme={null}
  curl -X POST "https://api.contactship.ai/v1/waba/send-media" \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "channel_id": "chn_abc123",
      "contact_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "media_type": "document",
      "media_data": "https://example.com/invoice.pdf",
      "file_name": "invoice_2026.pdf",
      "content": "Your invoice for this month"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.contactship.ai/v1/waba/send-media',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your-api-key',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        channel_id: 'chn_abc123',
        contact_id: 'c1d2e3f4-a5b6-7890-cdef-123456789012',
        media_type: 'image',
        media_data: 'https://example.com/product-catalog.jpg',
        content: 'Check out our latest catalog!',
      }),
    }
  );
  const result = await response.json();
  console.log(`Media URL: ${result.data.media_url}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.contactship.ai/v1/waba/send-media',
      headers={'x-api-key': 'your-api-key'},
      json={
          'channel_id': 'chn_abc123',
          'contact_id': 'c1d2e3f4-a5b6-7890-cdef-123456789012',
          'media_type': 'image',
          'media_data': 'https://example.com/product-catalog.jpg',
          'content': 'Check out our latest catalog!',
      },
  )
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "success": true,
    "message": "Media enviado y guardado",
    "data": {
      "message_id": "msg-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "provider_id": "wamid.HBgNMTIxMjM0NTY3ODkwFQIAERgSM...",
      "media_url": "https://example.com/product-catalog.jpg",
      "thread_id": "thr-b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  }
  ```
</ResponseExample>