Developer Platform
  • Home
  • Getting Started
    • General Information
    • Features Overview
    • Security
  • APPs
    • Public Apps
      • Shopify
      • Salesforce
      • Zendesk
      • Google Analytics
    • Build your App
      • Getting started
      • My Apps
      • App information
      • App Parameters
      • App Plugins
      • Add Webhooks
      • Submit your Apps
      • App security
      • Developer Policy
  • Use Cases
    • Copilots
      • Product Catalog sync through API
      • FAQ sync through API
    • Visitor experience
      • Integrating custom buttons into your site
      • Check availability before escalating to iAdvize
      • Authenticated Messaging
        • Introduction
        • Web client-side implementation
          • Authenticated Messaging overview
          • Brief timeline of the integration process
          • How to enable authenticated mode in the administration portal?
          • How to implement the customer authentication backend (token provider)?
          • How to authenticate with iAdvize in client's website?
          • How to deal with activation success or failure?
          • How to logout?
          • Compatibility with Mobile SDK
          • FAQ
        • Web backend implementation
          • Important information and recommendations
          • Signature and Encryption Detailed Process
          • Technical backend implementation
          • FAQ
      • Cross-domain Conversation Continuity
      • Customize replies with Markdown
    • Agent workspace
      • Custom App example and step-by-step tutorial
        • Get Started
        • Work with the Desk
        • Intent / Trigger
        • JWT
        • References
    • Administration
      • Users
        • SAML SSO Authentication - Implementation Guide
        • Create, update and delete users via API
        • Manage the availability of your users with the iAdvize API
        • Integrate the iAdvize conversation panel into an existing tool
    • Data & Analytics
      • Anonymize a conversation or visitor data
      • Create a custom dashboard
      • Find contact data using GraphQL
      • Retrieve conversations data
      • Retrieve messages exchanged within a conversation
  • Technologies
    • GraphQL API
      • Terminology
      • Reference
      • Authentication
      • Schema lifecycle
      • Error Management
      • Pagination
    • REST API (deprecated)
      • Statistic (deprecated)
      • Group (deprecated)
      • Call meeting (deprecated)
      • Operator (deprecated)
      • Skill (deprecated)
      • Transaction (deprecated)
      • Visitor (deprecated)
    • Webhooks
      • Reference
      • Guides
    • Desk events
      • Reference
    • Web & Mobile SDK
      • Javascript Web SDK
        • Reference
      • Javascript Callbacks
        • Reference
        • Guides
      • Mobile SDK
        • Fourme (latest)
        • Epoisses
        • Dauphin
        • Cantal
        • 🤝Support Policy
        • 🤔Frequently Asked Questions
    • Custom App
    • External Bot
      • Implementation
        • Configuration flow
        • Conversation flow
        • Conversation objects
      • Configuration
      • FAQ
      • Best practices
Powered by GitBook
On this page
  • Await object
  • Close object
  • Transfer object
  • Message object payloads
  • Text
  • Card
  • ProductOffer
  • File
  • CardBundle
  • ProductOfferBundle
  • Generic objects

Was this helpful?

  1. Technologies
  2. External Bot
  3. Implementation

Conversation objects

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

PreviousConversation flowNextConfiguration

Last updated 1 year ago

Was this helpful?

These objects allow you to:

  • make a pause (between two messages for example)

  • end the conversation

  • transfer the visitor to a group of agents

  • send messages (simple or complex)

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

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

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

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

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

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.

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

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

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

✓

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.

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

✓

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.

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

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

✓

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

see

Example of a generic card with title, text and picture set
Example of a generic card with several links

Example of a product offer with offer

Example of a document payload
Example of a picture payload

Example of a generic card with title, text and picture set

Example of a generic card with title, text and picture set

Example of a text payload reply with two quick replies
see await object
see close object
see transfer object
see message objects
Quick reply object
http://my-website/order.pdf
http://image.net/image.jpg
http://mylink
QuickReply[]
Image
Action[]
Image
Action[]
Card[]
ProductOffer[]