App Plugins

Use plugins to enhance the iAdvize interface by adding or editing predefined features.
Plugins are basically HTTP endpoints whose json responses fit the plugin json-schema. For each plugin one or more endpoint have to be defined. When a plugin is used on user interface, we will make a GET http call to endpoint with documented query parameters. Your http response have to comply with plugin json-schema. You can find a link of the json schema below each plugin route. It can be used to validate your http responses on your side.
The plugins already available are:
  • The product List (on the discussion panel)
  • The customer information (on the discussion panel)
  • The conversation closing form (on the discussion panel) - only for Chat/Call/Video channels
  • The bot (add an external bot within iadvize chatbox)

Product list

The integration of the product list enables iAdvize's Console panel users to browse a product catalog from the iAdvize discussion panel. Agents can look for a product while they are chatting and send it in just a click within their conversation.
Products are displayed in a popup window just over the conversations view: When shared, visitors can see their image, title, availability and price. By clicking on the "view product" button, visitors are redirected to the product page on your website.
Product list
Add the Product list plugin
To make sure your connector uses the Product list plugin correctly, all you have to do is to declare:
  • The product list URL - this is your catalog’s URL
  • The categories url - this is where your connector will get the list of your product categories
Categories data
Request - GET method
Query parameter
Description
Values
idConnectorVersion
Connector version id
?idConnectorVersion=c008849d-7cb1-40ca-9503-d6df2c5cddd8
idParent
Unique identifier of the parent category
?idParent=123
idWebsite
Unique identifier of the website on which your connector is installed
?idWebsite=ha-123
idOperator
Unique identifier of the operator loading the categories
?idOperator=9999
limit
Maximum number of resources per page
?limit=10
offset
Number of resources skipped before beginning to return resources
?offset=10
Response - Array of categories
[
{
"id": "123",
"idParent": "123",
"label": "category",
"products": [
"123",
"456"
],
"productsCount": 3
},
{
"id": "456",
"idParent": null,
"label": "category",
"products": null,
"productsCount": 7
}
]
Field
Description
Values
Required
id
Unique identifier
Integer
idParent
Unique identifier of the parent category
Integer
label
Label
String
products
products
Array of strings
productsCount
Number of products
Integer
You can validate your response data format with the associated json schema
Products data
Request - GET method
Query parameter
Description
Values
idConnectorVersion
Connector version id
?idConnectorVersion=c008849d-7cb1-40ca-9503-d6df2c5cddd8
idCategory
Category id
?idCategory=123
idWebsite
Unique identifier of the website on which your connector is installed
?idWebsite=ha-123
idOperator
Unique identifier of the operator loading the products
?idOperator=9999
limit
Maximum number of resources per page
?limit=10
offset
Number of resources skipped before beginning to return resources
?offset=10
searchQuery
Product search query
?searchQuery=query
Response - Array of products
[
{
"id": "123",
"title": "Product's title",
"productUrl": "http://www.e-commerce.com/url-product",
"brand": "brand",
"description": "product's description",
"shortDescription": "shrot description",
"available": true,
"imageUrl": "http://www.e-commerce.com/url-product-image.jpg",
"reference": "reference",
"priceCatalog": "99.9 €",
"pricePromotion": "90 €",
"priceSpecial": "80 €"
},
{
"id": "456",
"title": "Product's title",
"productUrl": "http://www.e-commerce.com/url-product",
"brand": null,
"description": "product's description",
"shortDescription": null,
"available": true,
"imageUrl": "http://www.e-commerce.com/url-product-image.jpg",
"reference": null,
"priceCatalog": "9.9 €",
"pricePromotion": null,
"priceSpecial": null
}
]
Field
Description
Values
Required
id
Unique identifier
Integer
title
Title
String
productUrl
Product's url
String
brand
Brand
String
description
Description
String
shortDescription
Short description
String
available
Availability
Boolean
imageUrl
Image's url
String
reference
Reference
String
priceCatalog
Price catalog
String
pricePromotion
Price promotion
String
priceSpecial
Price special
String
You can validate your response data format with the associated json schema.

Customer information

The customer information plugin enables iAdvize's Console panel users to access to customer information in a single click. Agents can overview the customer information in a new window while they are chatting. Operators can then edit it or simply look for information.
To be able to retrieve the customer information, iAdvize must be able to identify the visitor thanks to an email and/or an external ID.
Customer information
Add the customer information plugin In order to set the right plugin parameters, all you have to do is to declare:
  • The customer information URL - this is your customer information URL (mandatory).
  • The customer information action URL - This URL will be triggered, if agent click on ACTION type field. This field is not mandatory.
