Apizee REST APIs

Several use cases can be implemented through Apizee REST APIs.

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)

Refer to the authentication part to get details.

• 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
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)
agent	Login (username) of the agent who will handle the request
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

Example:

curl -X 'POST' https://cloud.apizee.com/api/tickets?name=Test&phone=0612345678&reference=1234&agent=agent1%40apizee.com&invite=1&scope=sso' 
    -H 'accept: application/JSON' 
    -H 'Authorization: Bearer xyzaaa-afcf-461f-a431-1245hgdh2324' 
    -d ''

Response:

The response is a JSON object.

{
    "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": "[e-mail]",
    "requestor_url":
    "https://diag.apizee.com?convId=88a2c81a-2b5a-496f-8546-0d7bdde8&pwd=798042",
    "requestor": {
        "phone": "[phone]"
        },
    "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.

Want to include Apizee in 3rd-party software: see the dedicated page.

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

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:

{
"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": "[e-mail]",
        "requestor_url":
        "https://diag.apizee.com?convId=3efcffcc-abc6-4917-b822-e659ea26&pwd=908120",
        "requestor": {
            "phone": "[phone]"
        },
        "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:

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

{
    "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

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

[
    {
    "ID": 821793,
    "Ref": 1234,
    "Description": "",
    "Priorité": "Immédiat",
    "Demandeur": "xx",
    "Contact": "[phone]",
    "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": "[e-mail]",
    "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 https://cloud.apizee.com/sdk/api

Example:

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.

    {
    "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": "[phone]",
    "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:

<iframe id="ApizeeVisio" 
    title="VisioAssistance"
    src="<URL>"
    allow="microphone;camera;geolocation;display-capture">
</iframe>

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

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:

{
    "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": "[phone]",
        "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

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

{
"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.

{
    "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"
        }
    ]
}