Documentation

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

In-feed view

Pop-up 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

ParameterTypeRequiredDescription
limitnumberYesParameter for a pagination
offsetnumberYesParameter 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

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

showFrerquency

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

ParameterTypeRequiredDescription
alignmentstringYesWhole alignment for all text and elements on widget
bgColorstringYesBackground color
btnColorstringYesBackground button color
btnTextColorstringYesButton text color
textColorstringYesWidget text color
gradientbooleanYesUse gradient on backgroud or not
gradientFromstringYesColor for gradient
gradientTostringYesColor for gradient
gradientDirectionstringYesList 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

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"'

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

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}'

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

ParameterTypeRequiredDescription
idstringYesmarketing 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

ParameterTypeRequiredDescription
alignmentstringYesWhole alignment for all text and elements on widget
bgColorstringYesBackground color
btnColorstringYesBackground button color
btnTextColorstringYesButton text color
textColorstringYesWidget text color
gradientbooleanYesUse gradient on backgroud or not
gradientFromstringYesColor for gradient
gradientTostringYesColor for gradient
gradientDirectionstringYesList 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

ParameterTypeRequiredDescription
idstringYesmarketing 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"'

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

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}'

Success response example

true

Additional

POST /user/external/advertisment

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

Request parameters

ParameterTypeRequiredDescription
decryptedUserIdstringYesunencrypted user ID (if encryption has been used)
valuebooleanYesText 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}"
    }
  }
}