## Objeto RCS
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:------------------------------------------------------------------------------------------------------------------------------------------|:------------:|:-------------:|
| sender         | Remetente de texto. Tem de ser registado primeiro. Para o registo, contacte o suporte [aqui](https://www.bulkgate.com/pt/contacto/). |   **Sim**   |       -       |
| expiration     | Limite de tempo em segundos após o qual é utilizado o canal alternativo. Os valores inferiores a `60` são ignorados e substituídos pelo valor predefinido |      Não      |    `60`     |
| message        | Objeto Message. Não pode ser utilizado em conjunto com os seguintes parâmetros (File, Card, Carousel), consulte [Objeto Message](#objeto-message) |  Não  |    `null`     |
| file           | Objeto File. Não pode ser utilizado em conjunto com os seguintes parâmetros (Message, Card, Carousel), consulte [Objeto File](#objeto-file) |  Não  |    `null`     |
| card           | Objeto Card. Não pode ser utilizado em conjunto com os seguintes parâmetros (Message, File, Carousel), consulte [Objeto Card](#objeto-card) |      Não      |    `null`     |
| carousel       | Objeto Carousel. Não pode ser utilizado em conjunto com os seguintes parâmetros (Message, File, Card), consulte [Objeto Carousel](#objeto-carousel) |      Não      |    `null`     |


## Objeto Message
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:-----------------------------------------------------------|:---------:|:-------------:|
| text           | Texto da mensagem RCS |  **Sim**  |       -       |
| suggestions    | Sugestões, consulte [Suggestion](#objeto-suggestions) |    Não     |     `[]`      |


**Exemplo de pedido com o objeto Message:**
```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"
					}
				]
			}
		}
	}
}
```


## Objeto File
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:|
| url            | Caminho para o ficheiro |  **Sim**  |       -       |
| force_refresh  | `force_refresh` definido como true obriga o RBM a obter novo conteúdo a partir do URL indicado, mesmo que o conteúdo do URL esteja em cache, o que aumenta o tempo de entrega da mensagem aos utilizadores. |    Não     |    `false`    |
| suggestions    | Sugestões, consulte [Suggestion](#objeto-suggestions) |    Não     |     `[]`      |

**Exemplo de pedido com o objeto File:**
```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"
					}
				]
			}
		}
	}
}
```

### Exemplo do objeto File
![Objeto File](docs:advanced-rcs/rcs_file_message_example)


## Objeto Card
| NOME DO PARÂMETRO | VALOR |  OBRIGATÓRIO   | VALOR PREDEFINIDO |
|:---------------|:---------------------------------------------------|:------------:|:-------------:|
| title          | Título do cartão |   Não   |    `null`     |
| description    | Descrição do cartão |   Não   |    `null`     |
| alignment      | Alinhamento do cartão à esquerda ou à direita |   Não   |    `null`     |
| orientation    | Orientação do cartão, horizontal ou vertical |   Não   |    `null`     |
| media          | Multimédia, consulte [Objeto Card Media](#objeto-card-media) |   Não   |    `null`     |
| suggestions    | Sugestões, consulte [Suggestion](#objeto-suggestions) |   Não   |     `[]`      |


### Objeto Card Media
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO  | VALOR PREDEFINIDO |
|:---------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------:|:-------------:|
| url            | Caminho para o objeto multimédia |   **Sim** |       -       |
| force_refresh  | force_refresh definido como `true` obriga o RBM a obter novo conteúdo a partir do URL indicado, mesmo que o conteúdo do URL esteja em cache, o que aumenta o tempo de entrega da mensagem aos utilizadores. |     Não     |    `false`    |
| height         | Altura do objeto multimédia (Short, Medium, Tall) |     Não     |    `null`     |


**Exemplo de pedido com o objeto Card:**
```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"
					}
				]
			}
		}
	}
}
```

### Exemplo do objeto Card
![Objeto Card](docs:advanced-rcs/rcs_card_message_example)


## Objeto Carousel
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:-------------------------------------------------------------|:-----------:|:-------------:|
| width          | Largura do carrossel (small, medium) |   Não   |   `null`   |
| cards          | Lista de cartões do carrossel |   Não   |   `[]`   |



### Objeto Carousel Card
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:--------------------------------------------------------------------|:---------:|:-------------:|
| title          | Título do cartão do carrossel |   Não   |    `null`     |
| description    | Descrição do cartão |   Não   |    `null`     |
| media          | Multimédia, consulte [Objeto Card Media](#objeto-card-media) |   Não   |    `null`     |
| suggestions    | Sugestões, consulte [Suggestion](#objeto-suggestions) |   Não   |     `[]`      |


**Exemplo de pedido com o objeto Carousel:**
```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"
					}
				]
			}
		}
	}
}
```

### Exemplo do objeto Carousel
![Objeto Carousel](docs:advanced-rcs/rcs_carousel_message_example)

### Exemplo do objeto Carousel suggestion
![Objeto Carousel suggestion](docs:advanced-rcs/rcs_carousel_suggestion_message_example)


## Objeto Suggestions
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:--------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------:|:-------------:|
| type           | Tipo do botão de sugestão, consulte [Tipos de sugestão](#tipo-de-sugestao) |   Não   |  `reply`  |
| text           | Texto do botão de sugestão |   **Sim**   |    -    |
| postback       | Conteúdo enviado na resposta quando o botão de sugestão é premido |   Não   |  `ok`  |
| location       | Localização apresentada quando o botão de sugestão é premido, consulte [View Location](#objeto-suggestions-view-location) | **Sim**, não em conjunto com os seguintes (`calendar`, `phone_number`, `url`) |   -   |
| calendar       | A aplicação de calendário abre-se para criar um novo evento quando o botão de sugestão é premido, consulte [Create calendar event](#objeto-suggestions-create-calendar-event) | **Sim**, não em conjunto com os seguintes (`location`, `phone_number`, `url`) |   -   |
| phone_number   | Número de telefone que é pré-marcado quando o botão de sugestão é premido, consulte [Dial Number](#objeto-suggestions-dial-number) | **Sim**, não em conjunto com os seguintes (`location`, `calendar`, `url`) |   -   |
| url            | Depois de premir o botão de sugestão, o telemóvel é redirecionado para o URL indicado, consulte [Open url](#objeto-suggestions-open-url) | **Sim**, não em conjunto com os seguintes (`location`, `calendar`, `phone_number`) |   -   |

## Exemplo do objeto Location quick reply
![Objeto Location quick reply](docs:advanced-rcs/rcs_quick_reply_location_message_example)


## Tipo de sugestão
| VALOR | DESCRIÇÃO |
|:------------------------|:------------------------------|
| `reply`                 | Resposta rápida |
| `dial_number`           | Pré-marcar um número |
| `view_location`         | Mostrar a localização recebida |
| `share_location`        | Partilhar a localização do destinatário |
| `open_url`              | Abrir o URL recebido |
| `create_calendar_event` | Criar um evento no calendário |


## Objeto Suggestions View Location
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:---------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:|
| type           | `view_location` |           |               |
| text           | Texto do botão de sugestão |  **Sim**  |       -       |
| postback       | Conteúdo enviado na resposta quando o botão de sugestão é premido |  Não  |    `ok`     |
| location       | [Localização](#objeto-location) apresentada quando o botão de sugestão é premido. |    Não     |   -   |

### Objeto Location
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:--------------------------------------------------------------------------------------------------------------------|:---------------------------------------------:|:-------------:|
| latitude       | Valor decimal (float) da latitude |   **Sim**, juntamente com longitude   |    `null`    |
| longitude      | Valor decimal (float) da longitude |      **Sim**, juntamente com latitude      |    `null`     |
| query          | Nome do local (string) a procurar como localização | **Sim**, se longitude e latitude não estiverem definidas | `null`     |
| label          | Texto (string) utilizado como etiqueta da localização na mensagem |              Não              |  `null`   |


**Exemplo de pedido com o objeto de sugestão Location:**
```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"
						}
					}
				]
			}
		}
	}
}
```


## Objeto Suggestions Create calendar event
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:-----------------------------------------------------------------------------------------------|:--------------:|:-------------:|
| type           | `create_calendar_event` |                |               |
| text           | Texto do botão de sugestão | **Sim**  |       -       |
| postback       | Conteúdo enviado na resposta quando o botão de sugestão é premido. | Não  |    `ok`     |
| calendar       | A aplicação de [calendário](#objeto-calendar) abre-se para criar um novo evento quando o botão de sugestão é premido. | Não  |   -   |


### Objeto Calendar
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:--------------------------------------|:---------:|:-------------:|
| start          | Data e hora (DateTime) do início do evento |    Não     |    `null`     |
| end            | Data e hora (DateTime) do fim do evento | Não  |    `null`     |
| title          | Título (string) do evento no calendário |  Não  |    `null`     |
| description    | Descrição textual do evento |    Não     |  `null`   |
| timezone       | Fuso horário (string) |    Não     |  `null`   |


**Exemplo de pedido com o objeto de sugestão Calendar event:**
```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"
						}
					}
				]
			}
		}
	}
}
```


## Objeto Suggestions Dial Number
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:--------------------------------------------------------------------------|:---------:|:-------------:|
| type           | `dial_number` |           |               |
| text           | Texto do botão de sugestão |  **Sim**  |       -       |
| postback       | Conteúdo enviado na resposta quando o botão de sugestão é premido. |  Não  |    `ok`     |
| phone_number   | Número de telefone que é pré-marcado quando o botão de sugestão é premido. |    Não     |   -   |


**Exemplo de pedido com a sugestão de número pré-marcado:**
```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"
					}
				]
			}
		}
	}
}
```


## Objeto Suggestions Open url
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:-----------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|
| type           | `open_url` |                 |               |
| text           | Texto do botão de sugestão |    **Sim**    |       -       |
| postback       | Conteúdo enviado na resposta quando o botão de sugestão é premido. | Não  |    `ok`     |
| url            | URL para o qual é redirecionado quando prime o botão de sugestão. | Não  |   -   |

**Exemplo de pedido com a sugestão Open 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"
					}
				]
			}
		}
	}
}
```

## Objeto Suggestions Reply
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:-----------------------------------------------------------------------------------------------------------------------|:--------------:|:-------------:|
| type           | `reply` |                |               |
| text           | Texto do botão de sugestão | **Sim**  |       -       |
| postback       | Conteúdo enviado na resposta quando o botão de sugestão é premido. | Não  |    `ok`     |


**Exemplo de pedido com a sugestão Reply:**
```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"
					}
				]
			}
		}
	}
}
```


## Objeto Suggestions Share location
| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:---------------|:--------------------------------------------------------------------------|:--------------:|:-------------:|
| type           | `share_location` |                |               |
| text           | Texto do botão de sugestão | **Sim**  |       -       |
| postback       | Conteúdo enviado na resposta quando o botão de sugestão é premido. | Não  |    `ok`     |


**Exemplo de pedido com o objeto Share location:**
```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"
					}
				]
			}
		}
	}
}
```

## Exemplo de pedido completo

O objeto RCS é igual em ambos os endpoints - só os destinatários à sua volta são diferentes.

Primeiro RCS, SMS como alternativa. A parte RCS obtém o texto de `message.text`; o `text` de nível superior chega apenas à parte 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"
		}
	}
}
```

Um cartão com multimédia e uma sugestão, novamente com SMS como alternativa.

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

A resposta é igual para todos os canais - consulte [Advanced transactional](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-transactional/2.0/) ou [Advanced promotional](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-promotional/2.0/).