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 supported languages. Accepts `true`/`false` or `1`/`0`
`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	Arbitrary string data attached to the giveaway, passed through to your system

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.

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"