Customer information data
Request - GET method
Query parameter
Description
Values
emailVisitor
Visitor email
idConnectorVersion
Connector version id
?idConnectorVersion=c008849d-7cb1-40ca-9503-d6df2c5cddd8
idVisitorExternal
Visitor external id
?idVisitorExternal=123
idVisitorUnique
Visitor unique id
?idVisitorUnique=a7b94266db827c5b8f04586e8e543abd4b7e976e9a723
idWebsite
Unique identifier of the website on which your connector is installed
?idWebsite=ha-123
operatorLocale
Operator locale
?operatorLocale=en
idOperator
Unique identifier of the operator loading the visitor profile
?idOperator=9999
Response - Array of fields
[
{
"id":"crm_profile_link",
"label": "CRM profile",
"value": "https://www.crm.fr/customer-information",
"fieldType":"URL"
},
{
"id":"crm_visitor_tag",
"label": "CRM tag",
"value": "tag",
"fieldType": "TEXT"
},
{
"id":"crm_create_case_action",
"label": "Create a case",
"value": "OPEN_CASE",
"fieldType": "ACTION"
}
]
Field
Description
Values
Required
id
Unique identifier
String
label
Label
String
value
Value
String
fieldType
Field type
ACTION, TEXT or URL
You can validate your response data format with the associated json schema.
Customer information action URL
Request - POST method
Body parameters
Description
Values
action
Action to execute on the connector
OPEN_CASE
idConnectorVersion
Connector version id
c008849d-7cb1-40ca-9503-d6df2c5cddd8
idVisitorUnique
Visitor unique id
a7b94266db827c5b8f04586e8e543abd4b7e976e9a723
idWebsite
Unique identifier of the website on which your connector is installed
ha-123
idConversation
Identifier of the current conversation
ha-123
idOperator
Operator identifier who has clicked on the action
ha-12345
Response - Array of fields
{
"success": true,
"message": "Case created with success"
}
Field
Description
Values
Required
success
Result of the action
Boolean
message
Result message of the action
String
You can validate your response data format with the associated json schema.

Conversation closing form

The conversation closing form plugin enables iAdvize's Console panel users to provide additional information manually at the end of conversation. This plugin is only available for Chat / Call and Video channels. 3rd part channels are not supported.
Conversation closing form plugin
Add the conversation closing form plugin
In order to set the right plugin parameters, all you have to do is to declare:
  • The connector URL - this is your form's url
Conversation Closing Form data
Request - GET method
Query parameter
Description
Values
idConnectorVersion
Connector version id
?idConnectorVersion=c008849d-7cb1-40ca-9503-d6df2c5cddd8
idWebsite
Unique identifier of the associated website (assigned to you by iAdvize)
?idWebsite=ha-123
operatorLocale
Operator locale
?operatorLocale=en
idOperator
Unique identifier of the operator loading the form
?idOperator=9999
Response - Array of inputs
Field
Description
Values
Required
id
Unique identifier
string
idParent
Parent identifier, if the field depends on it
string
label
Label
string
fieldType
Field type
TEXT, CHECKBOX, SELECT, TEXTAREA, INTEGER or DECIMAL
isRequired
Required
Boolean
options
List of options object for SELECT type
array
options.label
Label displayed for this option
string
options.value
Value saved when option is selected
string
[
{
"id": "create_crm_ticket",
"label": "Create a CRM ticket",
"fieldType": "CHECKBOX",
"isRequired": true
},
{
"id": "brand_name",
"label": "Brand name",
"fieldType": "TEXT",
"isRequired": true
},
{
"id": "brand_description",
"label": "Brand name brings a totally new concept \n to their customers.",
"fieldType": "TEXTAREA",
"isRequired": true
},
{
"id": "ticket_priority",
"idParent": "create_crm_ticket",
"label": "Priority",
"fieldType": "SELECT",
"isRequired": true,
"options": [
{
"label": "Major",
"value": "MAJOR"
},
{
"label": "Minor",
"value": "MINOR"
},
{
"label": "Trivial",
"value": "TRIVIAL"
}
]
},
{
"id": "order_id",
"label": "The order id related to the claim",
"fieldType": "INTEGER",
"isRequired": false
},
{
"id": "order_discount",
"label": "The discount granted to the customer",
"fieldType": "DECIMAL",
"isRequired": false
}
]
You can validate your response data format with the associated json schema.
⚠️ iAdvize can save up to 1024 characters in each field

