Marketing Offers API

Overview

The Marketing Offer API allows partners to publish interactive widgets in chat environments. This API supports custom media settings, scheduling options, recipient targeting, and the configuration of potential winnings.

Additionally, the API can automatically post user wins to the chat (see the ‘Winshare Type’ section below).

This document outlines the requirements, configurations, and error handling for using the API effectively.

View types

In-feed view

Pop-up view

Usage

To use the API, send a POST request to the endpoint with a JSON payload containing the configurations . Ensure all required fields are included to avoid errors.

Below is an example of how to construct a POST request with a JSON payload for the Marketing Offer API. This sample payload includes all the necessary details to create a marketing offer with custom media settings, scheduling, targeted recipients, winnings configuration, and specifies the view type as "in chat".

API endpoints

All endpoints below are protected by Bearer token you can get on the admin panel

GET /external/offer

GET /external/advertisement

Retrieves a paginated list of all marketing offers.

Request parameters:

Parameter	Type	Required	Description
`limit`	number	No	Parameter for a pagination
`offset`	number	No	Parameter for a pagination

CURL Example:

curl -X 'GET' \
  'https://chatbackend.watchers.io/external/offer?limit=10&offset=0' \
  -H 'accept: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

curl -X 'GET' \
  'https://chatbackend.watchers.io/external/advertisement?limit=1&offset=0' \
  -H 'accept: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

Response example:

[
    {
        "id": 1,
        "pic": null,
        "template": 10,
        "title": null,
        "text": null,
        "link": null,
        "linkText": null,
        "templateData": "{\"alignment\":\"left\",\"bgColor\":\"rgba(255, 255, 255, 1)\",\"btnColor\":\"rgba(252, 227, 3, 1)\",\"btnTextColor\":\"#000\",\"textColor\":\"#000\",\"gradient\":false,\"gradientDirection\":\"180deg\"}",
        "showMultipleTimes": false,
        "showFrerquency": "DAILY",
        "showDelayMS": 0,
        "startTime": "2025-05-01T15:15:00.000Z",
        "endTime": null,
        "type": "GLOBAL",
        "openType": "NEW_WINDOW",
        "data": "[{\"lang\":\"en\",\"title\":\"123\",\"text\":\"123\",\"link\":\"\",\"linkText\":\"\"}]"
    }
]

[
    {
        "id": 11,
        "title": null,
        "text": null,
        "pic": null,
        "link": null,
        "linkText": "More",
        "template": 2,
        "templatePic": null,
        "templateData": null,
        "sendTime": null,
        "deleteTime": null,
        "status": "SENT",
        "createdAt": "2025-04-23T14:20:01.574Z",
        "openType": "NEW_WINDOW",
        "data": "[{\"lang\":\"en\",\"title\":\"123\",\"text\":\"123\",\"link\":\"https://watchers.io\",\"linkText\":\"123\",\"pic\":\"https://storage.googleapis.com/watchers-eu-storage/90592d28-b769-4f3c-917d-c247dfcfc64a.jpeg\"}]",
        "messagesLength": "1",
        "viewsLength": "0"
    }
]

POST /external/offer

POST /external/advertisement

It creates a new marketing offer in one of two widget types.

Type 1 - Text

Request parameters

Parameter	Type	Required	Description
`title`	`string`	Yes	Title for a marketing offer widget
`text`	`string`	Yes	Text for a marketing offer widget
`link`	`string`	Yes	Link for button or all widget (depends on template)
`linkText`	`string`	Yes	Text on button
`template`	10 - `integer`	Yes	Template for widget must be 10
`templateData`	`TemplateData`	Yes	See below
`startTime`	`datetime`	Yes	Time UTC when widget will be shown in the chat room
`endTime`	`datetime`	Yes	Time UTC when widget will be hidden in the chat room
`externalRoomIds`	`array of strings`	Optional	List of rooms where offer should be shown only if `type` ROOM is used
`externalUserIds`	`array of strings`	Optional	List of users to show only if `type` USER is used
`showMultipleTimes`	boolean	Yes	true or false
`type`	enum GLOBAL ROOM USER	Yes	GLOBAL - show for all users in all rooms ROOM - all users in the room USER - concrete user in all rooms

TemplateData

