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:
Send invitations in a new tab (video assistance scenario only)
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 |
---|---|
| Recipient's phone number |
| any custom reference needed |
| Recipient's name |
| Text |
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.
Agent-side video interface as an iframe
The agent-side interface is accessible at https://apirtc.github.io/web-agent/. It is a web application configured through search query parameters. Find the list of all the available parameters on the app's GitHub page.
For example, https://apirtc.github.io/web-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 :
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":
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)
Find the list of all the available events and the fields of each event on the [GitHub repo](https://github.com/apirtc/web-agent#complete-list-of-messages) of the agent-side app.
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:
Find the list of all the available actions and the list of fields for each message type on the [GitHub repo](https://github.com/apirtc/web-agent#complete-list-of-messages) of the agent-side app.
The host application must wait for a message of type `ready` from the agent-side app before starting to post any message.
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:
loaderAgent module in 3rd-party applications
This integration option is only available for video assistance scenarios.
Your page should include the loaderAgent.js library:
This script file provides the loadAgent
function with the following prototype:
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 informationagentAppCallback
: [optional] a function called when an event is raised (callback)useFrame
: [optional] to allow the use of iframe during the callagentParams
: [optional] a structure containing additional parameters
Before being able to call the loadAgent
function, you must go through 2 steps:
Retrieve a token for the agent with the endpoint
/token
(see authentication)Use the endpoint
/v2/users/me
to retrieve the user info.
Example:
Response:
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:
Event List
Event type | Description | Params |
---|---|---|
| Agent is loaded and ready to work. | -- |
| Fired when a new box container has been created. |
|
| Fired when a box is opened. | jQuery object of the box container |
| Fired when a box is minimized. |
|
| Fired when a box is maximized. |
|
| Fired when a box is closed. |
|
| Fired when the page has been reloaded into navIframe. | -- |
| Fired when a new message is shown. |
|
| Fired when a message is sent |
|
| Fired when the presence information of other users changes : online / offline |
|
Code example
Example of use with the previously retrieved parameters:
Last updated