---
title: Marketing Offers API 
updatedAt: 2026-09-06T11:12:34.150Z
---

Fetch the complete documentation index at: https://docs.watchers.io/llms.txt

# Marketing Offers API 

You cansend personalised marketing offers automatically, and also to set the win sharing up to engage your users as never before

## Overview

> ⚠️ **Regional endpoints:** Replace `chatbackend.watchers.io` with the endpoint matching your project region. See [Supported Regions](https://docs.watchers.io/docs/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 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

<div style="display: flex; justify-content: center; gap: 5%;">
  <div style="text-align: center; width: 40%;">
    <img src="https://docs-assets.watchers.io/docs/readme/8e43cfebc652d27e091f11a7e446c9ec72b647ff4c237931d719177ffc75ab4f-feed-1.png" alt="In-feed view" style="width: 100%;">
    <p>In-feed view</p>
  </div>
  <div style="text-align: center; width: 40%;">
    <img src="https://docs-assets.watchers.io/docs/readme/9445038a22a663559d992101058370fc31fb7cd7cd5cfa6e47ee9024a033624d-feed.png" alt="Pop-up view" style="width: 100%;">
    <p>Pop-up view</p>
  </div>
</div>

<br>

### 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".

## Multilingual content

You can publish an offer with content in several languages in one request. Both endpoints (`/external/offer` for pop-up offers and `/external/advertisement` for in-feed offers) accept a `data` parameter in POST and PATCH requests: an array of per-language objects. The user sees the version matching their interface language, with a fallback to the project default language.

Fields of each object in the `data` array:

| Parameter | **Type** | **Required** | **Description** |
| --- | --- | --- | --- |
| `lang` | `string` | Yes | Language code (max 10 characters), matching the languages enabled for your project |
| `title` | `string` | No | Widget title for this language (max 100 characters) |
| `text` | `string` | No | Widget text for this language (max 300 characters) |
| `link` | `string` | No | Link for this language |
| `linkText` | `string` | No | Button text for this language (max 50 characters) |
| `promocode` | `string` | No | Promo code for this language |
| `pic` | `string` | No | Image URL for this language |

Example: a pop-up offer published in two languages.

```bash pop-up
curl -X 'POST' 'https://chatbackend.watchers.io/external/offer' \
  -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": "Welcome bonus",
        "text": "Claim your bonus now",
        "link": "https://example.com/promo",
        "linkText": "Start",
        "pic": "https://example.com/banner.jpeg"
      },
      {
        "lang": "es",
        "title": "Bono de bienvenida",
        "text": "Reclama tu bono ahora",
        "link": "https://example.com/promo",
        "linkText": "Empezar",
        "pic": "https://example.com/banner.jpeg"
      }
    ],
    "type": "ROOM",
    "externalRoomIds": ["room-123"],
    "template": 0,
    "templateData": {
      "btnColor": "#5c4e54",
      "btnTextColor": "#ffffff",
      "btnGradient": true,
      "btnGradientFrom": "#5c4e54",
      "btnGradientTo": "#fa2083",
      "btnGradientDirection": "180deg"
    },
    "openType": "NEW_WINDOW",
    "title": "Welcome bonus",
    "text": "Claim your bonus now",
    "showMultipleTimes": true,
    "showFrerquency": "ON_ENTRY",
    "showDelayMS": "5000"
  }'
```
```curl coupon(message)
curl -X 'POST' 'https://chatbackend.watchers.io/external/advertisement' \
  -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": "Welcome bonus",
        "text": "Use the promo code below",
        "link": "",
        "linkText": "Copy",
        "promocode": "WELCOME10",
        "pic": "https://example.com/banner.jpeg"
      },
      {
        "lang": "es",
        "title": "Bono de bienvenida",
        "text": "Usa el código promocional",
        "link": "",
        "linkText": "Copiar",
        "promocode": "WELCOME10",
        "pic": "https://example.com/banner.jpeg"
      }
    ],
    "externalRoomIds": ["room-123"],
    "template": 2,
    "openType": "NEW_WINDOW",
    "title": "Welcome bonus",
    "text": "Use the promo code below",
    "promocode": "WELCOME10"
  }'
```

To change translations of an existing offer, send the full `data` array via PATCH (`/external/offer/{offerId}` or `/external/advertisement/{advertisementId}`):

```bash pop-up
curl -X 'PATCH' 'https://chatbackend.watchers.io/external/offer/{marketing offer ID}' \
  -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": "Welcome bonus", "text": "Claim your bonus now", "link": "https://example.com/promo", "linkText": "Start" },
      { "lang": "es", "title": "Bono de bienvenida", "text": "Reclama tu bono ahora", "link": "https://example.com/promo", "linkText": "Empezar" },
      { "lang": "fr", "title": "Bonus de bienvenue", "text": "Réclamez votre bonus", "link": "https://example.com/promo", "linkText": "Commencer" }
    ]
  }'
```
```curl coupon(message)
curl -X 'PATCH' 'https://chatbackend.watchers.io/external/advertisement/{advertisement ID}' \
  -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": "Welcome bonus", "text": "Use the promo code", "linkText": "Copy", "promocode": "WELCOME10" },
      { "lang": "es", "title": "Bono de bienvenida", "text": "Usa el código promocional", "linkText": "Copiar", "promocode": "WELCOME10" }
    ]
  }'
```

## 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:

```bash pop-up
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}'
```
```c coupon(message)
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:

```json
[
    {
        "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":""}]"
    }
]
```
```json coupon(message)
[
    {
        "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

<img src="https://docs-assets.watchers.io/docs/readme/32440c295a64bea1ffff58f69a7d9cdd8189bae4ebf08c14f5dcb4a5703bca4c-text-highlight.svg" alt="" style="width:40%" class="img-center">

Request parameters

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

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

```bash pop-up
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 coupon(message)
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

```json pop-up
{
  "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"
  ]
}
```
```json coupon(message)
{
    "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

<img src="https://docs-assets.watchers.io/docs/readme/942d7fc8e8226bd69049cfca56cd421377340ea8c5f340b83e918225ef2e48fe-ad-highlight.png" alt="" style="width:40%" class="img-center">

Request parameters:

<table class="docs-table">
  <thead><tr> <th> Parameter</th>
      <th><b>Type</b></th>
      <th><b>Required</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>`pic`</td>
      <td>`string`</td>
      <td>Yes</td>
      <td>Url to image</td>
    </tr>
    <tr>
      <td>`link`</td>
      <td>`string`</td>
      <td>Yes</td>
      <td>Link for button or all widget (depends on template)</td>
    </tr>
    <tr>
      <td>`template`</td>
      <td>11 - `integer`</td>
      <td>Yes</td>
      <td>Template for widget must be 11</td>
    </tr>
    <tr>
      <td>`startTime`</td>
      <td>`datetime`</td>
      <td>Yes</td>
      <td>Time UTC when widget will be shown in the chat room</td>
    </tr>
    <tr>
      <td>`endTime`</td>
      <td>`datetime`</td>
      <td>Yes</td>
      <td>Time UTC when widget will be hidden in the chat room</td>
    </tr>
    <tr>
      <td>`externalRoomIds`</td>
      <td>`array of strings`</td>
      <td>Optional</td>
      <td>List of rooms where offer should be shown only if `type` `ROOM` is used</td>
    </tr>
    <tr>
      <td>`externalUserIds`</td>
      <td>`array of strings`</td>
      <td>Optional</td>
      <td>List of users to show offer only if `type` `USER` is used</td>
    </tr>
    <tr>
      <td>`showMultipleTimes`</td>
      <td>boolean</td>
      <td>Yes</td>
      <td>true or false</td>
    </tr>
    <tr>
      <td>`showFrerquency`</td>
      <td>enum <i> ON\_ENTRY </i> DAILY</td>
      <td>Yes</td>
      <td>–</td>
    </tr>
    <tr>
      <td>`showDelayMS`</td>
      <td>integer</td>
      <td>Yes</td>
      <td>After this delay offer will be shown</td>
    </tr>
    <tr>
      <td>`type`</td>
      <td>enum <i> `GLOBAL` </i> `ROOM` * `USER`</td>
      <td>Yes</td>
      <td>GLOBAL - show for all users in all rooms        ROOM - all users in the room USER - concrete user in all rooms</td>
    </tr>
  </tbody>
</table>

CURL Example:

```bash pop-up
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 coupon(message)
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:

```json pop-up
{
  "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"
  ]
}
```
```json coupon(message)
{
    "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:

<table class="docs-table">
  <thead><tr> <th> Parameter</th>
      <th><b>Type</b></th>
      <th><b>Required</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>`offerId`</td>
      <td>number</td>
      <td>Yes</td>
      <td>id of marketing offer you want to get <i>GET param in URL</i></td>
    </tr>
  </tbody>
</table>

CURL Example:

```bash pop-up
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 coupon(message)
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:

```json pop-up
{
  "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"
}
```
```json coupon(message)
[
    {
        "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

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

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

```bash pop-up
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 coupon(message)
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

```json pop-up
{
    "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"}]"
}
```
```curl coupon(message)
true
```

#### Type 2 - Image

Url parameters

| Parameter | **Type** | **Required** | **Description**    |
| --------- | -------- | ------------ | ------------------ |
| `id`      | `string` | Yes          | marketing offer ID |

Request parameters

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

CURL Example

```bash pop-up
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 coupon(message)
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

```json pop-up
{
  "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"
  ]
}
```
```json coupon(message)
true
```

### DELETE /external/offer/\{offerId}

### DELETE /external/advertisement/\{offerId}

Deletes the specified marketing offer by its ID.

Request parameters

<table class="docs-table">
  <thead><tr> <th> Parameter</th>
      <th><b>Type</b></th>
      <th><b>Required</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>`id`</td>
      <td>number</td>
      <td>Yes</td>
      <td>id of marketing offer you want to delete <i>GET param in URL</i></td>
    </tr>
  </tbody>
</table>

**CURL Example**

```bash pop-up
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 coupon(message)
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**

```json pop-up
true
```
```json coupon(message)
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:

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

Response example

```json
Empty, code 201
```

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

postMessage Example:

```jsx
{
  "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 |

<img src="https://docs-assets.watchers.io/docs/readme/4adcea4907f8b5d8b934421d0d05212652a4abbaf9929cdee7e4bfab9a8d8cb1-Design_examples.png" alt="" width="400" class="img-center">

<br>

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