# Conversation objects These objects allow you to: * make a pause (between two messages for example) [see await object](#await-object) * end the conversation [see close object](#close-object) * transfer the visitor to a group of agents [see transfer object](#transfer-object) * send messages (simple or complex) [see message objects](#message-objects) ## Await object If you are sending two messages in the same call, we strongly recommend that you use this object to mark a one-second pause between each message. This ensures that the messages are published in the correct order. | Field | Description | Type | Required | Example | | -------------- | ------------------------------- | ------------------------------ | -------- | --------- | | type | Type of the conversation object | String | ✓ | `await` | | duration.unit | Unit type | `millis \| seconds \| minutes` | ✓ | `seconds` | | duration.value | Delay value | Integer | ✓ | `20` | ```json { "type": "await", "duration": { "unit": "seconds", "value": 2 } } ``` ## Close object You can send a close conversation message such as: | Field | Description | Type | Required | Example | | ----- | ------------------------------- | ------ | -------- | ------- | | type | Type of the conversation object | String | ✓ | `close` | ```json { "type": "close" } ``` {% hint style="warning" %} A conversations is automatically **closed after 5 minutes** if nothing happens in the conversation. {% endhint %} ## Transfer object Transferring a conversation is quite straightforward. You can send the following messages: The `timeout` object (in the `transferOptions` key) allows you to specify the period of time during which iAdvize will try to perform the transfer. If the timeout is reached and the transfer could not be performed, the scenario continues and iAdvize will display the following messages. | Field | Description | Type | Required | Example | | ----------------------------- | ------------------------------------------------- | ------------------------------ | -------- | -------------------------------------- | | type | Type of the conversation object | String | ✓ | `transfer` | | distributionRule | Distribution/routing rule to transfer the visitor | UUID | ✓ | `f1cfbc00-1272-4780-9482-6597f56b39c3` | | transferOptions.timeout.unit | Unit type | `millis \| seconds \| minutes` | ✓ | `seconds` | | transferOptions.timeout.value | Delay value | Integer | ✓ | `20` | **Example** **In the following example,** we send a `transfer` message and schedule a failed transfer message afterward. If the transfer is successful, the next message for failed transfer is not published in the conversation. If the transfer fails, the message is sent to the conversation. This way you can notify your user about it and continue the conversation. ```json { "type": "transfer", "distributionRule": "f1cfbc00-1272-4780-9482-6597f56b39c3", "transferOptions": { "timeout": { "unit": "seconds", "value": 20 } } }, { "type": "message", "payload": { "contentType": "text", "value": "Transfer failed, please try again later" } }, { "type": "close" } ``` ## Message object payloads Several kinds of payloads can be used within your bot replies in order to enrich your responses. You will find in this section information about every type of content you can send with your iAdvize bot. ### **Text** Sending a simple message | Field | Description | Type | Required | Example | | ------------------- | ---------------------------------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | type | Type of the conversation object | String | ✓ | `message` | | payload | Payload described below | JSON Object | ✓ | see below | | payload.contentType | Type of the message’s content | String | ✓ | `text` | | payload.value | Textual content of the message | String | ✓ | Hi, i am a simple message. | | quickReplies | Quick replies to allow visitor to answer | [`QuickReply[]`](#quickreply) | | see [Quick reply object](https://developers.iadvize.com/documentation/building-your-bot-on-iadvize#quick-reply-object) | ```json { "type": "message", "payload": { "contentType": "text", "value": "Hi, i am a simple message." } } ``` ### **Card** A generic card is a payload you can use to send a more structured message. It always contains at least one link and can be used to help a visitor to navigate on a website by redirecting him to specific pages. You can specify multiple links on a single generic card. Generic card can also include a title, a description and an image. This help give context to the visitor about the links you are sending. | Field | Description | Type | Required | Example | | ------------------- | ---------------------------------------- | --------------------- | ------------------------------------- | ---------------------------------------------------------------- | | type | Type of the conversation object | String | ✓ | `message` | | payload | Payload described below | JSON Object | ✓ | see below | | payload.contentType | Type of the message’s content | String | ✓ | `card/content` | | payload.image | Json describing attached picture | [`Image`](#image) | | | | payload.title | Title of the card | String | | Delivery & Pickup | | payload.text | Textual content of the message | String | | Learn more about dispatch and delivery times, methods and costs. | | payload.actions | List of actions to be sent with the card | [`Action[]`](#action) | Action must contains at least on link | | #### Example 1: Generic one with title, text and picture ```json { "type": "message", "payload": { "contentType": "card/content", "image": { "url": "http://image.net/delivery.jpg", "description": "delivery picture" }, "title": "Delivery & Pickup", "text": "Learn more about dispatch and delivery times, methods and costs.", "actions": [ { "type": "LINK", "name": "See more", "url": "http://mylink.com/delivery" } ] } } ``` ![Example of a generic card with title, text and picture set](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/bots/example-generic-card-with-title-text-and-picture.png) #### Example 2: Only text and links ```json { "type": "message", "payload": { "contentType": "card/content", "actions": [ { "type": "LINK", "name": "How to print on an A4 page", "url": "http://mylink/a4page" }, { "type": "LINK", "name": "I could not print my stamps", "url": "http://mylink/stamps" }, { "type": "LINK", "name": "What are the different support and formats for etiquette?", "url": "http://mylink.com/etiquette" } ] } } ``` ![Example of a generic card with several links](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/bots/example-generic-card-with-several-links.png) ### **ProductOffer** A product offer payload lets you send a product offer to your visitor. Using the product offer you can showcase various attributes of your product such as the price, the photography of your product, the availability or a special offer. To show your visitors a carousel of product offers please see Product offer bundle | Field | Description | Type | Required | Example | | --------------------------- | ---------------------------------------- | ------------------------------------ | -------- | ----------------------- | | type | Type of the conversation object | String | ✓ | `message` | | payload | Payload described below | JSON Object | ✓ | see below | | payload.contentType | Type of the message’s content | String: `product-offer` | ✓ | `product-offer` | | payload.image | Json describing attached picture | [`Image`](#image) | | | | payload.name | Name of the product | String | ✓ | Samsung Frame 4K UHD TV | | payload.price | Price of the product without offer | String | ✓ | 1,499,99 € | | payload.offerPrice | Price of the product with offer | String | | 1,299,99 € | | payload.description | Description of the product | String | | | | payload.availability.status | Status of availability | One of: `AVAILABLE` or `UNAVAILABLE` | | `AVAILABLE` | | payload.actions | List of actions to be sent with the card | [`Action[]`](#action) | ✓ | | #### Example ```json { "type": "message", "payload": { "contentType": "product-offer", "image": { "url": "http://image.net/tvsamsumg.jpg", "description": "picture of a TV" }, "name": "Samsung Frame 4K UHD TV", "price": "€1,499.99", "offerPrice": "€1,299.99", "availability": { "status": "AVAILABLE" }, "actions": [ { "type": "LINK", "name": "See more", "url": "http://mylink/TvSamsung" } ] } } ``` ![Example of a product offer with offer](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/bots/example-product-offer-payload.png) ### **File** An attachment lets you send files directly in the chatbox. If you send an image it will be directly shown to the visitors if it is in a supported format by the visitor's browser. For a non-picture file it will offer the possibility to download it. | Field | Description | Type | Required | Example | | ------------------- | -------------------------------- | ------------------------------------------------------------------- | -------- | ------------------------------------------ | | type | Type of the conversation object | String | ✓ | `message` | | payload | Payload described below | JSON Object | ✓ | see below | | payload.contentType | Type of the message’s content | String `file` | ✓ | `file` | | payload.fileName | Name of the file to be displayed | String | ✓ | Can I add more information about my order? | | payload.mimeType | Mime type of the file | One of: `image/gif`, `application/pdf`, `image/png` or `image/jpeg` | ✓ | `image/gif` | | payload.url | Textual content of the message | String | ✓ | | #### Example: a text download link for a file ```json { "type": "message", "payload": { "contentType": "file", "fileName": "Can I add more information about my order?", "mimeType": "application/pdf", "url": "http://my-website.com/order.pdf" } } ``` ![Example of a document payload](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/bots/example-attachment-payload.png) #### Example 2: a picture directly shown in the conversation ```json { "type": "message", "payload": { "contentType": "file", "fileName": "My picture name", "mimeType": "image/png", "url": "http://my-website.com/image.png" } } ``` ![Example of a picture payload](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/bots/example-attachment-pic-payload.png) ### **CardBundle** With the generic card bundle you can create a carousel for the visitor. Sliders are an efficient tool to present multiple services, offers or products to your visitors. | Field | Description | Types | Required | Example | | ------------------- | ------------------------------- | -------------------- | -------- | ------------- | | type | Type of the conversation object | String | ✓ | `message` | | payload | Payload described below | JSON Object | ✓ | see below | | payload.contentType | Type of the message’s content | String `bundle/card` | ✓ | `bundle/card` | | payload.cards | List of cards to send | [`Card[]`](#card) | ✓ | | #### Example ```json { "type": "message", "payload": { "contentType": "bundle/card", "cards": [ { ... }, { "contentType": "card/content", "image": { "url": "http://image.net/delivery.jpg", "description": "delivery picture" }, "title": "Delivery & Pickup", "text": "Learn more about our policies", "actions": [{ "type": "LINK", "name": "See more", "url": "http://mylink/delivery" }] }, { ... } ] } } ``` ![Example of a generic card with title, text and picture set](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/bots/example-generic-card-bundle.png) ### **ProductOfferBundle** A product offer bundle is an efficient tool to showcase multiple products at one to your visitor. The visitor can navigate among the offers you sent using a slider. | Field | Description | Type | Required | Example | | ------------------- | --------------------------------- | --------------------------------- | -------- | ---------------------- | | type | Type of the conversation object | String | ✓ | `message` | | payload | Payload described below | JSON Object | ✓ | see below | | payload.contentType | Type of the message’s content | String `bundle/product-offer` | ✓ | `bundle/product-offer` | | payload.offers | List of product offers to display | [`ProductOffer[]`](#productoffer) | ✓ | | #### Example ```json { "type": "message", "payload": { "contentType": "bundle/product-offer", "offers": [ { ... }, { "contentType": "product-offer", "image": { "url": "http://image.net/tvpanasonic.jpg", "description": "picture of a TV" }, "name": "Panasonic Smart TV 4K", "price": "€1,499.99", "offerPrice": "€1,299.99", "description": "Enhance your everyday space with The Frame TV that reflects your style and fits your space", "availability": { "status": "AVAILABLE" }, "actions": [{ "type": "LINK", "name": "See more", "url": "http://mylink/TvPanasonic" }] }, { ... } ] } } ``` ![Example of a generic card with title, text and picture set](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/bots/example-product-offer-bundle.png) ### **Generic objects** #### **Image** An Image object can be used to display one image. The picture linked need to be of dimension 240x120(px) and should be displayable on browsers. | Field | Description | Type | Required | Example | | ----------- | ---------------------------------------------- | ------ | -------- | ---------------------------- | | url | Url pointing at a picture | String | ✓ | | | description | Textual description of the picture (alt field) | String | ✓ | picture of an image | ```json { "url": "http://image.net/image.jpg", "description": "picture of an image" } ``` #### **Action** Actions can be used to offers options to one visitor. Today, only link actions can be used. A link action is one action that can redirect one user to a given url link. | Field | Description | Type | Required | Example | | ----- | ------------------------- | ------------- | -------- | ------------------------------- | | type | Type of the action | String `LINK` | ✓ | `LINK` | | name | name to display link | String | ✓ | My link | | url | Link to be used in action | String | ✓ | [http://mylink](http://mylink/) | ```json { "type": "LINK", "name": "My link", "url": "http://mylink" } ``` #### **QuickReply** A quick reply is used for offering several choices to a visitor. Each choice needs to be specified in the "quickReplies" field of a reply. The answer sent by the visitor to the multiple choice question can only contain text. There is no maximum number of quick replies you can display. However we recommend not to use more than 3 quick replies for a single question. | Field | Description | Type | Required | Example | | ----------- | ---------------------------------- | ------------------ | -------- | ------------------ | | contentType | Type of the message’s content | `text/quick-reply` | ✓ | `text/quick-reply` | | value | Textual content of the quick-reply | String | ✓ | Yes | #### Example ```json { "contentType": "text/quick-reply", "value": "Yes, start the conversation" } ``` ![Example of a text payload reply with two quick replies](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/bots/example-quick-replies.png) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.iadvize.dev/technologies/external-bot/implementation/conversation-objects.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.