This article relies on the video communication services developed by Apizee.
There are 2 types of video communication service:
Apizee "Video Assistance" : this type of video communication webapp gathers a great set of interaction tools that will empower customer support agents to help their customers.
Apizee "Video Meeting" : this type of video communication service implements a video chat room where an 'organizer' has elevated permissions and where other participants can join the room through different scenario.
The use of these APIs requires a subscription to Apizee services. Please contact us to get more details on the available offers.
Overview
With the Apizee REST APIs, you can:
Authenticate the user (endpoint: /token)
Get a link to a room of type "Video assistance" (endpoint: /tickets)
or
Get a link to a room of type "Video Meeting" (endpoint: /conferences)
In response to the button press, the user may be redirected to the Apizee URL that allows for the video call. They must first identify themselves on Apizee.
Get a "video assistance" room
Retrieving the link to a video assistance room
The Apizee Video Assistance service allows 1-1 interactions between an agent and an assisted customer.
The user journeys of the agent and the assisted customers are different:
For example, the video assistance session on the customer side will automatically start with the rear camera activated (instead of the front camera),
The customer needs to provide their consent before using the service
Video Assistance services rely on the endpoint /tickets
Login (username) of the agent who will handle the request
Email of the assisted customer (mandatory if no phone number provided)
Phone of the assisted customer (use international prefix) (mandatory if no email provided)
To send the invitation to the assisted customer, use the value 1
Custom reference (e.g., to bind the video assistance session to a support case ID or other relevant business ID)
To retrieve the agent's URL, use the value sso
Response:
The response is a JSON object.
Copy {
"id": 82070,
"state": "invited",
"reference": "1234",
"created": "2023-07-12T15:48:11+00:00",
"modified": "2023-07-12T15:48:12+00:00",
"start_time": "2023-07-12T15:48:12+00:00",
"end_time": "2023-07-12T16:18:12+00:00",
"subject": null,
"type": "",
"description": null,
"agent": "arnaud.vallee@apizee.com",
"requestor_url":
"https://diag.apizee.com?convId=88a2c81a-2b5a-496f-8546-0d7bdde8&pwd=798042",
"requestor": {
"phone": "+33662682193"
},
"information_page_url": "https://apz.fr/d6Nx453elx",
"service_key": "115f89503138416a242f40fb7d7f338e",
"agent_url": "https://cloud.apizee.com",
"sso_url":
"https://cloud.apizee.com?access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjbG91ZC5hcGl6ZWUuY29tIiwiaWF0IjoxNjg5MTc2ODkyLCJzdWIiOiJ1c2VyOkFNTjM0cWFrbXJCbUpXcG8iLCJzc28iOnRydWUsImV4cCI6MTY4OTE3NzE5Mn0.L4_xNKE4JdyStmGcJQJqkMeRtDjvnZky9p-cqk9pEEE",
"status": "invited",
"name": null,
"button_id": 223
} The URL to use to reach the agent side is given by the attribute agent_url.
In a 1-1 interaction case, the agent side domain is the Apizee portal (ex: https://cloud.apizee.com ). This domain should be completed to land directly on the related assistance ticket: agentURL /entrypoint/button_id /tickets/id
The URL to reach the assisted customer interface is to be found as a value for therequestor_url attribute.
Get a ticket ID from a reference
If you cannot store the ID corresponding to the ticket, you can use the GET /tickets method
With the reference parameter.
Example
Copy curl -X 'GET'
'https://cloud.apizee.com/api/tickets?orderby=date&order=desc&limit=10&reference=ref12345678'
-H 'accept: application/JSON'
-H 'Authorization: Bearer xyzaaa-2f0f-44ec-8a2e-900faa015ded' The response contains all tickets corresponding to the search criteria:
Copy {
"total": 1,
"data": [
{
"id": 663614,
"state": "done",
"reference": "ref12345678",
"created": "2023-02-22T21:56:34+00:00",
"modified": "2023-07-13T15:49:19+00:00",
"start_time": "2023-02-22T21:56:45+00:00",
"end_time": "2023-02-22T22:12:18+00:00",
"subject": null,
"type": "",
"description": null,
"agent": "agent1@apizee.com",
"requestor_url":
"https://diag.apizee.com?convId=3efcffcc-abc6-4917-b822-e659ea26&pwd=908120",
"requestor": {
"phone": "+33612345678"
},
"information_page_url": "https://apz.fr/d6Nx453elx",
"geoloc": {
"lat": 48.7,
"lng": -3.5
},
"service_key": "115f89503138416a242f40fb7d7f338e"
}
]
} Get the recorded media for a given ticket
(requires having stored the ticket ID or retrieving the ID from a reference -- see above)
Example:
Copy curl -X 'GET'
'https://cloud.apizee.com/api/enterprises/1/tickets/663614/medias'
-H 'accept: application/JSON'
-H 'Authorization: Bearer xyzaaa-2f0f-44ec-8a2e-900faa015ded' The response contains an array of the links to the media
Copy {
"limit": 10,
"offset": 0,
"medias": [
{
"id": 1973404,
"title": "ysExSVPf-2552-477",
"type": "video/mp4",
"hash": "4b6c0600-b2fc-11ed-afc2-a9d424af1014",
"description": null,
"source_type": "unknown",
"url":
"https://cloud.apizee.com/media/showVideo/1/hash/4b6c0600-b2fc-11ed-afc2-a9d424af1014"
},
{
"id": 1973403,
"title": "diag_snapshot_1677103206155",
"type": "image/jpeg",
"hash": "445f0780-b2fc-11ed-89d4-09e76cc8a403",
"description": null,
"source_type": "unknown",
"location": {
"lat": 48.7703337,
"lon": -3.5149756
},
"url":
"https://cloud.apizee.com/media/showVideo/1/hash/445f0780-b2fc-11ed-89d4-09e76cc8a403"
}
],
"count": 2
} Get detailed ticket statistics for a given day
Example
Copy curl -X 'GET'
'https://cloud.apizee.com/api/enterprises/1/tickets-stats?format=JSON&since=2023-07-13&until=2023-07-14'
-H 'accept: application/JSON'
-H 'Authorization: Bearer xyzaaa-2f0f-44ec-8a2e-900faa015ded' The response notably contains the following information for each ticket:
Copy [
{
"ID": 821793,
"Ref": 1234,
"Description": "",
"Priorité": "Immédiat",
"Demandeur": "xx",
"Contact": "+33612345678",
"Etat": "Fermé",
"Assigné à": "Agent 1",
"Groupe": "Support",
"Type": null,
"Date de début de session": "2023-07-13 18:03:13",
"Date de fin": "2023-07-13 18:33:13",
"Répondues": "non",
"Nombre d'invitations": 0,
"Nombre d'invitations email": 0,
"Nombre d'invitations SMS": 1,
"Nombre Appels": 1,
"Durée totale des appels (secondes)": 335,
"Photos": 1,
"Vidéos": 0,
"Identifiant": "agent1@apizee.com",
"Service": "Tickets",
"Scans": 0,
"Appareil": "K",
"Système d'exploitation": "Android 10",
"Navigateur": "Chrome 114.0.0.0"
}
] Get a "video meeting" room (conference)
Retrieving the link
Apizee Meet allows for one-to-one or multi-person face-to-face interactions. The assisted party starts with the front camera.
Apizee Meet relies on the /conferences endpoint.
Parameters
string representing a list of emails or phone numbers separated by commas. (mandatory)
Equals to 1 if the invitation is sent to the participants
When moderation is activated, a participant waits for the moderator's acceptance to enter the room
The name given to this conference room. Can be used to find or identify this conference room
For the details of the available parameters, refer to https://cloud.apizee.com/sdk/api
Example:
Copy curl -X 'POST'
'https://cloud.apizee.com/api/conferences?participants=invite12345%40yopmail.com%2C0612345678&name=TEST&moderation=true&invite=true&moderator=agent1%40apizee.com'
-H 'accept: application/JSON'
-H 'Authorization: Bearer xyzaaa-c900-4dd2-8192-43326929e459'
-H 'X-CSRF-TOKEN: '
-d '' Response
The response is a JSON object.
Copy {
"id": 842199,
"name": "TEST",
"created": "2023-07-13T08:28:31+00:00",
"modified": "2023-07-13T08:28:31+00:00",
"start_time": "2023-07-13T08:28:31+00:00",
"end_time": "2023-07-13T09:28:31+00:00",
"status": "scheduled",
"room_name": "7a3dc7993234907508525829e02f2388:ae226154999f5d50f9e6f909e27c5113",
"url": "https://meet.apizee.com/private/7a3dc7993234907508525829e02f2388/ae226154999f5d50f9e6f909e27c5113",
"short_url": "https://apz.fr/v639BqrklV",
"sip_phone_number": "+33 2 57 57 97 61",
"sip_dtmf_code": "342543",
"organizer": {
"id": 2888,
"name": "Agent 1"
},
"created_by": {
"id": 1234,
"name": "API"
},
"service_key": "f7a0300abf044e86bfcc7d9ae906381e",
"moderator": {
"id": 2899,
"name": "Dr Doe"
}
} The URL to be provided on the agent or guest side is given by url or short_url
Start the session
There are 2 possible scenarios to start a video meeting session:
The agent opens the agent URL obtained in the previous step in a new tab
The agent opens the URL obtained in the previous step in an iframe,
Example:
Copy <iframe id="ApizeeVisio"
title="VisioAssistance"
src="<URL>"
allow="microphone;camera;geolocation;display-capture">
</iframe> Setting up the conference URL:
Name of the participant. When this parameter is filled in, the participant does not see the login card.
Get a Conference ID by name
You can use the GET /conferences method and its search parameter to find a conference ID.
Example
Copy curl -X 'GET'
'https://cloud.apizee.com/api/conferences?limit=100&since=2023-07-11T00%3A00%3A00Z&search=TEST&orderby=date&order=desc&
-H 'accept: application/JSON'
-H 'Authorization: Bearer xyzaaa-2f0f-44ec-8a2e-900faa015ded' Allows you to find conferences with the keyword 'TEST'
The response is a JSON array:
Copy {
"total": 1,
"data": [
{
"id": 842341,
"name": "TEST XX",
"created": "2023-07-13T16:21:57+00:00",
"modified": "2023-07-13T16:23:36+00:00",
"start_time": "2023-07-13T16:21:57+00:00",
"end_time": "2023-07-13T17:21:57+00:00",
"status": "ongoing",
"room_name": "7a3dc7993234907508525829e02f2388:5c310ee2210c24730a12929e1ec10a21",
"url":
"https://meet.apizee.com/private/7a3dc7993234907508525829e02f2388/5c310ee2210c24730a12929e1ec10a21",
"short_url": "https://apz.fr/5lKzrPDXWQ",
"sip_phone_number": "+33 2 57 57 97 61",
"sip_dtmf_code": "031092",
"organizer": {
"id": 2899231,
"name": "Dr Doe"
},
"created_by": {
"id":1234,
"name": "API"
},
"service_key": "f7a0300abf044e86bfcc7d9ae906381e",
"moderator": {
"id": 2899,
"name": "Dr Doe"
}
}
]
} Get the recorded or shared files
(requires having stored the conference ID or retrieving the ID -- see above)
Example
Copy curl -X 'GET'
'https://cloud.apizee.com/api/conferences/842341/media?limit=10&orderby=date&order=desc'
-H 'accept: application/JSON'
-H 'Authorization: Bearer xyzaaa-2f0f-44ec-8a2e-900faa015ded' Gives in response the array of media for this conference room
Copy {
"total": 2,
"data": [
{
"id": 2343988,
"hash": "aec9aca0-2199-11ee-9a17-c7ee7339236a",
"created": "2023-07-13T16:24:04+00:00",
"owner": {
"id": 2899,
"name": "Dr Doe"
},
"title": "0YW553BN-8214-composite",
"description": null,
"filename": "0YW553BN-8214-composite.mp4",
"status": "completed",
"media_type": "video",
"url":
"https://cloud.apizee.com/media/showVideo/1/hash/aec9aca0-2199-11ee-9a17-c7ee7339236a",
"filesize": 2270386,
"source_type": "conf_record",
"geoloc": {
"lat": 48.7611333,
"lng": -3.4669605
},
"metadata": {
"geoloc": {
"lat": 48.7611333,
"lng": -3.4669605
}
}
]
} Get statistics
The list of sessions per conference day can be found at the endpoint /session.
The statistics are updated 5 minutes after the end of the session.
By specifying the service_key parameter corresponding to the entry point /conference.
Copy {
"total": 1,
"since": "2023-07-13T00:00:00+00:00",
"until": "2023-07-14T23:59:59+00:00",
"data": [
{
"id": "1057a6af-eb9e-4730-b570-b0df1cfb",
"start_time": "2023-07-13T16:23:26+00:00",
"end_time": "2023-07-13T16:24:34+00:00",
"billing_duration": 5,
"total_participant_count": 2,
"organizer": {
"id": 2899,
"name": "Dr Doe"
},
"enterprise": {
"id": 1,
"name": "Apizee"
},
"service": {
"id": 5633,
"key": "f7a0300abf044e86bfcc7d9ae9063xxx",
"name": "Conference"
},
"type": "conference"
}
]
} 
