Giveaway API

Overview

Regional endpoints: Replace chatbackend.watchers.io with the endpoint matching your project region. See 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

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):

"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:

[
  { "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:

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)

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)

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"