---
title: Giveaway API
updatedAt: 2026-07-06T11:08:03.000Z
---

Fetch the complete documentation index at: https://docs.watchers.io/llms.txt

# Giveaway API

## Overview

> **Regional endpoints:** Replace `chatbackend.watchers.io` with the endpoint matching your project region. See [Supported Regions](https://docs.watchers.io/docs/supported-regions) for details.
> | Region | Endpoint |
> | :--- | :--- |
> | Europe (default) | `chatbackend.watchers.io` |
> | North America | `chatbackend.us.watchers.io` |
> | South America | `chatbackend.sa.watchers.io` |
> | Asia | `chatbackend.hk.watchers.io` |
> | Africa | `chatbackend.za.watchers.io` |

The Giveaway API allows partners to create and launch giveaway widgets programmatically in one or multiple chat rooms. This is an alternative to managing giveaways through the admin panel.

## Required Headers

| Parameter | Description |
| :--- | :--- |
| `x-api-key` | Your public API key used for the project |
| `Authorization` | Bearer token from the back office (_Admin panel / Settings / Bearer tokens_) |

## Create Giveaway

**POST** `https://chatbackend.watchers.io/external/giveaway`

Accepts both `application/json` and `multipart/form-data` (required when uploading a CSV file or image file).

### Request Parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `title` | string | Giveaway title displayed in the widget. Max 255 characters |
| `text` | string | Description text shown inside the widget. Max 255 characters |
| `buttonText` | string | Text on the participation button. Max 255 characters |
| `template` | integer | Widget template type |
| `pic` | string or file | Banner image. Pass a URL string, or upload a file via `multipart/form-data`. Max 10 MB, 16:9 aspect ratio |
| `templateData` | string | Additional template-specific settings |
| `startTime` | string (ISO 8601) | Scheduled start time. If omitted, the giveaway goes live immediately |
| `endTime` | string (ISO 8601) | End date and time of the giveaway |
| `maxWinners` | integer | Number of winners |
| `minParticipants` | integer | Minimum number of participants required for the giveaway to proceed |
| `maxParticipants` | integer | Maximum number of participants allowed. `maxWinners` must be less than this value |
| `minAccountAgeHours` | integer | Minimum account age in hours to participate. Prevents newly created accounts from joining |
| `minMessages` | integer | Minimum number of messages a user must have sent to be eligible. Excludes passive observers |
| `badgeIds` | array of integers | Restrict participation to users who hold one of the specified badge IDs |
| `enableTranslation` | boolean | Automatically translate the widget into all languages enabled for the project. Accepts `true`/`false` or `1`/`0`. Ignored if `data` is provided (your own translations always take priority) |
| `enableWinnersAnnouncement` | boolean | Send an automatic announcement to all chat participants when winners are selected. Accepts `true`/`false` or `1`/`0` |
| `rewardName` | string | Name of the prize displayed to users. Max 255 characters |
| `rewardDescription` | string | Description of the prize. Max 255 characters |
| `giftId` | string | ID of a pre-configured gift or reward item |
| `winnerListUrl` | string | Webhook URL. Watchers will POST winner details here when the giveaway ends. Max 255 characters |
| `roomIds` | array, CSV string, or CSV file | Chat rooms where the giveaway will run. Required if `userIds` is not provided. See formats below |
| `userIds` | array, CSV string, or CSV file | External user IDs to invite. Required if `roomIds` is not provided. See formats below |
| `data` | string (JSON) | Widget translations: a JSON string with an array of per-language objects (see **Multilingual Content** below). If provided, auto-translation is skipped even when `enableTranslation` is `true` |

> At least one of `roomIds` or `userIds` must be provided.

### roomIds / userIds Formats

Both fields accept three formats:

**JSON array** (in JSON body or form field):
```json
"roomIds": ["room_123", "room_456"]
```

**CSV string** (in form field):
```
roomIds=room_123,room_456,room_789
```

**CSV file** (multipart upload):
Upload a `.csv` file with the field name `roomIds` or `userIds`. The file should contain IDs separated by commas or newlines.

### Multilingual Content

You can publish a giveaway with content in several languages in one request. Pass the translations in the `data` parameter as a JSON string containing an array of per-language objects:

```json
[
  { "lang": "en", "title": "Weekly Prize Draw", "text": "Join to win!", "buttonText": "Join Now", "rewardName": "VIP Pass", "rewardDescription": "One month VIP access" },
  { "lang": "es", "title": "Sorteo semanal", "text": "¡Únete para ganar!", "buttonText": "Participar", "rewardName": "Pase VIP", "rewardDescription": "Un mes de acceso VIP" }
]
```

Localizable fields inside each object: `title`, `text`, `buttonText`, `rewardName`, `rewardDescription`. `lang` is the language code matching the languages enabled for your project.

The user sees the version matching their interface language. Fallback order: exact language, base language (e.g. `en` for `en-GB`), the project default language, the first entry in the array.

Two ways to get a multilingual giveaway:

- **Your own translations**: pass the `data` parameter as described above. Auto-translation is skipped, your texts are used as is.
- **Auto-translation**: omit `data` and set `enableTranslation: true`. The top-level `title`, `text`, `buttonText`, `rewardName` and `rewardDescription` are translated automatically into all languages enabled for the project.

Example with own translations:

```bash
curl -X POST https://chatbackend.watchers.io/external/giveaway \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly Prize Draw",
    "text": "Join to win!",
    "buttonText": "Join Now",
    "template": 1,
    "pic": "https://example.com/banner.jpg",
    "maxParticipants": 100,
    "maxWinners": 3,
    "rewardName": "VIP Pass",
    "roomIds": ["room_123"],
    "endTime": "2026-07-10T12:00:00.000Z",
    "data": "[{\"lang\":\"en\",\"title\":\"Weekly Prize Draw\",\"text\":\"Join to win!\",\"buttonText\":\"Join Now\",\"rewardName\":\"VIP Pass\"},{\"lang\":\"es\",\"title\":\"Sorteo semanal\",\"text\":\"¡Únete para ganar!\",\"buttonText\":\"Participar\",\"rewardName\":\"Pase VIP\"}]"
  }'
```

### Response

On success, returns the created giveaway object. The `status` field reflects the initial state:

| Value | Meaning |
| :--- | :--- |
| `SOON` | Giveaway is scheduled — `startTime` was provided |
| `LIVE` | Giveaway is active immediately — no `startTime` was provided |

### Example Request (JSON)

```bash
curl -X POST https://chatbackend.watchers.io/external/giveaway   -H "x-api-key: YOUR_API_KEY"   -H "Authorization: Bearer YOUR_BEARER_TOKEN"   -H "Content-Type: application/json"   -d '{
    "title": "Weekly Prize Draw",
    "text": "Join to win exclusive rewards!",
    "buttonText": "Join Now",
    "template": 1,
    "pic": "https://example.com/banner.jpg",
    "startTime": "2026-05-20T10:00:00Z",
    "endTime": "2026-05-21T10:00:00Z",
    "maxWinners": 3,
    "minMessages": 5,
    "enableTranslation": true,
    "enableWinnersAnnouncement": true,
    "rewardName": "VIP Pass",
    "rewardDescription": "One month VIP access",
    "winnerListUrl": "https://yourplatform.com/webhooks/giveaway-winners",
    "roomIds": ["room_123", "room_456"]
  }'
```

### Example Request (multipart with CSV file)

```bash
curl -X POST https://chatbackend.watchers.io/external/giveaway   -H "x-api-key: YOUR_API_KEY"   -H "Authorization: Bearer YOUR_BEARER_TOKEN"   -F "title=Weekly Prize Draw"   -F "text=Join to win exclusive rewards!"   -F "buttonText=Join Now"   -F "template=1"   -F "endTime=2026-05-21T10:00:00Z"   -F "maxWinners=3"   -F "enableTranslation=true"   -F "pic=@/path/to/banner.jpg"   -F "roomIds=@/path/to/rooms.csv"
```