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

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)

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:

  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:

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

Last updated