Admin panel

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

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:

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

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

Shell
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"
Updated 2 months ago