Parameter	Type	Required	Description
`alignment`	`string`	Yes	Whole alignment for all text and elements on widget
`bgColor`	`string`	Yes	Background color
`btnColor`	`string`	Yes	Background button color
`btnTextColor`	`string`	Yes	Button text color
`textColor`	`string`	Yes	Widget text color
`gradient`	`boolean`	Yes	Use gradient on backgroud or not
`gradientFrom`	`string`	Yes	Color for gradient
`gradientTo`	`string`	Yes	Color for gradient
`gradientDirection`	`string`	Yes	List of rooms where offer should be shown

CURL Example

curl -X 'POST' \
'https://chatbackend.watchers.io/external/offer' \
-H 'x-api-key: {Api key of project from admin panel}' \
-H 'Authorization: Bearer {Bearer token from admin panel}'
--form 'template="10"' \
--form 'title="Title"' \
--form 'text="Text"' \
--form 'link="https://www.watchers.io/"' \
--form 'linkText="Click me"' \
--form 'templateData="{\"alignment\": \"center\",\"bgColor\": \"#736969\",\"btnColor\": \"#1890bf\",\"btnTextColor\": \"#fff\",\"textColor\": \"#000\",\"gradient\": true,\"gradientFrom\": \"#60e753\",\"gradientTo\": \"#e4efe7\",\"gradientDirection\": \"135deg\" }"' \
--form 'showFrerquency="DAILY"' \
--form 'showDelayMS="0"' \
--form 'startTime="2024-05-22T12:00:01.000Z"' \
--form 'type="GLOBAL"'

curl -X 'POST' 'https://chatbackend.watchers.io/external/advertisement' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'
    -d '{
    "template": 2,
    "sendTime": null,
    "deleteTime": null,
    "openType": "NEW_WINDOW",
    "data": [
      {
        "lang": "en",
        "title": "123",
        "text": "123",
        "link": "https://watchers.io",
        "linkText": "123",
        "pic": "https://storage.googleapis.com/watchers-eu-storage/90592d28-b769-4f3c-917d-c247dfcfc64a.jpeg"
      }
    ],
    "externalRoomIds": [123]
  }'

Response example

{
  "offer": {
    "id": 0,
    "pic": "string",
    "template": 0,
    "title": "string",
    "text": "string",
    "link": "string",
    "linkText": "string",
    "templateData": "string",
    "showMultipleTimes": false,
    "showFrerquency": "DAILY",
    "showDelayMS": 0,
    "startTime": "2024-05-21T17:13:29.828Z",
    "endTime": "2024-05-21T17:13:29.828Z",
    "type": "GLOBAL"
  },
  "availableExternalRoomIds": [
    "string"
  ],
  "unavailableExternalRoomIds": [
    "string"
  ],
  "availableExternalUserIds": [
    "string"
  ],
  "unavailableExternalUserIds": [
    "string"
  ]
}

{
    "advertisement": {
        "id": 12,
        "title": null,
        "text": null,
        "pic": null,
        "link": null,
        "linkText": "Узнать подробности",
        "template": 2,
        "templatePic": null,
        "templateData": null,
        "sendTime": null,
        "deleteTime": null,
        "status": "SENT",
        "createdAt": "2025-05-01T15:25:39.304Z",
        "openType": "NEW_WINDOW",
        "data": "[{\"lang\":\"en\",\"title\":\"123\",\"text\":\"123\",\"link\":\"https://watchers.io\",\"linkText\":\"123\",\"pic\":\"https://storage.googleapis.com/watchers-eu-storage/90592d28-b769-4f3c-917d-c247dfcfc64a.jpeg\"}]",
        "user": null
    },
    "availableExternalRoomIds": [
        "123"
    ],
    "unavailableExternalRoomIds": [
        123
    ]
}

Type 2 - Image

Request parameters:

Parameter	Type	Required	Description
`pic`	`string`	Yes	Url to image
`link`	`string`	Yes	Link for button or all widget (depends on template)
`template`	11 - `integer`	Yes	Template for widget must be 11
`startTime`	`datetime`	Yes	Time UTC when widget will be shown in the chat room
`endTime`	`datetime`	Yes	Time UTC when widget will be hidden in the chat room
`externalRoomIds`	`array of strings`	Optional	List of rooms where offer should be shown only if `type` `ROOM` is used
`externalUserIds`	`array of strings`	Optional	List of users to show offer only if `type` `USER` is used
`showMultipleTimes`	boolean	Yes	true or false
`showFrerquency`	enum ON_ENTRY DAILY	Yes	–
`showDelayMS`	integer	Yes	After this delay offer will be shown
`type`	enum `GLOBAL` `ROOM` `USER`	Yes	GLOBAL - show for all users in all rooms ROOM - all users in the room USER - concrete user in all rooms

