Conversation objects

Conversation objects are used to describe the different events that can occur during a conversation with a visitor.

These objects allow you to:

• make a pause (between two messages for example) see await object

• end the conversation see close object

• transfer the visitor to a group of agents see transfer object

• send messages (simple or complex) see 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

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

{
  "type": "close"
}

A conversations is automatically closed after 5 minutes if nothing happens in the conversation.

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.

{
  "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[]		see Quick reply object

{
  "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
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 must contains at least on link

Example 1: Generic one with title, text and picture

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

Example 2: Only text and links

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

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
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[]	✓

Example

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

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	✓	http://my-website/order.pdf

Example: a text download link for a file

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

Example 2: a picture directly shown in the conversation

{
  "type": "message",
  "payload": {
    "contentType": "file",
    "fileName": "My picture name",
    "mimeType": "image/png",
    "url": "http://my-website.com/image.png"
  }
}

Example of a picture payload

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[]	✓

Example

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

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[]	✓

Example

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

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	✓	http://image.net/image.jpg
description	Textual description of the picture (alt field)	String	✓	picture of an image

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

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

{
  "contentType": "text/quick-reply",
  "value": "Yes, start the conversation"
}

Example of a text payload reply with two quick replies