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:

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.

FieldDescriptionTypeRequiredExample

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:

FieldDescriptionTypeRequiredExample

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.

FieldDescriptionTypeRequiredExample

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

FieldDescriptionTypeRequiredExample

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

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

FieldDescriptionTypeRequiredExample

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

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

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

FieldDescriptionTypeRequiredExample

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

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

βœ“

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

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.

FieldDescriptionTypeRequiredExample

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

βœ“

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

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.

FieldDescriptionTypesRequiredExample

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

βœ“

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"
          }]
      },
      { ... }
    ]
  }
}

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.

FieldDescriptionTypeRequiredExample

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

βœ“

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"
        }]
      },
      { ... }
    ]
  }
}

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.

FieldDescriptionTypeRequiredExample

url

Url pointing at a picture

String

βœ“

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.

FieldDescriptionTypeRequiredExample

type

Type of the action

String LINK

βœ“

LINK

name

name to display link

String

βœ“

My link

url

Link to be used in action

String

βœ“

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

FieldDescriptionTypeRequiredExample

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

Last updated