> For the complete documentation index, see [llms.txt](https://dev.apirtc.com/apirtc-developer-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.apirtc.com/apirtc-developer-portal/rest-apis-and-integration/apizee-api-rest-description.md).
# Apizee REST APIs
{% hint style="info" %}
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.
{% endhint %}
{% hint style="info" %}
The use of these APIs requires a subscription to [Apizee](https://www.apizee.com) services. Please [contact us](https://www.apizee.com/contact-us) to get more details on the available offers.
{% endhint %}
### Overview
With the Apizee REST APIs, you can:
* Authenticate the user (endpoint: `/token`)
{% hint style="info" %}
Refer to the [authentication](/apirtc-developer-portal/rest-apis-and-integration/introduction.md#authentication) part to get details.
{% endhint %}
* 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`
| Parameter | Description |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `agent``*` | Login (username) of the agent who will handle the request |
| `email` | Email of the assisted customer (mandatory if no phone number provided) |
| `phone` | Phone of the assisted customer (use international prefix) (mandatory if no email provided) |
| `invite` | To send the invitation to the assisted customer, use the value `1` |
| `reference` | Custom reference (e.g., to bind the video assistance session to a support case ID or other relevant business ID) |
| `scope` | To retrieve the agent's URL, use the value `sso` |
Response:
The response is a JSON object.
```json
{
"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: ). 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 the`requestor_url` attribute.
{% hint style="info" %}
Want to include Apizee in 3rd-party software: see the [dedicated page](/apirtc-developer-portal/rest-apis-and-integration/3rd-party-software-integration.md).
{% endhint %}
### 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
```bash
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:
```json
{
"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:
```bash
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
```json
{
"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
```bash
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:
* Number of photos
* Number of videos
* Call duration
```json
[
{
"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
| Parameters | Description |
| -------------- | -------------------------------------------------------------------------------------------------- |
| `participants` | string representing a list of emails or phone numbers separated by commas. (mandatory) |
| `invite` | Equals to 1 if the invitation is sent to the participants |
| `moderation` | When moderation is activated, a participant waits for the moderator's acceptance to enter the room |
| `moderator` | The moderator's login |
| `name` | 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
Example:
```bash
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.
```json
{
"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:
1. The agent opens the agent URL obtained in the previous step in a new tab
2. The agent opens the URL obtained in the previous step in an iframe,
Example:
```html
```
Setting up the conference URL:
| Parameter | Description |
| --------- | ------------------------------------------------------------------------------------------------------- |
| name | 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
```bash
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:
```json
{
"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
```bash
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
```json
{
"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`.
```json
{
"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"
}
]
}
```