Conversation panel app

Conversation panel apps extends the capabilities of the Desk by allowing our clients to embed their own apps in a dedicated panel.
General guidelines
A complete breakdown of our guidelines for Conversation Panel Apps can be found in our knowledge base.
App development
The apps that can be embedded in the Desk are web apps coded in any web compliant technology - static web page, dynamic web pages such as php or jsp generated, single page applications written in Angular or React, etc...
These apps will be embedded in an iframe element in the Desk, and the web server serving these apps must allow them to run in an iframe on the iAdvize domains: https://sd.iadvize.com or https://ha.iadvize.com. This is done by configuring the X-FRAME-OPTIONS header.
The app can communicate with the desk by using a library provided by iAdvize.
Please note that one iframe is created per conversation in order to keep a context for an app for each conversation. It is recommended to keep the app very lightweight and avoid heavy processing or streaming updates.
Library quick start
To use the library an app must include a javascript bundle in the html with the following code.
<script src="https://static.iadvize.com/conversation-panel-app-lib/2.9.0/idzcpa.umd.production.min.js"></script>
Then in the javascript code of the app the library can be used as follows.
window.idzCpa.init().then(client => {
client.insertTextInComposeBox('Hello world!');
});
⚠️ CPAs available on the iAdvize iOS and Android apps must use the version 2.0.3 or greater.
API reference
idzCpa
idzCpa is a global variable used as the entry point of the CPA library.
init
function init(): Promise
The client is obtained via the idzCpa.init function that returns a Promise.
const clientPromise = idzCpa.init();
clientPromise.then(client => { / do something /});
Client context
client.context // => Context
type Context = {
conversationId: string;
projectId: string;
channel: Channel;
language: string;
}
// list of available channels:
enum Channel {
AppleBusinessChat = 'APPLE_BUSINESS_CHAT',
Call = 'CALL',
Chat = 'CHAT',
Facebook = 'FACEBOOK',
FacebookBusinessOnMessenger = 'FACEBOOK_BUSINESS_ON_MESSENGER',
GoogleBusinessMessages = 'GOOGLE_BUSINESS_MESSAGES',
Instagram = 'INSTAGRAM',
MobileApp = 'MOBILE_APP',
Sms = 'SMS',
Twitter = 'TWITTER',
Video = 'VIDEO',
Whatsapp = 'WHATSAPP',
}
The context property on the client returns the conversation context: conversation ID and project ID.
client.context.conversationId // => '5701a92f-a8e3-49ad-81dc-ac801171f799'
client.context.projectId // => '3103'
client.context.channel // => 'CHAT'
client.context.language // => 'fr'
List of commands available
Command
Description
insertTextInComposeBox
Allows the CPA to send some text to the active thread compose zone.
pushCardInConversationThread
Allows the CPA to send a card to the active conversation thread.
pushCardBundleInConversationThread
Allows the CPA to send a card carousel to the active conversation thread.
pushApplePayPaymentRequestInConversationThread
Allows the CPA to send an Apple Pay Payment request in the conversation thread.
getJWT
Allows the CPA to get a JWT token signed with the secret token defined in the connector of the CPA.
How to use each command
insertTextInComposeBox
Allows the CPA to send some text to the active thread compose zone.
Signature
function insertTextInComposeBox(value: string): void
⚠️ value field is required
Example
client.insertTextInComposeBox('Hello world!');
Result
insertTextInComposeBox
pushCardInConversationThread
Allows the CPA to send a card to the active conversation thread.
Signature
type Action = {
type: 'LINK';
title: string;
url: string;
}
type Card = {
title?: string;
text?: string;
actions: Action[],
image?: {
url: string;
description: string;
}
}
function pushCardInConversationThread(value: Card): void
⚠️ actions field is required and must contain at least one action of LINK type ⚠️ title, text and image fields are optional
Example
const card: Card = {
title: "Card 1 title",
text: "Card 1 description",
actions: [
{
type: 'LINK',
title: "Click here",
url: "https://..."
},
],
image: {
url: "https://...",
description: "Image description add to alt img attribute",
}
}
client.pushCardInConversationThread(card)
Result
pushCardInConversationThread
pushCardBundleInConversationThread
Allows the CPA to send a card carousel to the active conversation thread.
Signature
type Carousel = {
title?: string;
cards: Card[]; // See pushCardInConversationThread command for more information of Card type
}
function pushCardBundleInConversationThread(value: Carousel): void
⚠️ title field of Carousel is optional ⚠️ cards field of Carousel is required
Example
const card1: Card = {
title: "Card 1 title",
text: "Card 1 description",
actions: [
{
type: "LINK",
title: "Click here",
url: "https://...",
}
],
image: {
url: "https://...",
description: "Image description add to alt img attribute"
}
}
const card2: Card = {
title: "Card 2 title",
text: "Card 2 description",
actions: [
{
type: "LINK",
title: "Click here",
url: "https://...",
}
],
image: {
url: "https://...",
description: "Image description add to alt img attribute"
}
}
const carousel: Carousel = { cards: [ card1, card2 ] }
client.pushCardBundleInConversationThread(carousel)
Result
pushCardBundleInConversationThread
getJWT
  • Allows the CPA to get a secured JWT token. This JWT is signed with the secret token defined in the connector of the CPA.
