3rd-party software integration

Apizee video capabilities can be integrated into any business platform.

Integrating Apizee in a 3rd-party solution requires you to use the REST APIs to provision for video assistance or a video chat room and get in return a URL to join the room. Please refer to the page dedicated to REST APIs description to get the corresponding steps.

In the examples below, choose the right URL to render either the agent/organizer side or the customer/participant side of the video communication room.

The use of these APIs requires a subscription to Apizee services. Please contact us to get more details on the available offers.

Overview: How to integrate Apizee into 3rd-party software

There are 3 possible scenarios for starting a video assistance session from 3rd-party software:

1. Send invitations in a new tab (video assistance scenario only)

2. Open the video assistance room in a new tab

3. Integrate Apizee agent-side app using an Iframe

4. Integrate the whole Apizee console using an Iframe

5. Use a loader script to implement a video chat pop in into the 3rd-party app

Send invitations in a new tab

This form only works with the video assistance service. Make sure this service is activated in your offer.

Insert a link or a button in the 3rd-party application that redirects the user to a new tab opening the Apizee invitation form.

URL format: https://cloud.apizee.com/tickets/quick-invitation

In a new tab, the user signs on to the Apizee platform (if not already identified) and then uses the form to send invitations to participants.

The form is pre-filled with the phone number passed as a query parameter.

Query parameters (optional):

Parameters	Description	Example
phone_numbers	Recipient's phone numbers	https://cloud.apizee.com/quick-invitation?phone_numbers=0645345643,%2B33656434567
reference	any custom reference needed	https://cloud.apizee.com/quick-invitation?reference=ERZ4534DS

<a href="https://cloud.apizee.com/quick-invitation?phone_numbers=0645345643,%2B33656434567
&reference=ERZ4534DS" target="_blank">
    Invite
</a>

Note that this integration doesn't require backend service to authenticate against Apizee services.

You may also use the link in an iframe tag (see below).

Open a video assistance or a video meeting room in a new tab

Simply retrieve the URL through the REST API (see the page dedicated to REST API description for the detailed steps) and insert it into an anchor link tag in your HTML page.

<a href="<RETRIEVED URL>" target="_blank">Start video chat</a>

Agent-side video interface as an iframe

The agent-side interface is accessible at https://app.apizee.com/agent/ . It is a web application configured through search query parameters. Here's a list of all the available parameters.

Parameter	stands for	Default	Description
a	audio	true	set to false to disable audio usage
aK	apiKey	none	ApiRTC apiKey, mandatory
c	connect	true	Connect with ApiRTC platform
cN	conversationName	empty	the ApiRTC Conversation name
cU	cloudUrl	https://cloud.apizee.com	the cloud url
aN	agentName	empty	name of agent
gN	guestName	empty	guest name to be pre-set in the invitation form
gP	guestPhone	empty	phone number to be pre-set in the invitation form
gU	guestUrl	https://app.apizee.com/guest/?id=invitationId	url of the web-guest web application
iI	installationId	APZ_AGENT_	used a header for local-storage keys
iU	invitationServiceUrl	https://is.apizee.com/invitations	url of the invitation service
j	join	true	Join the Conversation
l	lang	browser config	to force language to fr or en
lL	logLevel	warn	can be debug, info, warn, error
uId	userId	generated by ApiRTC	id of the user-agent that the application will use to connect with ApiRTC

For example, https://app.apizee.com/agent/?aK=myDemoApiKey&cN=Test configure the application to connect to the conversation named Test with `DemoApiKey` as an apiKey.

myDemoApiKey is used as an example, replace it with your own ApiKey. Make sure your account has SMS credits.

To integrate the application within HTML, use an iframe as below :

<iframe
  src="https://app.apizee.com/agent/?aK=myDemoApiKey&cN=Test"
  height="720px"
  width="100%"
  allow="autoplay;microphone;camera;display-capture;encrypted-media;clipboard-write;"
></iframe>

Make sure to allow permissions to the Iframe tag.

Dynamic control

The agent-side application has a real-time messaging feature that enables 2-way communication through the standard Window: postMessage mechanism:

• From the agent-side app to the host platform

• From the host platform to the agent-side app

From the agent-side app to the host platform

To enable the host application to receive events from the agent-side app, it has to register a listener on the window DOM element on events of type "message":

const AGENT_APP_DOMAIN = "https://app.apizee.com";
const receiveMessage = (event) => {
  if (event.origin !== AGENT_APP_DOMAIN) return;

  const message = event.data;

  switch (message.type) {
    case "ready": {
      // web-agent app is ready to receive messages
      break;
    }
    case "snapshot": {
      const dataUrl = message.dataUrl;
      // display or store the snapshot dataUrl.
      break;
    }
    ...
    default:
      console.warn(`Unhandled message.type ${message.type}.`);
  }
};

window.addEventListener("message", receiveMessage);

The received data contains at least a `type` attribute which describes the type of event triggered by the agent-side app.

For example, when a snapshot is taken,

• the agent-side app trigger an event containing a message of type `snapshot`.

• the event holder of the host application catches the event, reads the message's type, and executes the corresponding processing (e.g. grab the dataUrl field of the message and store the image somewhere)

Here's the list of all the available events and the fields of each event of the agent-side app.

message type	field(s)	Description
ready	N/A	notifies when web-agent is ready to receive messages
sms_sent	name: string, phone: string, link: string	notifies an sms has been sent to guest name and phone with link
snapshot	dataUrl: string, contact: { id: string, userData: apiRTC.UserData }	notifies when a snapshot taken on a Stream from a Contact is received
subscribed_streams	length: Number	fired every time the number of subscribed streams changes

From the host platform to the agent-side app