CURL Example:

curl -X 'POST' \
'https://chatbackend.watchers.io/external/offer' \
-H 'x-api-key: {Api key of project from admin panel}' \
-H 'Authorization: Bearer {Bearer token from admin panel}'
--form 'template="11"' \
--form 'pic="https://watchers.io/_next/static/media/hand-03.16265125.webp"' \
--form 'link="https://www.watchers.io/"' \
--form 'showFrerquency="DAILY"' \
--form 'showDelayMS="0"' \
--form 'startTime="2024-05-22T12:00:01.000Z"' \
--form 'type="GLOBAL"'

curl -X 'POST' 'https://chatbackend.watchers.io/external/advertisement' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'
    -d '{
    "template": 11,
    "openType": "NEW_WINDOW",
    "data": [{"lang":"en","title":"","text":"","link":"https://watchers.io","linkText":"","pic":"https://watchers.io/_next/static/media/intro.0c193d57.jpg"}],
    "externalRoomIds": [123]
  }'

Response example:

{
  "offer": {
    "id": 0,
    "pic": "string",
    "template": 0,
    "title": "string",
    "text": "string",
    "link": "string",
    "linkText": "string",
    "templateData": "string",
    "showMultipleTimes": false,
    "showFrerquency": "DAILY",
    "showDelayMS": 0,
    "startTime": "2024-05-21T17:13:29.828Z",
    "endTime": "2024-05-21T17:13:29.828Z",
    "type": "GLOBAL"
  },
  "availableExternalRoomIds": [
    "string"
  ],
  "unavailableExternalRoomIds": [
    "string"
  ],
  "availableExternalUserIds": [
    "string"
  ],
  "unavailableExternalUserIds": [
    "string"
  ]
}

{
    "advertisement": {
        "id": 13,
        "title": null,
        "text": null,
        "pic": null,
        "link": null,
        "linkText": "More",
        "template": 11,
        "templatePic": null,
        "templateData": null,
        "sendTime": null,
        "deleteTime": null,
        "status": "SENT",
        "createdAt": "2025-05-05T13:03:19.357Z",
        "openType": "NEW_WINDOW",
        "data": "[{\"lang\":\"en\",\"title\":\"\",\"text\":\"\",\"link\":\"https://watchers.io\",\"linkText\":\"\",\"pic\":\"https://storage.googleapis.com/watchers-eu-storage/574e7894-5a30-4383-8263-076437b305f2.jpeg\"}]"
    },
    "availableExternalRoomIds": [
        "123"
    ],
    "unavailableExternalRoomIds": []
}

GET /external/offer/{offerId}

GET /external/advertisement/{advertisementId}

Get a marketing offer by ID.

Request parameters:

Parameter	Type	Required	Description
`offerId`	number	Yes	id of marketing offer you want to get GET param in URL

CURL Example:

curl -X 'GET' \
  'https://chatbackend.watchers.io/external/offer/{marketing offer ID}' \
  -H 'accept: application/json'
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

curl -X 'GET' \
  'https://chatbackend.watchers.io/external/advertisement/{advertisement ID}' \
  -H 'accept: application/json'
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

Response example:

{
  "id": 0,
  "pic": "string",
  "template": 0,
  "title": "string",
  "text": "string",
  "link": "string",
  "linkText": "string",
  "templateData": "string",
  "showMultipleTimes": false,
  "showFrerquency": "DAILY",
  "showDelayMS": 0,
  "startTime": "2024-05-21T16:37:20.639Z",
  "endTime": "2024-05-21T16:37:20.639Z",
  "type": "GLOBAL"
}

[
    {
        "id": 1,
        "title": "7474",
        "text": "7474",
        "pic": null,
        "link": "https://watchers.io",
        "linkText": "More",
        "template": 3,
        "templateData": null,
        "sendTime": null,
        "deleteTime": null,
        "status": "SENT",
        "createdAt": "2024-04-09T11:00:26.648Z",
        "openType": "NEW_WINDOW",
        "data": null,
        "messagesLength": "0",
        "viewsLength": "7",
        "externalRoomIds": null
    }
]