Signature
function getJWT(): Promise
Example
// use jwtToken on CPA for secure request
client.getJWT().then((jwtToken: string) => { / use JWT token / })
pushApplePayPaymentRequestInConversationThread
  • Allows the CPA to send an Apple Pay Payment request to the active conversation thread.
  • The CPA can only send an Apple Pay Payment request to a conversation from an Apple channel.
Signature
type ApplePayPaymentRequestType = {
requestIdentifier: UUID;
payment: ApplePayPaymentRequest;
receivedMessage: ApplePayReceivedMessage;
}
// Detail for payment field type
type ApplePayPaymentRequest = {
currencyCode: string;
lineItems: PaymentItem[];
requiredBillingContactFields: ApplePayContactField[];
requiredShippingContactFields: ApplePayContactField[];
shippingMethods: ShippingMethod[];
total: PaymentItem;
}
type PaymentItem = {
amount: string;
label: string;
type: ApplePayLineItemType;
};
enum ApplePayLineItemType {
final,
pending,
}
type ShippingMethod = {
amount: string;
detail: string;
identifier: string;
label: string;
};
enum ApplePayContactField {
email = 'email',
name = 'name',
phone = 'phone',
postalAddress = 'postalAddress',
phoneticName = 'phoneticName',
}
// type for receivedMessage field
type ApplePayReceivedMessage = {
type: 'CARD';
data: CardType;
}
type CardType = {
title?: string;
text?: string;
image?: CardImage;
actions: LinkAction[];
};
type CardImage = {
url: string;
description: string;
};
type LinkAction = {
type: 'LINK';
title: string;
url: string;
};
// Error
type ActionError = {
message: string;
details?: string[];
}
function pushApplePayPaymentRequestInConversationThread(applePayPaymentRequest: ApplePayPaymentRequestType): Promise
Note
If the request of payment is not sent, you may have an error in your request payload. To help you fix your payload, you can catch the error Promise: an ActionError is available with more details on what's happening.
More details about the ApplePayPaymentRequest type are provided in the official Apple developer documentation.
Example
const applePayPaymentRequest: ApplePayPaymentRequestType = {
requestIdentifier: "83f86edb-XXXXX", // UUID
payment: {
currencyCode: "USD",
lineItems: [
{
amount: "45",
label: "Earpods",
type: "final"
},
{
amount: "955",
label: "iPhone 12 mini",
type: "final"
}
],
requiredBillingContactFields: ["email"],
requiredShippingContactFields: ["email"],
shippingMethods: [
{
amount: "10",
detail: "Available within an hour",
identifier: "in_store_pickup",
label: "In-StorePickup"
}
],
total: {
amount: "1000",
label: "TOTAL",
type: "final"
}
},
receivedMessage: {
type: "CARD",
data: {
title: "Please check this payment request",
text: "Check this payment request and choose your shipping method",
actions: [],
style: "icon"
}
}
}
client.pushApplePayPaymentRequestInConversationThread(applePayPaymentRequest)
.then(() => /* success apple pay payment request */)
.catch((error: ActionError) =>
/* error.message -> Error on command request */
/* error.details (if exists) -> More details about the error if it exists */
)
Result