The host application can control the agent-side app by using the standard DOM postMessage method of the Iframe element:

const AGENT_APP_DOMAIN = "https://app.apizee.com";
iframe.contentWindow.postMessage(
  {
    type: "conversation",
    name: "new_conversation_name",
  },
  AGENT_APP_DOMAIN
);

The host application must wait for a message of type `ready` from the agent-side app before starting to post any message.

Here's the list of all the available actions and the list of fields for each message type of the agent-side app.

message type	field(s):type	Description
configuration	installationId: string; apiKey?: string; cloudUrl: string; callStatsMonitoringInterval?: number; guestUrl: string; invitationServiceUrl: string; logLevel: string;	configures application
connect	N/A	connection with ApiRTC platform
conversation	name: string	set Conversation name
disconnect	N/A	disconnect from ApiRTC platform
guest_data	userId?: string, username?: string, name?: string [key: string]: string | undefined;	set guest data
join	N/A	join Conversation
leave	N/A	leave Conversation
user_data	userId?: string, username?: string, name?: string [key: string]: string | undefined;	set user data

Apizee console in an iframe tag

If you don't manage to use the REST API to create a link, you may use the URL of Apizee console.

Prerequisites: If you want to use Apizee in an iframe, there are several prerequisites:

• For security reasons, communicate the domain of your application to our support team, so that we can authorize it

• Create a DNS entry in your application's domain (ex: apizee.your-domain.com) which is a CNAME of cloud.apizee.com. This subdomain / URL will be used when called the iframe

The sample integration code is shown below:

<iframe id="ApizeeApp"
        title="VisioAssistance"
        src="https://apizee.your-domain.com" <!-- created CNAME entry to cloud.apizee.com -->
        allow="microphone;camera;geolocation;display-capture"
        allowfullscreen>
</iframe>

loaderAgent module in 3rd-party applications

This integration option is only available for video assistance scenarios.

Your page should include the loaderAgent.js library:

<script type="text/javascript" src="https://cdn.apirtc.com/agent/loaderAgent.js"></script>

This script file provides the loadAgent function with the following prototype:

loadAgent(serverDomainRoot,
    apiCCkey,
    userInfos,
    agentAppCallback,
    useFrame,
    agentParams);

With:

• serverDomainRoot: Apizee platform url, for example "https://cloud.apizee.com/

• apiCCkey: The apiRTC or Apizee key to be found in your console (https://cloud.apirtc.com/enterprise/api)

• userInfos: javascript structure containing user-related information

• agentAppCallback: [optional] a function called when an event is raised (callback)

• useFrame: [optional] to allow the use of iframe during the call

• agentParams: [optional] a structure containing additional parameters

Before being able to call the loadAgent function, you must go through 2 steps:

1. Retrieve a token for the agent with the endpoint /token (see authentication)

2. Use the endpoint /v2/users/me to retrieve the user info.

Example:

curl -X 'GET' 
    'https://cloud.apizee.com/api/v2/users/me' 
    -H 'accept: application/JSON' 
    -H 'Authorization: Bearer xyzaaa-c900-4dd2-8192-433269xxxxx' 
    -H 'X-CSRF-TOKEN: '

Response:

    {
        "photo_url":
        "https://cloud.apizee.com/img/users/AMN34qakmrBmJWpo/default?t=1689179650",
        "enterpriseId": 1,
        "userId": 3456,
        "apiKey": "7a3dc7993234907508525829e02f2300", //the apiRTC key defined for your enterprise account
        "nickname": "Agent Martin",
        "token": "xyzaaa-c900-4dd2-8192-433xxxxxx",
        "is_agent": false,
        "ccs": "ccs6.apizee.com",
        "mail": "[e-mail]"
    }

The fields userId, apiKey, nickname and token will be necessary to call LoadAgent.

Agent Event Callback

This callback function allows executing actions following events raised by the Agent video module.

Define this function before calling it in LoadAgent:

var agentAppCallback = function agentAppCallback(agent, type, params) {
    switch (type) {
    case "init":
        alert('Agent is loaded');
        break;
    case "updatePresence":
        break;
    ...
    }
};

Event List

Event type	Description	Params
init	Agent is loaded and ready to work.	--
createNewIMDiv	Fired when a new box container has been created.	{ destId:Integer, nickname:String }
openComBox	Fired when a box is opened.	jQuery object of the box container
minimize	Fired when a box is minimized.	destId:Integer
maximize	Fired when a box is maximized.	destId:Integer
close	Fired when a box is closed.	destId:Integer
putInFrame	Fired when the page has been reloaded into navIframe.	--
showNewMessage	Fired when a new message is shown.	{ nickname:String, destId:Integer, message:String, html:String }
sendMessage	Fired when a message is sent	{ destId:Integer, message:String }
updatePresence	Fired when the presence information of other users changes : online / offline	{ eventType:String, time:String, connectedUsersList:Array, state:String }

Code example

Example of use with the previously retrieved parameters:

var serverDomainRoot = "https://cloud.apizee.com/",
    apiCCkey = "YOUR_APIKEY_HERE",
    userInfos = {
            id: 3456, //userId
            token: "xyzaaa-c900-4dd2-8192-433xxxxxx ", // apiKey
            nickname: "Agent Martin",
        };

var useFrame = true;
var agentParams = {
    directory: false,
    directoryStartOpen: false,
    template: 'agent-modern',
    useDefaultTheme: false
    culture: 'en'
};

var agentAppCallback = function agentAppCallback(agent, type, params) {
    switch (type) {
    case "init":
        alert('Agent is loaded');
        break;
    }
};

loadAgent(serverDomainRoot, user.apiKey, userInfos, agentAppCallback,
useFrame, agentParams);