PATCH /external/offer/{offerId}

PATCH /external/advertisement/{advertisementId}

Allows modifying widget information, depending on the specified template ID. Supports two types of widgets for updates.

Type 1 - Text

Url parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	marketing offer ID

Request parameters

Parameter	Type	Required	Description
`title`	`string`	Yes	Title for a marketing offer widget
`text`	`string`	Yes	Text for a marketing offer widget
`link`	`string`	Yes	Link for button or all widget (depends on template)
`linkText`	`string`	Yes	Text on button
`template`	10 - `integer`	Yes	Template for widget must be 10
`templateData`	`TemplateData`	Yes	See below
`startTime`	`datetime`	Yes	Time UTC when widget will be shown in the chat room
`endTime`	`datetime`	Yes	Time UTC when widget will be hidden in the chat room
`externalRoomIds`	`array of strings`	Optional	List of rooms where offer should be shown only if `type` `ROOM` is used
`externalUserIds`	`array of strings`	Optional	List of users to show offer only if `type` `USER` is used
`showMultipleTimes`	boolean	Yes	`true` or `false`
`showFrerquency`	enum ON_ENTRY DAILY	Yes
showDelayMS	integer	Yes	After this delay ofeer will be shown
type	enum `GLOBAL` `ROOM` `USER`	Yes	GLOBAL - show for all users in all rooms ROOM - all users in the room USER - concrete user in all rooms

TemplateData

Parameter	Type	Required	Description
`alignment`	`string`	Yes	Whole alignment for all text and elements on widget
`bgColor`	`string`	Yes	Background color
`btnColor`	`string`	Yes	Background button color
`btnTextColor`	`string`	Yes	Button text color
`textColor`	`string`	Yes	Widget text color
`gradient`	`boolean`	Yes	Use gradient on backgroud or not
`gradientFrom`	`string`	Yes	Color for gradient
`gradientTo`	`string`	Yes	Color for gradient
`gradientDirection`	`string`	Yes	List of rooms where offer should be shown

CURL Example

curl -X 'PATCH' \
  'https://chatbackend.watchers.io/external/offer/{marketing offer ID}' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}' \
--form 'template="10"' \
--form 'title="Title"' \
--form 'text="Text"' \
--form 'link="https://www.watchers.io/"' \
--form 'linkText="Click me"' \
--form 'templateData="{\"alignment\": \"center\",\"bgColor\": \"#736969\",\"btnColor\": \"#1890bf\",\"btnTextColor\": \"#fff\",\"textColor\": \"#000\",\"gradient\": true,\"gradientFrom\": \"#60e753\",\"gradientTo\": \"#e4efe7\",\"gradientDirection\": \"135deg\" }"' \
--form 'showFrerquency="DAILY"' \
--form 'showDelayMS="0"' \
--form 'startTime="2024-05-22T12:00:01.000Z"' \
--form 'type="GLOBAL"'

curl -X 'PATCH' 'https://chatbackend.watchers.io/external/advertisement/8' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'
    -d '{
    "template": 11
  }'

Response example

{
    "id": 1,
    "pic": null,
    "template": 10,
    "title": "Title",
    "text": "Text",
    "link": "https://www.watchers.io/",
    "linkText": "Click me",
    "templateData": "{\"alignment\": \"center\",\"bgColor\": \"#736969\",\"btnColor\": \"#1890bf\",\"btnTextColor\": \"#fff\",\"textColor\": \"#000\",\"gradient\": true,\"gradientFrom\": \"#60e753\",\"gradientTo\": \"#e4efe7\",\"gradientDirection\": \"135deg\" }",
    "showMultipleTimes": false,
    "showFrerquency": "DAILY",
    "showDelayMS": 0,
    "startTime": "2024-05-22T12:00:01.000Z",
    "endTime": null,
    "type": "GLOBAL",
    "rooms": [],
    "users": [],
    "openType": "NEW_WINDOW",
    "data": "[{\"lang\":\"en\",\"title\":\"Title\",\"link\":\"https://www.watchers.io/\",\"linkText\":\"Click me\",\"text\":\"Text\"}]"
}

