# 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"
}
]
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://dev.apirtc.com/apirtc-developer-portal/rest-apis-and-integration/apizee-api-rest-description.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.