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 |
---|---|---|---|
|
| Yes | Title for a marketing offer widget |
|
| Yes | Text for a marketing offer widget |
|
| Yes | Link for button or all widget (depends on template) |
|
| Yes | Text on button |
| 10 - | Yes | Template for widget must be 10 |
|
| Yes | See below |
|
| Yes | Time UTC when widget will be shown in the chat room |
|
| Yes | Time UTC when widget will be hidden in the chat room |
|
| Optional | List of rooms where offer should be shown
only if |
|
| Optional | List of users to show
only if |
| boolean | Yes | true or false |
| enum
| Yes | GLOBAL - show for all users 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 |
---|---|---|---|
|
| Yes | Url to image |
|
| Yes | Link for button or all widget (depends on template) |
| 11 - | Yes | Template for widget must be 11 |
|
| Yes | Time UTC when widget will be shown in the chat room |
|
| Yes | Time UTC when widget will be hidden in the chat room |
|
| Optional | List of rooms where offer should be shown
only if |
|
| Optional | List of users to show offer
only if |
| boolean | Yes | true or false |
| enum
| Yes | – |
| integer | Yes | After this delay offer will be shown |
| enum
| Yes | GLOBAL - show for all users 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 |
---|---|---|---|
| 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 |
---|---|---|---|
|
| Yes | Title for a marketing offer widget |
|
| Yes | Text for a marketing offer widget |
|
| Yes | Link for button or all widget (depends on template) |
|
| Yes | Text on button |
| 10 - | Yes | Template for widget must be 10 |
|
| Yes | See below |
|
| Yes | Time UTC when widget will be shown in the chat room |
|
| Yes | Time UTC when widget will be hidden in the chat room |
|
| Optional | List of rooms where offer should be shown
only if |
|
| Optional | List of users to show offer
only if |
| boolean | Yes |
|
| enum
| Yes | |
showDelayMS | integer | Yes | After this delay ofeer will be shown |
type | enum
| Yes | GLOBAL - show for all users 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 |
---|---|---|---|
|
| Yes | Url to image |
|
| Yes | Link for button or all widget (depends on template) |
| 11 - | Yes | Template for widget must be 11 |
|
| Yes | Time UTC when widget will be shown in the chat room |
|
| Yes | Time UTC when widget will be hidden in the chat room |
|
| Optional | List of rooms where offer should be shown
only if |
|
| Optional | List of users to show offer
only if |
| boolean | Yes | true or false |
| enum | Yes | |
| integer | Yes | After this delay ofeer will be shown |
| enum
| Yes | GLOBAL - show for all users 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 |
---|---|---|---|
| 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"
}'
Updated 9 days ago