true

Type 2 - Image

Url parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	marketing offer ID

Request parameters

Parameter	Type	Required	Description
`pic`	`string`	Yes	Url to image
`link`	`string`	Yes	Link for button or all widget (depends on template)
`template`	11 - `integer`	Yes	Template for widget must be 11
`startTime`	`datetime`	Yes	Time UTC when widget will be shown in the chat room
`endTime`	`datetime`	Yes	Time UTC when widget will be hidden in the chat room
`externalRoomIds`	`array of strings`	Optional	List of rooms where offer should be shown only if `type` `ROOM` is used
`externalUserIds`	`array of strings`	Optional	List of users to show offer only if `type` `USER` is used
`showMultipleTimes`	boolean	Yes	true or false
`showFrerquency`	enum	Yes
`showDelayMS`	integer	Yes	After this delay ofeer will be shown
`type`	enum GLOBAL ROOM USER	Yes	GLOBAL - show for all users in all rooms ROOM - all users in the room USER - concrete user in all rooms

CURL Example

curl -X 'PATCH' \
'https://chatbackend.watchers.io/external/offer/{marketing offer ID}' \
-H 'x-api-key: {Api key of project from admin panel}' \
-H 'Authorization: Bearer {Bearer token from admin panel}'
--form 'template="11"' \
--form 'pic="https://watchers.io/_next/static/media/hand-03.16265125.webp"' \
--form 'link="https://www.watchers.io/"' \
--form 'showFrerquency="DAILY"' \
--form 'showDelayMS="0"' \
--form 'startTime="2024-05-22T12:00:01.000Z"' \
--form 'type="GLOBAL"'

curl -X 'PATCH' 'https://chatbackend.watchers.io/external/advertisement/8' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'
    -d '{
    "template": 11
  }'

Response example

{
  "advertisement": {
    "title": "string",
    "text": "string",
    "pic": "string",
    "link": "string",
    "linkText": "string",
    "template": 0,
    "templatePic": "string",
    "templateData": "string",
    "sendTime": "2024-04-19T10:59:20.095Z",
    "deleteTime": "2024-04-19T10:59:20.095Z",
    "status": "string",
    "messages": [
      "string"
    ],
    "createdAt": "2024-04-19T10:59:20.095Z"
  },
  "availableExternalRoomIds": [
    "string"
  ],
  "unavailableExternalRoomIds": [
    "string"
  ]
}

true

DELETE /external/offer/{offerId}

DELETE /external/advertisement/{offerId}

Deletes the specified marketing offer by its ID.

Request parameters

Parameter	Type	Required	Description
`id`	number	Yes	id of marketing offer you want to delete GET param in URL

CURL Example

curl -X 'DELETE' \
  'https://chatbackend.watchers.io/external/offer/{marketing offer ID}' \
  -H 'accept: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

curl -X 'DELETE' \
  'https://chatbackend.watchers.io/external/advertisement/{advertisement ID}' \
  -H 'accept: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}'

Success response example

true

true

Additional

POST /user/external/advertisment

You can exclude a user form all marketing offers if request this option.

Request parameters:

Parameter	Type	Required	Description
`decryptedUserId`	`string`	Yes	unencrypted user ID (if encryption has been used)
`value`	boolean	Yes	Text for a marketing offer widget

Request Body example:

{
  "decryptedUserId": "string",
  "value": true
}

Response example

Empty, code 201

When create a new marketing offer, you can choose a type of action on click

postMessage Example:

{
  "type": "link",
  "body": {
    "action": "open",
    "data": {
      "link": "${advertisement link from admin panel}"
    }
  }
}

WinShare type

This API allows automatically post user wins to the chat.

Parameter	Type	Required	Description
`template`	`integer`	Yes	must be 12
`userId`	`string`	No	Could be empty

curl -X 'POST' 'https://chatbackend.watchers.io/external/advertisement' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel} \
    -d '{
      "data": [
        {
          "lang": "en",
          "title": "Release the kraken",
          "text": "multiplier",
          "link": "https://watchers.io/",
          "linkText": "won 234$",
          "pic": "https://watchers.io/_next/static/media/intro.0c193d57.jpg"
        }
      ],
      "template": 12,
      "externalRoomIds": [
        "123"
      ],
      "userId": "123"
    }'