Oct8ne API for custom CSM integration

oct8ne’s proprietary coviewing technology allows companies to provide customers with a personalized in-store experience online. Agents and customers view products and search for together, creating opportunities for increased sales as agents upsell and cross-sell in real-time. Unlike traditional live chat services, oct8ne equips agents with tools to engage in sales while providing expertise. Post-visit sales intelligence and analytics allow companies to continuously optimize their sales process.

This is a lightweight component that can be integrated in any web eCommerce platform and is distributed following the SaaS (Software as a Service) model.

The purpose of this document is to provide software architects, engineers and developers with useful technical information to integrate oct8ne in your eCommerce platform.

Note: There are free official extensions and plug-ins for some of the main eCommerce platforms, providing easier integration with these products without needing custom developments. Before you begin to develop your custom solution, please review the available platforms on the product’s website, www.oct8ne.com.

In order to provide an overview of the system, oct8ne’s architecture and where each of its components fit in a common usage scenario is briefly described first.

Next follows a high-level description of the oct8ne installation process on eCommerce platforms, including the basic aspects of creating custom adapters for non-standard platforms.

Subsequently, the API, methods and data structures used are described in detail. These will enable you to build adapters to achieve a perfect integration of oct8ne with any platform.

If you have any questions or suggestions, please do not hesitate to contact us at devsupport@oct8ne.com, where you will obtain customized technical support.

Thank you for using the oct8ne API.

Happy coding!

Architecture

The following are the main components of oct8ne:

oct8ne platform: made up by the set of server components hosted on the oct8ne infrastructure which provide web and real-time services to the rest of elements.
oct8ne widget: consists of the HTML, CSS and JavaScript elements that, embedded in your eCommerce platform, will enable the oct8ne features. Further below, how to enter this component on your platform is described.
oct8ne adapter: the add-on specifically developed for the eCommerce platform with which you wish to integrate oct8ne. It resides within its infrastructure and in most cases will use the same technology stack as the eCommerce platform with which it is integrated (.NET, PHP, Java, etc.).

Note: If you wish to integrate oct8ne with your eCommerce platform, you only need to develop this component. The rest is provided by oct8ne.

The following diagram represents these components, their location and the connections between them in the context of a generic eCommerce system operating with oct8ne:

As you can see in the above diagram, neither the widget nor the oct8ne platform itself will ever interact directly with your eCommerce system; they always do so via the extension specifically designed for it. This architecture allows the oct8ne solution to be adaptable to any eCommerce platform, regardless of the technology on which it is built.

Overview

The integration of oct8ne in an eCommerce platform will follow the procedure below:

Downloading and installing plug-ins and extensions

If your eCommerce platform has specific adapters, you will normally find them in the plug-ins and extensions gallery or on the website of their developers, although the exact location will vary depending on the platform. For more information please refer to your platform manual or documentation.

Please follow the instructions provided by the developer of the extension. The installation process is typically straightforward and it allows a swift implementation of oct8ne on your system.

Registering as a developer and enabling the platform

In order to have access to the API and to a test account that will allow you to develop your oct8ne adapters, you will need a developer account.

You can request one by sending an email to devsupport@oct8ne.com with your contact information and a brief description of the project that you wish to develop. You will receive a reply with your credentials to access the test infrastructure and all the additional information needed to integrate oct8ne with your platform.

Inserting the oct8ne widget

To enable the services of oct8ne on your eCommerce platform, you must enter the following script code so that it is present on all pages where you wish these services to be available. Usually, this can be achieved by entering the script in the layout or master page of your website, although there could be other ways to do it depending on the platform.

var oct8ne = document.createElement("script");

oct8ne.type = "text/javascript";

oct8ne.server = "OCT8NE-SERVER-HERE";

oct8ne.src =
(document.location.protocol=="https:"?"https://":"http://")
+ [OCT8NE-STATIC-SERVER-HERE]api/v2/oct8ne.js'
+ '?' + (Math.round(new Date().getTime() / 86400000));

oct8ne.async = true;

oct8ne.license = "YOUR-LICENSE-HERE";

oct8ne.baseUrl = "//yourdomain.com";
oct8ne.checkoutUrl = oct8ne.baseUrl + "/checkout";

oct8ne.loginUrl = oct8ne.baseUrl + "/login";
oct8ne.checkoutSuccessUrl = oct8ne.baseUrl + "/checkout/success";

oct8ne.locale = "en-US";

oct8ne.currencyCode = "USD";

oct8ne.apiVersion = "2.4";

oct8ne.currentProduct = {
id: "84",
thumbnail: "http://myserver.com/img/thumbs/84.jpg"
};

var s = document.getElementsByTagName("script")[0];

s.parentNode.insertBefore(oct8ne, s);

</script>

Nota: Value [OCT8NE-STATIC-SERVER-HERE] is supplied upon registration as a developer.

A good location for this portion of script could be just before closing the <BODY> tag of your website, although in any case it will depend on how your website is laid out.

In this script code it is required to set the correct value of the following properties:

Required properties
server	string	Server address code that was supplied upon registration as a developer.
src	String	Absolute URL to the oct8ne API scripts file, which will be made available upon registration as a developer. It may be different than the one that will be provided in production environments. In the above code snippet an additional parameter is added to the URL to make the visitor load the latest version of the script at least once a day.
license	String	License code that was supplied upon registration as a developer.
baseUrl	String	Absolute URL of the root of the website.
checkoutUrl	String	Absolute URL of the eCommerce platform page to which the customer must be redirected to finalize his/her purchase.
loginUrl	String	Absolute URL of the user login page on the eCommerce platform.
checkoutSuccessUrl	String	URL of the page shown just after the order has been placed, usually used to thank the user for purchasing and give him/her information useful for tracking the order.
locale	String	Active locale for the eCommerce platform current user, for example “en-US” or “es-ES”.
currencyCode	String	Currency code for the current user, for example “USD” or “EUR”.
apiVersion	String	Version of the api implemented by the adapter. In this document, it corresponds to the version: "2.4"
currentProduct	object	Object that describes the product that is being displayed, through the properties: id (product identifier) thumbnail (product thumbnail URL).

