3rd-party software integration
Apizee video capabilities can be integrated into any business platform.
Last updated
Apizee video capabilities can be integrated into any business platform.
Last updated
The use of these APIs requires a subscription to Apizee services. Please contact us 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:
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.
URL format: https://cloud.apizee.com/quick-invitation
This integration doesn't require backend service to authenticate against Apizee services. only the user would need to sign-in.
Add the following parameter in the query parameters in the URL to pass information or configure behavior of the invitation form:
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.
/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.
/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.
/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.
/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.
/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.
/quick-invitation?read_only.recipients=true
The "Guest" field is disabled and cannot be changed.
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:
Add parameters to the URL to configure the form (see #send-invitations-in-a-new-tab for a complete list of available parameters)
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.
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.
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.
a
audio
true
set to false to disable audio usage
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 :
Make sure to allow permissions to the Iframe tag.
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
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)
Here's the list of all the available events and the fields of each event of the agent-side app.
ready
N/A
notifies when web-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
The host application can control the agent-side app by using the standard DOM postMessage
method of the Iframe element:
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.
configuration
configures application
connect
N/A
connection with ApiRTC platform
conversation
set Conversation name
disconnect
N/A
disconnect from ApiRTC platform
guest_data
set guest data
join
N/A
join Conversation
leave
N/A
leave Conversation
user_data
set user data
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 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:
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.
This callback function allows executing actions following events raised by the Agent video module.
Define this function before calling it in LoadAgent:
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 }
Example of use with the previously retrieved parameters: