## RCS objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| sender          | Textový odosielateľ. Musí byť najprv zaregistrovaný. Kvôli registrácii kontaktujte podporu [tu](https://www.bulkgate.com/sk/kontakt/). | **Áno** | - |
| expiration      | Časový limit v sekundách, po ktorého uplynutí sa použije alternatívny kanál. Hodnoty nižšie ako `60` sa ignorujú a nahradia sa predvolenou hodnotou | **Nie** | `60` |
| message         | Message objekt. Nemožno ho použiť súčasne s nasledujúcimi parametrami (File, Card, Carousel), pozrite [Message objekt](#message-objekt) | **Nie** | `null` |
| file            | File objekt. Nemožno ho použiť súčasne s nasledujúcimi parametrami (Message, Card, Carousel), pozrite [File objekt](#file-objekt) | **Nie** | `null` |
| card            | Card objekt. Nemožno ho použiť súčasne s nasledujúcimi parametrami (Message, File, Carousel), pozrite [Card objekt](#card-objekt) | **Nie** | `null` |
| carousel        | Carousel objekt. Nemožno ho použiť súčasne s nasledujúcimi parametrami (Message, File, Card), pozrite [Carousel objekt](#carousel-objekt) | **Nie** | `null` |


## Message objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:---------------:|:--------|:-------:|:------------------:|
|      text       | Text RCS správy | **Áno** | - |
|   suggestions   | Pole suggestion tlačidiel, pozrite [Suggestion](#suggestion-objekt) | **Nie** | `[]` |


**Príklad Message objektu:**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"message": {
				"text": "Your order 4517 has been shipped.",
				"suggestions": [
					{
						"type": "reply",
						"text": "Thanks",
						"postback": "order_thanks"
					},
					{
						"type": "open_url",
						"text": "Track the parcel",
						"url": "https://example.com/track/4517"
					}
				]
			}
		}
	}
}
``` 


## File objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| url             | Cesta k súboru | **Áno** | - |
| force_refresh   | force_refresh nastavené na `true` spôsobí opätovné vyžiadanie obsahu zo zadanej URL, aj keď je obsah z tejto URL v cache. Môže oneskoriť doručenie správy niektorým používateľom. | **Nie** | `false` |
| suggestions     | Pole suggestion tlačidiel, pozrite [Suggestion](#suggestion-objekt) | **Nie** | `[]` |


**Príklad požiadavky s File objektom:**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"file": {
				"url": "https://example.com/invoice-4517.pdf",
				"force_refresh": false,
				"suggestions": [
					{
						"type": "reply",
						"text": "Got it",
						"postback": "invoice_received"
					}
				]
			}
		}
	}
}
``` 

### Príklad File objektu
![File objekt](docs:advanced-rcs/rcs_file_message_example)


## Card objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| title           | Nadpis karty | **Nie** | `null` |
| description     | Popis karty | **Nie** | `null` |
| alignment       | Zarovnanie vľavo alebo vpravo | **Nie** | `null` |
| orientation     | Orientácia karty, horizontálna alebo vertikálna | **Nie** | `null` |
| media           | Media objekt, pozrite [Card media objekt](#card-media-objekt) | **Nie** | `null` |
| suggestions     | Pole suggestion tlačidiel, pozrite [Suggestion](#suggestion-objekt) | **Nie** | `[]` |


### Card media objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:--------|:------------------:|
| url             | Cesta k súboru | **Áno** | - |
| force_refresh   | force_refresh nastavené na `true` spôsobí opätovné vyžiadanie obsahu zo zadanej URL, aj keď je obsah z tejto URL v cache. Môže oneskoriť doručenie správy niektorým používateľom. | **Nie** | `false` |
| height          | Výška media objektu (Short, Medium, Tall) | **Nie** | `null` |


**Príklad požiadavky s Card objektom:**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"card": {
				"title": "Order 4517",
				"description": "Shipped today, delivery in two working days.",
				"orientation": "vertical",
				"alignment": "left",
				"media": {
					"url": "https://example.com/order-4517.jpg",
					"height": "medium",
					"force_refresh": false
				},
				"suggestions": [
					{
						"type": "reply",
						"text": "Thanks",
						"postback": "order_thanks"
					}
				],
				"card_suggestions": [
					{
						"type": "open_url",
						"text": "Open the order",
						"url": "https://example.com/orders/4517"
					}
				]
			}
		}
	}
}
```

### Príklad Card objektu
![Card objekt](docs:advanced-rcs/rcs_card_message_example)


## Carousel objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| width           | Šírka karuselu (small, medium) | **Nie** | `null` |
| cards           | Zoznam kariet karuselu | **Nie** | `[]` |


### Carousel card objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| title           | Nadpis karty | **Nie** | `null` |
| description     | Popis karty | **Nie** | `null` |
| media           | Media objekt, pozrite [Card media objekt](#card-media-objekt) | **Nie** | `null` |
| suggestions     | Pole suggestion tlačidiel, pozrite [Suggestion](#suggestion-objekt) | **Nie** | `[]` |


**Príklad Carousel objektu:**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"carousel": {
				"width": "medium",
				"cards": [
					{
						"title": "Spring jacket",
						"description": "Now 30 % off.",
						"media": {
							"url": "https://example.com/jacket.jpg",
							"height": "short"
						},
						"suggestions": [
							{
								"type": "open_url",
								"text": "Buy",
								"url": "https://example.com/p/jacket"
							}
						]
					},
					{
						"title": "Running shoes",
						"description": "Now 20 % off.",
						"media": {
							"url": "https://example.com/shoes.jpg",
							"height": "short"
						},
						"suggestions": [
							{
								"type": "open_url",
								"text": "Buy",
								"url": "https://example.com/p/shoes"
							}
						]
					}
				],
				"suggestions": [
					{
						"type": "reply",
						"text": "Show more",
						"postback": "carousel_more"
					}
				]
			}
		}
	}
}
```

### Príklad Carousel objektu
![Carousel objekt](docs:advanced-rcs/rcs_carousel_message_example)

### Príklad Carousel suggestion objektu
![Carousel suggestion objekt](docs:advanced-rcs/rcs_carousel_suggestion_message_example)


## Suggestion objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| type            | Typ suggestion tlačidla, pozrite [Suggestion typy](#suggestion-typy) | **Nie** | `reply` |
| text            | Text suggestion tlačidla | **Áno** | - |
| postback        | Text odpovede odoslanej po stlačení suggestion tlačidla | **Nie** | `ok` |
| location        | Poloha zobrazená po kliknutí na suggestion tlačidlo (použije sa len pri suggestion type [`view_location`](#suggestions-view-location-objekt)) | **Áno**, nie súčasne s nasledujúcimi typmi (`calendar`, `phone_number`, `url`) | - |
| calendar        | Udalosť v kalendári, ktorá sa vytvorí po kliknutí na suggestion tlačidlo (použije sa len pri suggestion type [`create_calendar_event`](#suggestions-create-calendar-event-objekt)) | **Áno**, nie súčasne s nasledujúcimi typmi (`location`, `phone_number`, `url`) | - |
| phone_number    | Telefónne číslo, ktoré sa vytočí po kliknutí na suggestion tlačidlo (použije sa len pri suggestion type [`dial_number`](#suggestions-dial-number-objekt)) | **Áno**, nie súčasne s nasledujúcimi typmi (`location`, `calendar`, `url`) | - |
| url             | Presmerovanie na URL po kliknutí na suggestion tlačidlo (použije sa len pri suggestion type [`open_url`](#suggestions-open-url-objekt)) | **Áno**, nie súčasne s nasledujúcimi typmi (`location`, `calendar`, `phone_number`) | - |


## Príklad Location quick reply objektu
![Location quick reply objekt](docs:advanced-rcs/rcs_quick_reply_location_message_example)


## Suggestion typy
| HODNOTA                 | POPIS                     |
|:------------------------|:--------------------------|
| `reply`                 | Rýchla odpoveď            |
| `dial_number`           | Predvoliť číslo na vytočenie |
| `view_location`         | Zobraziť polohu           |
| `share_location`        | Zdieľať moju polohu       |
| `open_url`              | Otvoriť URL               |
| `create_calendar_event` | Vytvoriť udalosť v kalendári |


## Suggestions View Location objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| type            | `view_location` | | |
| text            | Text suggestion tlačidla | **Áno** | - |
| postback        | Text odpovede odoslanej po stlačení suggestion tlačidla. | Nie | `ok` |
| location        | [Poloha](#location-objekt) zobrazená po kliknutí na suggestion tlačidlo | Nie | - |


### Location objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| latitude        | Zemepisná šírka ako desatinné číslo | **Áno** spolu so zemepisnou dĺžkou | `null` |
| longitude       | Zemepisná dĺžka ako desatinné číslo | **Áno** spolu so zemepisnou šírkou | `null` |
| query           | Poloha, ktorú chcete vyhľadať na mape. | **Áno**, ak nie je zadaná zemepisná šírka a dĺžka | `null` |
| label           | Názov polohy | Nie | `null` |



**Príklad odporúčanej polohy**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"message": {
				"text": "Your order 4517 has been shipped.",
				"suggestions": [
					{
						"type": "view_location",
						"text": "Show the pick-up point",
						"postback": "show_pickup",
						"location": {
							"latitude": 50.086584,
							"longitude": 14.410763,
							"query": "Karluv most",
							"label": "Pick-up point"
						}
					}
				]
			}
		}
	}
}
```


## Suggestions Create calendar event objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| type            | `create_calendar_event` | | |
| text            | Text suggestion tlačidla | **Áno** | - |
| postback        | Text odpovede odoslanej po stlačení suggestion tlačidla. | Nie | `ok` |
| calendar        | Udalosť v [kalendári](#calendar-objekt), ktorá sa vytvorí po kliknutí na suggestion tlačidlo | Nie | - |

### Calendar objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| start           | DateTime začiatku udalosti | Nie | `null` |
| end             | DateTime konca udalosti | Nie | `null` |
| title           | Názov udalosti | Nie | `null` |
| description     | Popis udalosti | Nie | `null` |
| timezone        | Časové pásmo | Nie | `null` |


**Príklad odporúčanej udalosti:**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"message": {
				"text": "Your order 4517 has been shipped.",
				"suggestions": [
					{
						"type": "create_calendar_event",
						"text": "Add delivery to calendar",
						"postback": "add_delivery",
						"calendar": {
							"start": "2026-09-14T09:00:00+02:00",
							"end": "2026-09-14T12:00:00+02:00",
							"title": "Delivery of order 4517",
							"description": "The courier will arrive in this window.",
							"timezone": "Europe/Prague"
						}
					}
				]
			}
		}
	}
}
```



## Suggestions Dial Number objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| type            | `dial_number` | | |
| text            | Text suggestion tlačidla | **Áno** | - |
| postback        | Text odpovede odoslanej po stlačení suggestion tlačidla. | Nie | `ok` |
| phone_number    | Telefónne číslo, ktoré sa vytočí po kliknutí na suggestion tlačidlo | Nie | - |

**Príklad predvoleného čísla na vytočenie**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"message": {
				"text": "Your order 4517 has been shipped.",
				"suggestions": [
					{
						"type": "dial_number",
						"text": "Call the courier",
						"postback": "call_courier",
						"phone_number": "420777777779"
					}
				]
			}
		}
	}
}
```


## Suggestions Open url objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| type            | `open_url` | | |
| text            | Text suggestion tlačidla | **Áno** | - |
| postback        | Text odpovede odoslanej po stlačení suggestion tlačidla. | Nie | `ok` |
| url             | Presmerovanie na URL po kliknutí na suggestion tlačidlo | Nie | - |

**Príklad odporúčanej URL**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"message": {
				"text": "Your order 4517 has been shipped.",
				"suggestions": [
					{
						"type": "open_url",
						"text": "Track the parcel",
						"postback": "track_parcel",
						"url": "https://example.com/track/4517"
					}
				]
			}
		}
	}
}
```


## Suggestions Reply objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| type            | `reply` | | |
| text            | Text suggestion tlačidla | **Áno** | - |
| postback        | Text odpovede odoslanej po stlačení suggestion tlačidla. | Nie | `ok` |

**Príklad odporúčanej odpovede**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"message": {
				"text": "Your order 4517 has been shipped.",
				"suggestions": [
					{
						"type": "reply",
						"text": "Thanks",
						"postback": "order_thanks"
					}
				]
			}
		}
	}
}
```

## Suggestions Share location objekt
| NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA |
|:----------------|:--------|:-------:|:------------------:|
| type            | `share_location` | | |
| text            | Text suggestion tlačidla | **Áno** | - |
| postback        | Text odpovede odoslanej po stlačení suggestion tlačidla. | Nie | `ok` |


**Príklad zdieľania polohy**
```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": [
		"420777777777"
	],
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"message": {
				"text": "Your order 4517 has been shipped.",
				"suggestions": [
					{
						"type": "share_location",
						"text": "Share your location",
						"postback": "share_location"
					}
				]
			}
		}
	}
}
```

## Príklad kompletnej požiadavky

RCS objekt je na oboch endpointoch rovnaký - líšia sa len príjemcovia okolo neho.

Najprv RCS, SMS ako záchrana. Vetva RCS si berie text z `message.text`; text na najvyššej úrovni sa dostane len do vetvy SMS.

```http-json
POST /api/2.0/advanced/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": ["420777777777"],
	"text": "Your order 4517 has been shipped.",
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"expiration": 120,
			"message": {
				"text": "Your order 4517 has been shipped.",
				"suggestions": [
					{"type": "open_url", "text": "Track the parcel", "url": "https://example.com/track/4517"},
					{"type": "reply", "text": "Thanks", "postback": "thanks"}
				]
			}
		},
		"sms": {
			"sender_id": "gText",
			"sender_id_value": "BulkGate"
		}
	}
}
```

Karta s médiom a suggestion tlačidlom, opäť so SMS ako záchranou.

```http-json
POST /api/2.0/advanced/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"number": ["420777777777", "420777777778"],
	"text": "Spring sale starts today, up to 50 % off.",
	"channel": {
		"rcs": {
			"sender": "BulkGate",
			"card": {
				"title": "Spring sale",
				"description": "Up to 50 % off, this week only.",
				"orientation": "vertical",
				"media": {
					"url": "https://example.com/spring-sale.jpg",
					"height": "medium"
				},
				"suggestions": [
					{"type": "open_url", "text": "Open the offer", "url": "https://example.com/spring-sale"}
				]
			}
		},
		"sms": {
			"sender_id": "gText",
			"sender_id_value": "BulkGate"
		}
	}
}
```

Odpoveď je pre všetky kanály rovnaká - pozrite [Advanced transactional](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-transactional/2.0/) alebo [Advanced promotional](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-promotional/2.0/).