ApiRTC
BlogSupportSign UpConsole
  • ApiRTC Developer Portal
  • Status Page
  • What is ApiRTC?
    • Key Concepts
    • ApiRTC Architecture
    • Supported browsers
      • Vintage Browsers Compatibility
    • Billing
    • Product Roadmap and releases
  • Terms & Privacy Policies
    • 🍪Cookies
  • Get help & support
  • ApiRTC JS Library
    • QuickStart Guide
    • Where to find ApiRTC library?
    • Developers Guide
    • Video Communication LifeCycle
    • Demo App & Resources
    • Authentication
    • SDKs & Frameworks
      • ReactJS Libraries
        • Getting Started with ApiRTC React Hooks
        • ApiRTC React Hook Lib Reference
      • ReactNative library
      • Android SDK Reference
      • iOS SDK Reference
    • ApiRTC.js Reference
    • Changelog
  • REST APIs & Integration
    • Introduction
    • Apizee REST APIs
    • 3rd-party software integration
    • Webhooks
    • Rate Limits
    • Try it out
  • Other Resources
    • SDK License Agreement
    • ApiRTC Website
    • Blog
    • ApiRTC Community Github
Powered by GitBook
On this page
  • Send invitations from a new tab
  • Available parameters
  • Send invitations from an iframe
  • Open the video assistance room in a new tab
  • Agent-side video interface as an iframe
  • Dynamic control
  • loaderAgent module in 3rd-party applications
  • Agent Event Callback
  • Event List
  • Code example
Edit on GitHub
  1. REST APIs & Integration

3rd-party software integration

Apizee video capabilities can be integrated into any business platform.

PreviousApizee REST APIsNextWebhooks

Last updated 1 month ago

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

In this page, you will find several ways of integrating the Apizee solution into 3rd-party software:


Send invitations from a new tab

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.

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

This integration doesn't require backend service to authenticate against Apizee services. only the user would need to sign-in.

Available parameters

Add the following parameter in the query parameters in the URL to pass information or configure behavior of the invitation form:

Parameter
Description
Format
Behavior

reference

Displays a non-editable label with a client reference.

String (max 50 characters)

If provided, displays the reference as a label. Strings longer than 50 characters are truncated. Not displayed if no service is preselected.

service_key

Preselects a service in the invitation dropdown.

Alphanumeric (32 characters)

If valid, the corresponding service is preselected. If invalid, no preselection occurs, and a warning is logged. Overrides previously used services.

phone_numbers

Prepopulates the "Invited Guests" field with phone numbers.

Comma-separated phone numbers

Valid numbers are added to the field. Invalid numbers are flagged with an error.

email_addresses

Prepopulates the "Invited Guests" field with email addresses.

Comma-separated email addresses

Valid emails are added to the field. Invalid emails are flagged with an error.

read_only.service

Makes the service dropdown field read-only.

Boolean (true or false)

If true, the service dropdown cannot be edited.

read_only.recipients

Makes the recipients field read-only.

Boolean (true or false)

If true, the recipient field cannot be edited.

reference

  • Displays as a non-editable label if provided in the URL.

  • Truncated to 50 characters if the string exceeds the limit.

  • Only displayed and used for services of type video-assistance.

Example
Output

/quick-invitation?reference=ABC123

Displays "Reference: ABC123" as a non-editable label.

/quick-invitation?reference=LongStringExceeding50Chars

Displays the first 50 characters of the reference string.

service_key

  • Preselects the specified service in the dropdown if valid.

  • Overrides previously used services.

Example
Output

/quick-invitation?service_key=9447243e889a783488c4369ccfdc0f4

Preselects the service corresponding to the key.

/quick-invitation?service_key=invalidkey

No service preselected.

phone_numbers

Prepopulates the "Guests" field with valid numbers.

Example
Output

/quick-invitation?phone_numbers=0612345678

Adds 0612345678 to the "Invited Guests" field.

/quick-invitation?phone_numbers=0612,+33612345678

Adds 0612 (flagged as invalid), adds +33612345678.

email_addresses

Prepopulates the "Guests" field with valid email addresses.

Example
Output

/quick-invitation?email_addresses=user@example.com

Adds user@example.com to the "Guests" field.

/quick-invitation?email_addresses=user@,valid@email.com

Adds user@ (flagged as invalid), adds valid@email.com

read_only.service

When true, the service dropdown becomes uneditable.

Example
Output

/quick-invitation?read_only.service=true

The service dropdown is disabled and cannot be changed.


read_only.recipients

When true, the "Guest" field becomes uneditable.

Example
Output

/quick-invitation?read_only.recipients=true

The "Guest" field is disabled and cannot be changed.

Send invitations from an iframe

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://xxx.your-domain.com/quick-invitation" <!-- created CNAME entry to cloud.apizee.com -->
        allow="microphone;camera;geolocation;display-capture"
        allowfullscreen>
</iframe>

Add parameters to the URL to configure the form (see #send-invitations-in-a-new-tab for a complete list of available parameters)

Open the video assistance room in a new tab

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.

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

Agent-side video interface as an iframe

Parameter
stands for
Default
Description

aK*

apiKey

none

cN*

conversationName

empty

the ApiRTC Conversation name, mandatory

cU

cloudUrl

https://cloud.apizee.com

the cloud url

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 guest web application

iI

installationId

APZ_AGENT_

used asused a header for local-storage keysused a header for local-storage keys header for local-storage keys

l

lang

browser config

to force language to fr or en (must be in ISO 639-1 format)

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

  • 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 agent is ready to receive messages

sms_sent

notifies an sms has been sent to guest name and phone with link

snapshot

notifies when a snapshot taken on a Stream from a Contact is received

subscribed_streams

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

configures application

conversation

set Conversation name

guest_data

set guest data

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. 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": "agentxxx@apizee.com"
    }

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);

URL format:

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 to get the corresponding steps.

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

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

apiKey, mandatory

For example, configure the application to connect to the conversation named Test with `DemoApiKey` as an apiKey.

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

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

name: string,
phone: string,
link: string
dataUrl: string,
contact: {
    id: string,
    conversationName: string,
    userData: apiRTC.UserData
}
length: Number
installationId: string;
apiKey?: string;
cloudUrl: string;
callStatsMonitoringInterval?: number;
guestUrl: string;
invitationServiceUrl: string;
logLevel: string;
name: string
userId?: string,
username?: string,
name?: string
[key: string]: string | undefined;
https://cloud.apizee.com/quick-invitation
the page dedicated to REST APIs description
the page dedicated to REST API description
https://app.apizee.com/agent/
https://app.apizee.com/agent/?aK=myDemoApiKey&cN=Test
Window: postMessage
ApiRTC
Apizee
contact us
Send invitations from a new tab
Send invitations from an iframe
Open the video assistance room in a new tab
Agent-side video interface as an iframe
Use a loader script to implement a video chat pop in into the 3rd-party app
authentication