## RCS objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:----------------------------------------------------------------------------------------------------------------------------------------|:-----------------:|:---------------:| | sender | Textový odesílatel. Musí být nejdříve registrován. Pro registraci kontaktujte podporu [zde](https://www.bulkgate.com/cs/kontakt/). | **Yes** | - | | expiration | Časový limit v sekundách, po jehož vypršení bude použit alternativní kanál. Hodnoty nižší než `60` se ignorují a nahradí se výchozí hodnotou | **Ne** | `60` | | message | Message objekt. Nemůže být použít současně s následujícími parametry (File, Card, Carousel) viz [Message objekt](#message-objekt) | **Ne** | `null` | | file | File objekt. Nemůže být použít současně s následujícími parametr (Message, Card, Carousel) viz [File objekt](#file-objekt) | **Ne** | `null` | | card | Card objekt. Nemůže být použít současně s následujícími parametr (Message, File, Carousel) viz [Card objekt](#card-objekt) | **Ne** | `null` | | carousel | Carousel objekt. Nemůže být použít současně s následujícími parametr (Message, File, Card) viz [Carousel objekt](#carousel-objekt) | **Ne** | `null` | ## Message objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:---------------:|:-------------------------------------------------------------------|:-------:|:---------------:| | text | Text RCS zprávy | **Ano** | - | | suggestions | Pole suggestion tlačítek, viz [Suggestion](#suggestion-objekt) | **Ne** | `[]` | **Pří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ÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------:|:---------------:| | url | Cesta k souboru | **Ano** | - | | force_refresh | force_refresh nastaveno na `true` způsobí opětoivné vyžádání obsahu ze specifikované URL i za předpokladu ze obsah z URL je v cachei. Může zpozdit doručení zprávy k nekterým uživatelům. | **Ne** | `false` | | suggestions | Pole suggestion tlačítek, viz [Suggestion](#suggestion-objekt) | **Ne** | `[]` | **Příklad požadavku File 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", "file": { "url": "https://example.com/invoice-4517.pdf", "force_refresh": false, "suggestions": [ { "type": "reply", "text": "Got it", "postback": "invoice_received" } ] } } } } ``` ### Příklad File objektu ![File objekt](docs:advanced-rcs/rcs_file_message_example) ## Card objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:-----------------------------------------------------------------------------|:-------------:|:---------------:| | title | Titulek karty | **Ne** | `null` | | description | Popisek karty | **Ne** | `null` | | alignment | Zarovnání vlevo, nebo vpravo | **Ne** | `null` | | orientation | Orientace karty, horizontální, nebo vertikální | **Ne** | `null` | | media | Media objekt, viz [Card media objekt](#card-media-objekt) | **Ne** | `null` | | suggestions | Pole suggestion tlačítek, viz [Suggestion](#suggestion-objekt) | **Ne** | `[]` | ### Card media objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------|:---------------:| | url | Cesta k souboru | **Ano** | - | | force_refresh | force_refresh nastaveno na `true` způsobí opětovné vyžádání obsahu ze specifikované URL i za předpokladu ze obsah z URL je v cachei. Může zpozdit doručení zprávy k nekterým uživatelům. | **Ne** | `false` | | height | Výška media objektu (Short, Medium, Tall) | **Ne** | `null` | **Příklad požadavku Card 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", "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" } ] } } } } ``` ### Příklad Card objektu ![Card Objekt](docs:advanced-rcs/rcs_card_message_example) ## Carousel objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:--------------------------------|:-------:|:---------------:| | width | Šířka carouselu (small, medium) | **Ne** | `null` | | cards | Seznam carousel karet | **Ne** | `[]` | ### Carousel card objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:---------------------------------------------------------------|:-------:|:---------------:| | title | Titulek karty | **Ne** | `null` | | description | Popisek karty | **Ne** | `null` | | media | Media objekt, see [Card media objekt](#card-media-objekt) | **Ne** | `null` | | suggestions | Pole suggestion tlačítek, viz [Suggestion](#suggestion-objekt) | **Ne** | `[]` | **Pří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" } ] } } } } ``` ### Příklad Carousel objektu ![Carousel Object](docs:advanced-rcs/rcs_carousel_message_example) ### Příklad Carousel suggestion objektu ![Carousel suggestion Object](docs:advanced-rcs/rcs_carousel_suggestion_message_example) ## Suggestion objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------:|:---------------:| | type | Typ suggestion tlačítka, viz [Suggestion typy](#suggestion-typy) | **Ne** | `reply` | | text | Text suggestion tlačítka | **Ano** | - | | postback | Text odpovědi odeslané při stisknutí suggestion tlačítka | **Ne** | `ok` | | location | Lokace zobrazena při kliku na suggestion tlačítko (Použit pouze při nastaveni [`view_location`](#suggestions-view-location-objekt) suggestion typu) | **Ano**, ne současně s následujícími typy (`calendar`, `phone_number`, `url`) | - | | calendar | Událost kalendáře jenž se vytvoří při kliku na suggestion tlačítko (Použit pouze při nastaveni [`create_calendar_event`](#suggestions-create-calendar-event-objekt) suggestion typu) | **Ano**, ne současně s následujícími typy (`location`, `phone_number`, `url`) | - | | phone_number | Telefonní číslo, které se vytočí při kliku na suggestion tlačítko (Použit pouze při nastaveni [`dial_number`](#suggestions-dial-number-objekt) suggestion typu) | **Ano**, ne současně s následujícími typy (`location`, `calendar`, `url`) | - | | url | Redirekt na url při kliku na suggestion tlačítko (Použit pouze při nastavení [`open_url`](#suggestions-open-url-objekt) suggestion typu) | **Ano**, ne současně s následujícími typy (`location`, `calendar`, `phone_number`) | - | ## Příklad Location quick reply objektu ![Location quick reply objekt](docs:advanced-rcs/rcs_quick_reply_location_message_example) ## Suggestion typy | HODNOTA | POPIS | |:------------------------|:---------------------------| | `reply` | Rychlá odpověď | | `dial_number` | Před vytočit číslo | | `view_location` | Zobraz lokaci | | `share_location` | Sdílej mou lokaci | | `open_url` | Otevři url | | `create_calendar_event` | Vytvoř událost v kalendáři | ## Suggestions View Location objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:----------------------------------------------------------------------|:-----------:|:---------------:| | type | `view_location` | | | | text | Text suggestion tlačítka | **Ano** | - | | postback | Text odpovědi odeslané při stisknutí suggestion tlačítka. | Ne | `ok` | | location | [Lokace](#location-objekt) zobrazena při kliku na suggestion tlačítko | Ne | - | ### Location objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:----------------------------------------------------------------------------------------------|:-------------------------------------------------------:|:---------------:| | latitude | Desetinné číslo zeměpisné šířky | **Ano** společne s zeměpisnou výškou | `null` | | longitude | Desetinné číslo zeměpisné výšky | **Ano** společně s zeměpisnou šířkou | `null` | | query | Lokace kterou chtece vyhledat na mapě. | **Ano** pokud zeměpisná výška a šířka nejsou zadané | `null` | | label | Název lokace | Ne | `null` | **Příklad doporučené lokace** ```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ÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:---------------------------------------------------------------------------------------|:----------:|:---------------:| | type | `create_calendar_event` | | | | text | Text suggestion tlačítka | **Ano** | - | | postback | Text odpovědi odeslané při stisknutí suggestion tlačítka. | Ne | `ok` | | calendar | Událost [kalendáře](#calendar-objekt) jenž se vytvoří při kliku na suggestion tlačítko | Ne | - | ### Calendar objekt | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:---------------------------------------|:----------:|:---------------:| | start | DateTime počátku události | Ne | `null` | | end | DateTime konce události | Ne | `null` | | title | Název události | Ne | `null` | | description | Popisek události | Ne | `null` | | timezone | Časová zóna | Ne | `null` | **Příklad doporučené události:** ```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ÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:-----------------------------------------------------------------------|:----------:|:---------------:| | type | `dial_number` | | | | text | Text suggestion tlačítka | **Ano** | - | | postback | Text odpovědi odeslané při stisknutí suggestion tlačítka. | Ne | `ok` | | phone_number | Telefonní číslo, které se vytočí při kliku na suggestion tlačítko | Ne | - | **Příklad předvytočeného čísla** ```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ÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:--------------------------------------------------------------------------------|:-------:|:---------------:| | type | `open_url` | | | | text | Text suggestion tlačítka | **Ano** | - | | postback | Text odpovědi odeslané při stisknutí suggestion tlačítka. | Ne | `ok` | | url | Redirekt na url při kliku na suggestion tlačítko | Ne | - | **Příklad doporučené 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ÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:--------------------------------------------------------------|:-------:|:---------------:| | type | `reply` | | | | text | Text suggestion tlačítka | **Ano** | - | | postback | Text odpovědi odeslané při stisknutí suggestion tlačítka. | Ne | `ok` | **Příklad doporučené odpovědi** ```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ÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:--------------------------------------------------------------------|:-------:|:---------------:| | type | `share_location` | | | | text | Text suggestion tlačítka | **Ano** | - | | postback | Text odpovědi odeslané při stisknutí suggestion tlačítka. | Ne | `ok` | **Příklad sdílení lokace** ```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" } ] } } } } ``` ## Příklad kompletního requestu RCS objekt je na obou endpointech stejný - liší se jen příjemci kolem něj. Nejdřív RCS, SMS jako záchrana. RCS větev si bere text z `message.text`; text na nejvyšší úrovni dorazí jen do SMS větve. ```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édiem a suggestion tlačítkem, opět se SMS jako 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" } } } ``` Odpověď je pro všechny kanály stejná - viz [Advanced transactional](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-transactional/2.0/) nebo [Advanced promotional](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-promotional/2.0/).