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)

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

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

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

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": "+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

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": "+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:

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

Setting up the conference URL:

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": "+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

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

PreviousIntroduction Next3rd-party software integration

Last updated 29 days ago