Note: You must set the currentProduct property when the current page corresponds to a product, so that oct8ne can record the product information. Otherwise, it is not necessary to define it.

There are other properties that can be set, and it is even recommended that you do so, to achieve a better integration of oct8ne in your eCommerce platform. They will be described further below, in the chapter “Advanced oct8ne integration”.

Creating a custom adapter

oct8ne offers an application programming interface (API) that allows integrating your collaboration and support services in any kind of third-party platform through the implementation of a custom adapter.

Creating an adapter for a particular eCommerce platform consists of implementing (using the most suitable technology in each case) a component hosted in its infrastructure that is capable of publishing a series of methods defined by the oct8ne API via the HTTP protocol. This is for the purpose of exchanging information with the platform for which it was built, and with the rest of the oct8ne components (described above).

Invocations to these methods occur upon certain actions of the user or the system itself. For example, when the user does a search in the oct8ne interface, the widget establishes communication with the eCommerce adapter. It is the latter that uses the means available on the platform to obtain and return the results back to the widget, and the widget finally displays them on screen for the user.

Another example of interaction occurs when oct8ne needs to know which products are related to a specific product. In this case, the widget will request said information from the adapter, which will retrieve it from the eCommerce system and return it to the widget so that it can display it to the user.

The oct8ne adapters for eCommerce platforms must implement all the methods defined by the API. They will be invoked by oct8ne:

Methods	Components involved	When it occurs
productInfo	Widget→Adapter	oct8ne needs to obtain all the details of a product to show it to the user.
productSummary	Widget→Adapter	oct8ne needs to obtain summary information of a product.
search	Widget→Adapter	The user searches for a product using the built-in oct8ne search provider.
customerData	Widget→Adapter	oct8ne needs to update the session state of the user currently logged into the eCommerce platform.
addToWishlist	Widget→Adapter	The user adds an item to his/her wish list of products via the oct8ne interface.
getAdapterInfo	Platform→Adapter	The platform needs to obtain information about the adapter.
getOrders	Platform→Adapter	List of orders made by the customer, this list is shown to the agent.
getOrderDetails	Platform→Adapter	Detail of an order made by the customer, this detail is shown to the agent.

Note: The system may not perform correctly if any of these methods are not implemented in the adapter.

Additionally, there are advanced integrations that allow achieving a better oct8ne user experience, covering some more sophisticated scenarios. They will be described in Chapter 5, “Advanced oct8ne integration”.

Integration using the oct8ne API

General notes on implementation

This section describes some important details that affect all the methods and calls of the oct8ne API.

Using JSONP

