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. 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 as specified above. 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 which you can get from admin panel
GET /external/offer
Retrieves a paginated list of all marketing offers.
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
limit | number | Yes | Parameter for a pagination |
offset | number | Yes | Parameter for a pagination |
CURL Example
curl -X 'GET' \
'https://Altenar API URL/bets/last?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}'
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:33:53.821Z",
"endTime": "2024-05-21T16:33:53.821Z",
"type": "GLOBAL"
}
]
POST /external/offer
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"'
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"
]
}
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"'
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"
]
}
GET /external/offer/{offerId}
Get 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}'
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"
}
PATCH /external/offer/{offerId}
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: 5adc06f9-1be6-4542-8fbb-fdeafb16655b' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI4YjIyMzdjYi03ZTJkLTQxYTYtYmJiNC01ODA2NTY0ZWJlODIiLCJwcm9qZWN0IjoiZGV2IiwiaWF0IjoxNzEzMTczNjI2fQ.40XMB159r8BTaIRkNChsxUH1tv7-KaYqtybBYHz-7-8' \
--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"'
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"
]
}
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"'
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"
]
}
DELETE /external/offer/{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}'
Success response example
true
Additional
POST /user/external/advertisment
You can exclude user form all marketing offers if the 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 you create a new marketing offer, you can choose type of action on click on marketing offer
postMessage Example
{
"type": "link",
"body": {
"action": "open",
"data": {
"link": "${advertisement link from admin panel}"
}
}
}
Updated about 2 months ago