In order to prevent any problems with calls from different origins, the oct8ne API uses the JSON with padding technique, also known as JSONP (http://en.wikipedia.org/wiki/JSONP), at almost all its entry points.

Thus all the calls made from the oct8ne widget to the adapter of your platform may include the additional parameter callback, which contains the name of the function that will be executed on the client side when the response is received. From your adapter, you will simply have to return the JSON content with the following structure:

<callbackFunction>( <jsonData> );

For example, an adapter API method that receives the value "myFunc" as the callback parameter could return the following content, always with the content-type set to “application/javascript”:

myFunc({
productCount: 0,
error: false
})

Due to the use of JSONP, the oct8ne widget uses the HTTP verb GET to make queries to the adapter.

If the parameter callback is not present, the data must be returned using raw JSON (content-type “application/json”) as shown below:

{
productCount: 0,
error: false
}

Path of calls to the adapter

The current version of the oct8ne API requires all the methods of the adapter to be located in a predetermined path, /oct8ne/frame/<method>.

In future versions of the API, you will be able to modify it and adapt it to your schema of paths or needs, but for now, this possibility is not available. They must be ‘case insensitive’. So, they must work whether they are invoked with upper- or lower-case letters.

E.g.:’/oct8ne/frame/productInfo’ and ’/oct8ne/frame/productinfo’ must should work in the same way.

The “productInfo” method

This adapter method is invoked by the oct8ne widget each time the complete information of a product is needed. All the adapters must implement this method.

URL
<yourserver.com>/oct8ne/frame/productInfo
Input parameters
productIds	Identifiers in the platform for the products whose data are to be obtained, separated by the comma character.
locale	Locale to be used to format the query results, for example “en-US” or “es-ES”. If empty, the default locale will be used.
currency	Currency to be used to get the product prices, for example “USD” or “EUR”. If empty, the site’s default currency will be used.
Sample requests
GET http://www.myserver.com/oct8ne/frame/productInfo?productIds=1&callback=myFunc GET http://www.myserver.com/oct8ne/frame/productInfo?productIds=1,2&callback=myFunc GET http://www.myserver.com/oct8ne/frame/productInfo?productIds=1&callback=myFunc &locale=en-US&currency=USD
Sample response (JSONP)
myFunc([ <ProductInfo-1>, <ProductInfo-2>, ... <ProductInfo-N>, ])

Note: Remember that the response must return an array of products with the "ProductInfo" structure, described below.

The ProductInfo structure

Contains information about a product.

ProductInfo

internalId

String

Internal identifier of the product in the eCommerce platform.

title

String

Product name or title.

description

String

Extended description text for the product. It must be suitable for display on a webpage (for example, line breaks should be converted to <br/> tags before returning it).

formattedPrice

String

Final price of the product. It must be formatted before returning it to the widget, for example, by entering commas to separate thousands and periods to separate decimals, and adding the currency suffix or prefix, attending to the value of the “locale” and “currency” query parameters.

If you don’t want oct8ne show the product price, simply set this value as null.

formattedPrevPrice

String

Price of the product before applying the discount. If the product does not have a discount, it contains the same value as the price property. It must be formatted before returning it to the widget, according to the value of the “locale” and “currency” query parameters.

productUrl

String

Absolute URL to the product details page, from which it can be added to the shopping cart by selecting the necessary attributes (size, color, etc.).

addToCartUrl

String

Absolute URL to which a request must be sent to add the product to the shopping cart. It is compulsory when useProductUrl is false—in this case, when the customer adds a product to their shopping cart using oct8ne, the widget will make an AJAX request to this address.

By default, the HTTP verb to be used in the AJAX request will be “POST”. However, it is possible to modify it by setting the following property on the oct8ne object of the widget:

var oct8ne = document.createElement("script");

...
oct8ne.addToCartHttpVerb = "GET";
...
</script>

useProductUrl

Boolean

It must be true if the product must be added to the shopping cart redirecting the user to the product’s page in the eCommerce platform. It will happen, for example, if the product has attributes that must be selected before being added to the shopping cart, such as size or color.

If it is false, the widget will make an AJAX request to add the product to the shopping cart, as it is described in the addToCartUrl property.

thumbnail

String

Absolute URL to the product thumbnail. It can have any size, but for optimal viewing a height and width of 120px is recommended.

medias

Array

Array of Media objects with the product images. It must contain at least one item, which will be the one used as the default image of the product. The images referenced can have any size, but for optimal viewing a maximum height and width of 800px is recommended.

The following code snippet shows a ProductInfo object:

{
internalId: "23",
title: "Product title",
description: "This is the <b>product description</b>",
formattedPrice: "1,500.00 €",
formattedPrevPrice: "2,000.00 €",
useProductUrl: true,
productUrl: "//myserver.com/cart/add/23",
addToCartUrl: "//myserver.com/cart/ajax/add/23",
thumbnail: "//myserver.com/thumbs/23.jpg",
medias: [
{ url: "//myserver.com/images/23-1.jpg"},

{ url: "//myserver.com/images/23-2.jpg"},

{ url: "//myserver.com/images/23-3.jpg"}

]
}

The Media structure

Contains information about an image or resource of a product.

Media
url	String	Absolute URL to the image or resource.

{
url: "//myserver.com/images/23-3.jpg"
}

The “productSummary” method

This adapter method is invoked by the oct8ne widget when summary information of a product is needed. All the adapters must implement this method.

URL
<yourserver.com>/oct8ne/frame/productSummary
Input parameters
productIds	Identifiers in the platform for the products whose data are to be obtained, separated by the comma character.
locale	Locale to be used to format the query results, for example “en-US” or “es-ES”. If empty, the default locale will be used.
currency	Currency to be used to get the product prices, for example “USD” or “EUR”. If empty, the site’s default currency will be used.
Sample requests
GET http://www.myserver.com/oct8ne/frame/productSummary?productIds=1&callback=myFunc GET http://www.myserver.com/oct8ne/frame/productSummary?productIds=1,2&callback=myFunc GET http://www.myserver.com/oct8ne/frame/productSummary?productIds=1&callback=myFunc &locale=es-ES&currency=EUR
Sample response (JSONP)
myFunc([ <ProductSummary-1>, <ProductSummary-2>, ... <ProductSummary-N>, ])

Note: Remember that the response must return an array of products with the "ProductSummary" structure, described below.

The ProductSummary structure

This structure contains summary information about a product.

ProductSummary
internalId	String	Internal identifier of the product in the eCommerce platform.
title	String	Product name or title.
formattedPrice	String	Final price of the product. It must be formatted before returning it to the widget, for example, by entering commas to separate thousands and periods to separate decimals, and adding the currency suffix or prefix, attending to the value of the “locale” and “currency” query parameters. If you don’t want oct8ne show the product price, simply set this value as null.
formattedPrevPrice	String	Price of the product before applying the discount. If the product does not have a discount, it contains the same value as the price property. It must be formatted before returning it to the widget, according to the value of the “locale” and “currency” query parameters.
productUrl	String	Absolute URL to the product details page, from which it can be added to the shopping cart by selecting the necessary attributes (size, color, etc.).
thumbnail	String	Absolute URL to the product thumbnail. It can have any size, but for optimal viewing a height and width of 120px is recommended.

The following code snippet shows a ProductSummary object:

{
internalId: "23",
title: "Product title",
formattedPrice: "1,500.00",
formattedPrevPrice: "2,000.00",
productUrl: "//myserver.com/cart/add/23",
thumbnail: "//myserver.com/thumbs/23.jpg"
}

The “search” method

This adapter method for your eCommerce platform is invoked by the widget each time the user does a product search using any of the tools provided by oct8ne. All the adapters must implement this method.

URL
<yourserver.com>/oct8ne/frame/search
Input parameters
search	Search text.
page	Page number (one-based) to be returned.
pageSize	Page size. The default value is 10.
orderby	Ordering criteria. It must be one of the following values (case sensitive): relevance (default) price name If your eCommerce platform does not implement any of the filters, it must provide a reasonable ordering for the products returned from the search. For example, if there is nothing similar to “relevance” in your platform to order the products, it could return them ordered by update date, price or another criterion that it considers to be more logical in your particular scenario.
dir	Ordering direction. It must be one of the following values (case sensitive): asc (default) desc
locale	Locale to be used to format the query results, for example “en-US” or “es-ES”. If empty, the default locale will be used.
currency	Currency to be used to get the product prices, for example “USD” or “EUR”. If empty, the site’s default currency will be used.
Sample requests
GET http://www.myserver.com/oct8ne/frame/search?search=shoes&page=1&pageSize=10 &callback=myFunc GET http://www.myserver.com/oct8ne/frame/search?search=shoes &locale=es-MX&currency=USD&callback=myFunc
Sample response (JSONP)
myFunc({ total: <number of products found>, results: [ <ProductSummary-1>, <ProductSummary-2>, <ProductSummary-N>, ] filters: <FilterInfo> })

In addition to the previous input parameters, the widget will include the value of the active filters in the call. For example, if you have a single active filter defined with the name “color” and the value “black”, the full call to this method could be the following:

myserver.com/oct8ne/frame/search?search=shoes&start=0&count=10&color=black

The FilterInfo structure

This structure contains information about the applied and available filters in the result of a search.

FilterInfo
applied	Array	Array of <AppliedFilter> objects
available	Array	Array of <AvailableFilter> objects

{
applied: [
<AppliedFilter-1>
<AppliedFilter-2>
<AppliedFilter-N>
]

available: [
<AvailableFilter-1>
<AvailableFilter-2>
<AvailableFilter-N>
]

}

The applied property is optional and, if included, it must contain an array of AppliedFilter type objects, which describe the filters that are being applied in the query.

The AppliedFilter type contains information about a filter currently applied in the query.

AppliedFilter
param	String	Name of the parameter sent to the “Search” method, e.g. “category”.
paramLabel	String	Text to be displayed in the UI to identify this filter criterion, e.g. “Product category”.
value	String	Current value of the filter, e.g. “18”.
valueLabel	String	Text to be displayed that describes the current value of the filter, e.g. “Sports”.

{
param: "category",
paramLabel: "Product category",
value: "18",
valueLabel: "Sports"

}

The following code represents a filter applied where it is being indicated that the criterion used is the “category” field, with a value of “18”. On the screen, it will appear described with the text “Sports”:

The available property of the FilterInfo structure is also compulsory, and it must contain an array of AvailableFilter objects that describe the filters that can be applied to the result of the query.

The AvailableFilter type contains the filters available after doing a search, allowing the user to refine the results. Each platform can define its own filter criteria.

Visually, they are displayed as a series of filtering criteria grouped into categories, followed by the number of items or products that would meet the search criteria if the user decides to select them.

For example, on the screenshot you can see the filters available after searching the text “text”. There are two groups of filters called “Category” and “Price range”. In the first of them you can see the different categories which contain products in whose description the text “text” was found and the number of products available in each of them. In the second group of filters you can see the different price ranges for which there are existing products.

This data structure is described in detail below.

AvailableFilter
param	String	Name of the parameter that will be sent to the “Search” method when this filter is activated, e.g. “price”.
paramLabel	String	Text that appears on the screen, e.g. “Price range”.
options	Array	Collection of FilterOption objects that describe the options available in the filter.
		FilterOption
		value	String	Value of the parameter that will be sent to the “Search” method when the user selects this option, e.g. “1”.
		valueLabel	String	Text to be displayed on the interface, e.g. “0-99”.
		count	String	Number of products that match this search criterion, taking into account the filters applied and the text string to be found.

The following piece of code shows an AvailableFilter object:

{
param: "price",
paramLabel: "Price range",
options: [
{ value: "0", valueLabel: "0-99", count: "1" },
{ value: "2", valueLabel: "200-299", count: "2" },
{ value: "3", valueLabel: "300-399", count: "8" }
]

}

Note: The collection of available filters must include neither the active filter nor those for which no products exist, in order to avoid showing the customer filter options that it would not make sense to select.

The “customerData” method

This adapter method is invoked by the oct8ne widget each time that it is necessary to retrieve the full session state of the current customer, including the currently logged user, the items present in the shopping cart and the items added to their wish list. All adapters must implement this method.

URL
<yourserver.com>/oct8ne/frame/customerData
Input parameters
locale	Locale to be used to format the query results, for example “en-US” or “es-ES”. If empty, the default locale will be used.
currency	Currency to be used to get the product prices, for example “USD” or “EUR”. If empty, the site’s default currency will be used.
No input parameters.
Sample requests
GET http://www.myserver.com/oct8ne/frame/customerData?callback=myFunc GET http://www.myserver.com/oct8ne/frame/customerData?callback=myFunc &locale=es-MX&currency=USD
Sample response (JSONP)
myFunc({ <CustomerData> })

The CustomerData structure

This structure contains the complete state of the user’s session in oct8ne.

CustomerData
id	String	Identifier of the user logged onto the platform, or null if they have not been authenticated.
firstName	String	First name of the user logged onto the platform, or null if they have not been authenticated.
lastName	String	Last name of the user logged onto the platform, or null if they have not been authenticated.
email	String	Email of the user logged onto the platform, or null if they have not been authenticated.
wishlist	Array	Array of ProductSummary objects.
cart	Array	Array of ProductInCart objects.

The following piece of code shows a CustomerData object that represents an authenticated user who has added one product to their wish list and two to their shopping cart:

{
id: "1234",
firstName: "John",
lastName: "Doe",
email: "johndoe@myserver.com",
wishlist: [
<ProductSummary-2>

],
cart: [
<ProductInCart-1>

<ProductInCart-2>

<ProductInCart-N>

]

}

The ProductInCart structure

This structure contains information useful for the user about a product that is present in the shopping cart of the customer of the eCommerce platform. It is a specialization of ProductSummary, so it inherits all the properties of that structure and adds the following:

ProductInCart (inherited from ProductInfo)
qty	Number	Number of items added to the shopping cart.

The following piece of code shows a ProductInCart object:

{

internalId: "23",
title: "Product title",
price: "1,500.00",
prevPrice: "2,000.00",
productUrl: "//myserver.com/cart/add/23",
thumbnail: "//myserver.com/thumbs/23.jpg"
qty: 3

}

The “addToWishlist” method

This method is invoked by the widget when the user adds a product to their wish list using the oct8ne tools. The implementation of this method is compulsory if you wish to integrate the wish list with oct8ne.

URL
<yourserver.com>/oct8ne/frame/addToWishList
Input parameters
productIds	Identifiers in the platform for the products to be added to the user’s wish list, separated by commas.
Sample requests
GET http://www.myserver.com/oct8ne/frame/addToWishList?productIds=3?callback=myFunc GET http://www.myserver.com/oct8ne/frame/addToWishList?productIds=3,8?callback=myFunc
Sample response (JSONP)
myFunc({ result: "true" })

Note: In order to avoid duplicate entries, it is up to the developer to check if the products existed previously in the wish list before adding them.

The “getAdapterInfo” method

This method is invoked from the oct8ne platform and the client side to obtain information about the adapter. All adapters must implement this method.

.URL

<yourserver.com>/oct8ne/frame/getAdapterInfo

Sample requests

GET http://www.myserver.com/oct8ne/frame/getAdapterInfo?callback=myFunc
GET http://www.myserver.com/oct8ne/frame/getAdapterInfo

Sample responses

myFunc({

platform: "Magento",

adapterName: "Oct8ne official adapter for Magento",

adapterVersion: "2.5",

developedBy: "Oct8ne Inc",

supportUrl: "http://www.oct8ne.com/support/magento",

apiVersion: "2.3",

enabled: true

})

{

platform: "Magento",

adapterName: "Oct8ne official adapter for Magento",

adapterVersion: "2.5",

developedBy: "Oct8ne Inc",

supportUrl: "http://www.oct8ne.com/support/magento",

apiVersion: "2.4",

enabled: true

}

The properties of the data structure returned are described below:

AdapterInfo
platform	String	Required. ECommerce platform on which the adapter runs. It may contain the exact version (e.g. “Magento CE 1.9.1”).
adapterName	String	Official name of the adapter.
adapterVersion	String	Required. Development version of the adapter.
developedBy	String	Required. Developer of the adapter.
supportUrl	String	Support URL of the adapter, if any.
apiVersion	String	Required. Version of the oct8ne API used by the adapter. It must coincide with the version of the JavaScript file loaded from the widget.
enabled	Boolean	It contains true if the adapter is enabled on the platform, false otherwise.

The “getOrders” method

This method of the oct8ne platform allows the developers of adapters to give the possibility to the agents to see the history of orders made by a client.

URL
<yourserver.com>/oct8ne/frame/getOrders
Input parameters
customerEmail	Client email that you want see the orders.
apiToken	Security token. You must compare it with the token supplied in the oct8ne register, and only respond to the request if it is correct.
page	Number of page to return. By default 1
pageSize	Page size. By default 10.
locale	Locale to be used to format the query results, for example “en-US” or “es-ES”. If empty, the default locale will be used.
currency	Currency to be used to get the order total amount, for example “USD” or “EUR”. If empty, the site’s default currency will be used.
Sample requests
GET http://www.myserver.com/oct8ne/frame/getOrders ?customerEmail=myemail@web.com &apiToken=C9562C260EE0B82577D9D315F53EBE78 &page=1 &pageSize=10 &locale=es-ES &currency=EUR GET http://www.myserver.com/oct8ne/frame/getOrders ?customerEmail=myemail2@web.com &apiToken=C9562C260EE0B82577D9D315F53EBE78 &page=3 &pageSize=10
Sample response (JSON)
[ { "date":"2019-02-28 16:19:15", "reference":"VFIYYMABU", "total":"55,30\u00a0\u20ac", "currency":"EUR", "labelState":"Waiting for payment by check", "deliveryDate":"" }, { "date":"2019-02-28 16:18:10", "reference":"EASLDSBCM", "total":"170,32\u00a0\u20ac", "currency":"EUR", "labelState":"Pending Shipping", "deliveryDate":"" } ]

Note: If the apiToken received is not correct, this method must return an empty array.

The “getOrderDetails” method

This method of the oct8ne platform allows the developers of adapters to give the possibility to the agents to see the detail of an order.

URL
<yourserver.com>/oct8ne/frame/getOrderDetails
Input parameters
reference	Order identifier
apiToken	Security token. You must compare it with the token supplied in the oct8ne register, and only respond to the request if it is correct.
locale	Locale to be used to format the query results, for example “en-US” or “es-ES”. If empty, the default locale will be used.
currency	Currency to be used to get the order total amount, for example “USD” or “EUR”. If empty, the site’s default currency will be used.
Sample requests
GET http://www.myserver.com/oct8ne/frame/getOrderDetails ?reference=VFIYYMABU &apiToken=C9562C260EE0B82577D9D315F53EBE78
Sample response (JSON)
{ "date":"2019-02-28 16:19:15", "reference":"VFIYYMABU", "total":"55,30\u00a0\u20ac", "currency":"EUR", "labelState":" Waiting for payment by check ", "deliveryDate":"", "carrier":"My carrier", "trackingNumber":"XXXXX", "trackingUrl":"https://mycarrier/orederId/", "products": [ { "quantity":"3", "name":"Brown bear notebook Paper" } ], "comments": [ { "message":"Leave it in the porter", "customer":true } ] }

Note: If the apiToken received is not correct, this method must return an empty array.

Advanced oct8ne integration

The following sections describe additional possibilities when integrating oct8ne with your eCommerce platform:

Session notification with order placed.
Integration of the Phone PIN.
Integration of embedded links.
Real-time update of the oct8ne widget.
Real-time eCommerce update.
Link up.

Suggestion: For an optimal oct8ne user experience, it is recommended that you implement all the integrations described here, even though this is not strictly necessary.

Session notification with order placed

oct8ne lets you know if a chat session with a client has ended with a sale.

To do this, a request must be made to the oct8ne servers by entering a script on the merchant's page where it is known with certainty that a sale has been completed (order confirmation page , etc…). The script must contain the id "oct8ne-sale-notify".

URL
https://[OCT8NE-STATIC-SERVER-HERE]api/source/js/ext/sale-notification.js?license='[YOUR-LICENSE-HERE]'&currencyCode='CURRENCY_ISO_CODE'&locale='LOCALE'&value='CART_VALUE'&reference='ORDER_ID'&customerId='CUSTOMER_ID'&contextInfo='CONTEXT_INFO'
Input parameters
license	License code that was supplied upon registration as a developer.
currencyCode	Currency to be used to get the order total amount, for example “USD” or “EUR”. If empty, the site’s default currency will be used.
locale	Locale to be used to format the query results, for example “en-US” or “es-ES”. If empty, the default locale will be used.
value	Final value of the order placed. Sample: "1237,59 €"
reference	Identifier of the order in the store.
customerId	Customer identifier in the store.
contextInfo	Additional information you want to save. This is a serialized object such as JSON with arbitrary key / value pairs. Sample: "{'key1':'value1','key2':'value2'}"
Sample requests
https://static.oct8ne.com/api/source/js/ext/sale-notification.js ?license=75CDF90D2A40A53A2899175156FE99E4 &currencyCode=EUR &locale=es-ES &value=589,32 € &reference=KHWLILZLL &customerId=382442 &contextInfo={'key1':'value1','key2':'value2'}
Script sample
<script id="oct8ne-sale-notification" type="text/javascript" src=https://static.oct8ne.com/api/source/js/ext/sale-notification.js ?license=C95532140EE0B82566D9D315F53EBE78&CurrencyCode=EUR&locale=es-ES&value=589,32 € &reference=KHWLILZLL&customerId=382442&contextInfo=%7B%27key1%27%3A%27value1%27%2C%27key2%27%3A%27value2%27%7D'> </script>

Note: The only required field is "license" and the script must contain the id

"oct8ne-sale-notification".

Note: The variable [OCT8NE-STATIC-SERVER-HERE] refers to the Oct8ne server on which you are registered.

Oct8ne works with different servers, in the USA and in the EU.

Once inside the Oct8ne control panel, note the address (url) of the browser:

If it is 'backoffice.oct8ne.com', it is the USA server.

If it is 'backoffice-eu.oct8ne.com', the server is EU.

The value of the variable depending on the server is:

In EU [OCT8NE-STATIC-SERVER-HERE]: static-eu.oct8ne.com

In USA [OCT8NE-STATIC-SERVER-HERE]: static.oct8ne.com

Integration of the phone pin

oct8ne allows agents to quickly start a coviewing sales session with visitors who are contacting them by telephone and can be better assisted by added visual support. Upon starting the session, agents will see which products the visitor had already viewed (if applicable) and other details.

To begin a session, the visitor must give the agent a PIN code that will be displayed in a location of the company’s choosing.

The PIN can be located anywhere on the website, on any HTML element, so it is completely customizable. oct8ne will simply search the page for elements with the CSS class “oct8ne-phone” and configure them so that upon clicking, the PIN appears immediately below.

For example, the following code shows how the PIN could be displayed under an image of a telephone aligned to the right of the page:

<body>

...

...

</body>

If you do not wish to apply inline styles you could also use independent CSSs:

HTML:

<body>

...

<img src="http://www.yourdomain.com/images/phone.png"
class="oct8ne-phone">
...

</body>

CSS:

.oct8ne-phone {
float: right;
cursor: pointer;

Integration of embedded links

The developer of an eCommerce platform may create custom links to access the oct8ne coviewer. This allows great flexibility when it comes to adding attractive visual elements to encourage site visitors to contact the sales agents and get advice regarding their purchases.

When there are agents connected, all the elements of the DOM marked with the CSS class “oct8ne-widget-on” will be visible. There are no limitations on the type of HTML element or its location on the page layout—this class can be applied to images, HTML blocks such as DIV or SPAN, or to any other type of tag, and these can be positioned wherever suits your website best. The following piece of code shows an element of this type and its customization using inline styles:

<body>

...

<div class="oct8ne-widget-on"
style="display: none;
position: fixed; top: 0; right: 0; z-index: 9999">
Agents available, chat now!
</div>

...

</body>

When the visitor clicks on the element, the oct8ne viewer will open and a chat session will start with the agent who is available at that time.

Note: You must ensure that these elements are initially invisible on the page using inline styles or CSS sheets, for example by setting their style to display: none. oct8ne will only display them if it detects agents connected on the platform.

In the same way, oct8ne will display all the elements in which the CSS class “oct8ne-widget-off” appears when there are no agents connected. The following code block contains an example of implementation of this link on the page, and its customization via style sheet:

HTML:

<body>

...

<div class="oct8ne-widget-off" id="no-agents">
<p>Contact us
<small>We’ll call you asap</small>
</p>

</div>

...

</body>

CSS:

#no-agents {
display: none;
position: fixed;
z-index: 9999;
right: 0;
top: 0;
}

By default, when a visitor clicks on these elements, the oct8ne contact form will open. If you wish to change this behavior, you may add the class “oct8ne-widget-disabled” and add to the element a custom link, as shown in the example below:

<div class="oct8ne-widget-off oct8ne-widget-disabled">
style="display: none; cursor: pointer;"

<a href="/contact">Contact us</a>

</div>

Inserting the previous code snippet in the page, a link “Contact us” will be shown in the page when no agents are available. When a visitor clicks on that link, he/she will be redirected to the page “/contact” of the web site, instead of opening the oct8ne contact form.

Elements may coexist on the same page that use both classes in order to display one message or the other depending on whether agents are available:

<body>

...

<div class="oct8ne-widget-on" style="display: none">
Agents available, chat now!
</div>

<div class="oct8ne-widget-off" style="display: none">
Contact us!
</div>

...

</body>

The classes can even be combined in the same element to make it visible regardless of whether there are agents or not, with the same text and features:

<body>

...

...

</body>

Real-time update of the oct8ne widget

Information about some actions the visitor may perform on the eCommerce platform should be sent to the oct8ne widget so that it updates the UI and stays synchronized.

For example, this may happen when the user logs in as a client of the platform. Informing the widget of this action would be ideal in order to offer more personalized services. Another instance would be when the customer uses an Ajax button of the eCommerce platform to add a product to their shopping cart or their wish list. In this case, it would again be necessary to notify oct8ne so that the UI displays the new state correctly.

Note: oct8ne reloads the full state of the widget each time the user browses away from the page by calling the “customerData” method, so the state will keep updated in most cases. What is described in this section would be of interest if the UI of your eCommerce platform uses Ajax for operations that modify the system state without leaving the page.

For such scenarios, oct8ne provides a real-time update mechanism that can be invoked at any time from the adapter by making an HTTP request to the oct8ne platform. This request should be executed from the eCommerce platform adapter when one of the state change actions takes place, which will prompt the widget to be updated.

URL
http://backoffice.oct8ne.com/platformConnection/update
Input parameters
visitor	Identifier of the user’s oct8ne session, available in the “oct8ne-visitor” cookie.
what	What you wish to update: “cart”, “wishlist” or “user”.
Sample request
POST http://backoffice.oct8ne.com/platformConnection/update?visitor=3847&what=cart
Sample response
This method does not return any value.

Internally, the invocation of this method will prompt the oct8ne platform to use its real-time messaging infrastructure to notify the widget that its state needs to be updated. Upon receiving said notification, the widget will invoke the adapter to obtain the new state, and it will update the UI accordingly.

It is important to take into account that this update will only take place when there is a real-time connection between the visitor and the oct8ne platform, and this happens only when the visitor has started communication with a sales agent of the store.

Note: You can easily detect whether the agent and the visitor are communicating, since in these instances the “oct8ne-visitor” cookie always contains a character string that identifies the connection. Therefore, if this cookie does not contain any value, it is unnecessary to make the request.

In cases where there is no real-time connection open, the update could be forced from the client side by calling the update() method of the oct8ne object, as in the following example:

function ajaxAddToCart(productId) {
$.ajax( // Adds the product to the cart
...
)
.done(function(result) { // If the operation succeeds,
oct8ne.update("cart"); // refresh oct8ne widget status
});
}

The update() method supports a parameter through which it is possible to specify what information of the widget has to be updated. The values permitted are identical to those of the what parameter of the aforementioned HTTP call.

Real-time eCommerce update

In a similar way to the situation described in the previous section, the visitor sometimes performs actions using oct8ne which should be notified to the eCommerce platform so that it updates the UI and keeps the state synchronized between both systems.

For example, this situation may occur in eCommerce platforms where the contents of the shopping cart are always visible. In this scenario, if the customer adds a product to the cart using the button available in the oct8ne widget, the contents of the eCommerce shopping cart will not be updated until the page is refreshed or the user browses away from the page.

To achieve a better integration in such scenarios, oct8ne offers a mechanism of callbacks by which the developer of the adapter can take control when the user performs these actions using the widget and ensure the synchronization of the eCommerce interface with the new system state, for example by updating the contents of the shopping cart on the page via Ajax.

The callbacks are available in the oct8ne object entered in the pages, and they can be used as shown in the following piece of code:

var oct8ne = document.createElement("script");
...
oct8ne.onProductAddedToCart = function(productId) {
// The product has been added to the cart using oct8ne
// Update the ecommerce’s UI here
};
oct8ne.onProductAddedToWishList = function(productId) {
// The product has been added to the wish list using oct8ne
// Update the ecommerce’s UI here
};
...
</script>

Note: Please bear in mind that these callbacks are invoked by the widget once the product has been added to the shopping cart or the wish list, so the product must not be added again inside it.

Link up

This method, available on the oct8ne platform, allows developers of adapters to automate the process of registering and obtaining the license identifier and security token of the API. It can be of interest especially if you wish to build a plug-in or extension of a standard eCommerce system and provide its managers with an automatic installation mechanism, normally executed after the download of the component from a gallery of extensions.

Note: You should only implement this method if you are creating a plug-in or extension for a standard platform and you wish to include in it an auto-installation process.

In such cases, link up will be a required step that will have to be performed before being able to use oct8ne on the platform.

URL
https://backoffice.oct8ne.com/platformConnection/linkup
Input parameters
email	Email account which the oct8ne user account was registered with.
pass	User’s password to access oct8ne.
platform	Name of the platform, e.g. “Magento”, “WooCommerce”, etc. In the case of a custom development, use “Custom”. Please review the developer support information for other scenarios.
urlDomain	Full base URL of the eCommerce system, including the protocol, e.g. “http://www.mycommerce.com”.
statusPlatform	Boolean value ("true" or "false") indicating whether oct8ne is enabled on the page at the time the link up is performed.
Sample request
POST https://backoffice.oct8ne.com/platformConnection/linkup content-type: application/x-www-form-urlencoded email=johndoe@gmail.com&pass=mysecurepass&platform=woocommerce &urlDomain=http://www.myecommerce.com&statusPlatform=false
Sample response (JSON)
{ apiToken: "61958072EB8B476EBF5D6F77F66384AC", licenseId: "3BDFF5329C414EBCB116CCE1CE1AD807", server: "subdomain.domain.com/", urlStatic: "otrosubdomain.domain.com/" }

Note: The values returned by this method must be stored by the adapter for their subsequent use when generating the script of the oct8ne widget, when calling certain methods or when performing security checks.

Support

We would appreciate your suggestions and comments. Please send feedback, notification of bugs, or a request to obtain customized technical support to: devsupport@oct8ne.com.

Release notes

Version 2.4

The following changes have been added since the previous API version.

Added the new method GetOrders to the API.
Added the new method GetOrderDetails to the API.
Removed the section relative to the configuration of the “assisted search”
Added the new required variable apiVersion to the Javascript code

Note: If you are upgrading from previous versions, please remember to set the API version in the GetAdapterInfo method to “2.4”.

Version 2.3

The following changes have been added since the previous API version.

Added the new required variable checkoutSuccessUrl to the Javascript code.
Added the new method GetCart to the API.
Added in rev03: The main Javascript file is now downloaded from the CDN “static.oct8ne.com”.

Note: If you are upgrading from previous versions, please remember to set the API version in the GetAdapterInfo method to “2.3”.

Version 2.2

The following changes have been added since the previous API version.

Added to the Javascript code the new required variables currencyCode and locale, specifying the currency and locale that are currently in use.
The productInfo, productSummary, search, productRelated and customerData methods accept the new optional parameters “currency” and “locale”, specifying the currency and locale to be used.
price and prevPrice fields have been removed from the ProductInfo and ProductSummary objects.
The field rating has been removed from the ProductInfo object.
ProductInfo and ProductSummary objects contains now the new fields formattedPrice y formattedPrevPrice where we can find the fully formatted prices of the products, taking into account the currency and locale specified in the query.

Note: If you are upgrading from previous versions, please remember to set the API version in the GetAdapterInfo method to “2.2”.

Version 2.1

The following changes have been added since the previous API version.

The Search method now returns ProductSummay objects.
The GetAdapterInfo method now includes the field enabled, that allows knowledge of whether or not the adapter is active in the platform.
All methods now return data in JSON or JSONP format depending on the existence of the callback parameter.
The method GetReportData has been removed.
The method GetSalesReport, that captures sales information has been included.
The methods CustomerData and ProductRelated now use the ProductSummary data structure.
The new method ProductSummary captures product summaries.
The cookie “TokenVisitor” has been renamed to “oct8ne-visitor”.

Related Articles
API for sending transactional or bulk messages from WhatsApp
Introduction WhatsApp Delivery API allows you to automate the delivery of WhatsApp templates via Oct8ne. The following operations are available: Send template to WhatsApp Get delivery status Get deliveries Get message details Security All API calls ...
Integration with Google Analytics version 4 (GA4)
Introduction Oct8ne allows direct integration with Google Analytics version 4 (GA4) through event submission. These provide vital information about the interactions that take place within Oct8ne, which you can check in your Google Analytics ...
Instal Oct8ne into your website
Oct8ne can be integrated into any website in three different ways depending on your platform and needs. 1.- By code: To do this you must first register on the Oct8ne website. Then you can access the control panel and from the Management --> ...
Customised or personalised triggers
Oct8ne triggers offer the possibility of interacting with the visitor when specific circumstances previously defined in the ‘Triggers’ section of the Oct8ne dashboard (for example: time on the page or a specific URL address) occur. But sometimes ...
Oct8ne custom widget design
WHAT IS THE EMBED LINK? Developers can create custom links to access the Oct8ne coviewer. This allows you to have more flexibility when adding visuals to your website to make it attractive and encourage your potential customers to contact agents for ...

Oct8ne API for custom CSM integration

Oct8ne API for custom CSM integration

Introduction

Architecture

Overview

Downloading and installing plug-ins and extensions

Registering as a developer and enabling the platform

Inserting the oct8ne widget

Creating a custom adapter

Integration using the oct8ne API

General notes on implementation

Using JSONP

Path of calls to the adapter

The “productInfo” method

The ProductInfo structure

The Media structure

The “productSummary” method

The ProductSummary structure

The “search” method

The FilterInfo structure

The “customerData” method

The CustomerData structure

The ProductInCart structure

The “addToWishlist” method

The “getAdapterInfo” method

The “getOrders” method

The “getOrderDetails” method

Advanced oct8ne integration

Session notification with order placed

Integration of the phone pin

Integration of embedded links

Real-time update of the oct8ne widget

Real-time eCommerce update

Link up

Support

Release notes

Version 2.4

Version 2.3

Version 2.2

Version 2.1

Related Articles

API for sending transactional or bulk messages from WhatsApp

Integration with Google Analytics version 4 (GA4)

Instal Oct8ne into your website

Customised or personalised triggers

Oct8ne custom widget design