# 3rd-party software integration

{% 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 %}

In this page, you will find several ways of integrating the Apizee solution into 3rd-party software:

* [Send invitations from a new tab](#send-invitations-in-a-new-tab)
* [Send invitations from an iframe](#send-invitations-from-an-iframe)
* [Open the video assistance room in a new tab](#open-a-video-assistance-or-a-video-meeting-room-in-a-new-tab)
* [Agent-side video interface as an iframe](#agent-side-video-interface-as-an-iframe)
* [Use a loader script to implement a video chat pop in into the 3rd-party app](#loaderagent-module-in-3rd-party-applications)

***

## Send invitations from a new tab

In a new tab, the user signs on to the Apizee platform (if not already identified) and then uses the form to send invitations to participants.

<figure><img src="/files/QrrAetL6l8uO0dUCEMKc" alt=""><figcaption></figcaption></figure>

Insert a link or a button in the 3rd-party application that redirects the user to a new tab opening the Apizee invitation form.

URL format: <https://cloud.apizee.com/quick-invitation>

{% hint style="info" %}
This integration doesn't require backend service to authenticate against Apizee services. only the user would need to sign-in.
{% endhint %}

### Available parameters

Add the following parameter in the query parameters in the URL to pass information or configure behavior of the invitation form:

| Parameter              | Description                                                   | Format                          | Behavior                                                                                                                                             |
| ---------------------- | ------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reference`            | Displays a non-editable label with a client reference.        | String (max 50 characters)      | If provided, displays the reference as a label. Strings longer than 50 characters are truncated. Not displayed if no service is preselected.         |
| `service_key`          | Preselects a service in the invitation dropdown.              | Alphanumeric (32 characters)    | If valid, the corresponding service is preselected. If invalid, no preselection occurs, and a warning is logged. Overrides previously used services. |
| `phone_numbers`        | Prepopulates the "Invited Guests" field with phone numbers.   | Comma-separated phone numbers   | Valid numbers are added to the field. Invalid numbers are flagged with an error.                                                                     |
| `email_addresses`      | Prepopulates the "Invited Guests" field with email addresses. | Comma-separated email addresses | Valid emails are added to the field. Invalid emails are flagged with an error.                                                                       |
| `read_only.service`    | Makes the service dropdown field read-only.                   | Boolean (`true` or `false`)     | If `true`, the service dropdown cannot be edited.                                                                                                    |
| `read_only.recipients` | Makes the recipients field read-only.                         | Boolean (`true` or `false`)     | If `true`, the recipient field cannot be edited.                                                                                                     |

#### **`reference`**

* Displays as a non-editable label if provided in the URL.
* Truncated to 50 characters if the string exceeds the limit.
* Only displayed and used for services of type video-assistance.

| Example                                                  | Output                                                    |
| -------------------------------------------------------- | --------------------------------------------------------- |
| `/quick-invitation?reference=ABC123`                     | Displays "Reference: ABC123" as a non-editable label.     |
| `/quick-invitation?reference=LongStringExceeding50Chars` | Displays the first 50 characters of the reference string. |

#### **`service_key`**

* Preselects the specified service in the dropdown if valid.
* Overrides previously used services.

| Example                                                         | Output                                           |
| --------------------------------------------------------------- | ------------------------------------------------ |
| `/quick-invitation?service_key=`9447243e889a783488c4369ccfdc0f4 | Preselects the service corresponding to the key. |
| `/quick-invitation?service_key=invalidkey`                      | No service preselected.                          |

#### **`phone_numbers`**

Prepopulates the "Guests" field with valid numbers.

| Example                                             | Output                                                 |
| --------------------------------------------------- | ------------------------------------------------------ |
| `/quick-invitation?phone_numbers=0612345678`        | Adds `0612345678` to the "Invited Guests" field.       |
| `/quick-invitation?phone_numbers=0612,+33612345678` | Adds `0612` (flagged as invalid), adds +`33612345678`. |

#### **`email_addresses`**

Prepopulates the "Guests" field with valid email addresses.

| Example                                                   | Output                                                    |
| --------------------------------------------------------- | --------------------------------------------------------- |
| `/quick-invitation?email_addresses=user@example.com`      | Adds `user@example.com` to the "Guests" field.            |
| `/quick-invitation?email_addresses=user@,valid@email.com` | Adds `user@` (flagged as invalid), adds `valid@email.com` |

#### **`read_only.service`**

When `true`, the service dropdown becomes uneditable.

| Example                                    | Output                                                  |
| ------------------------------------------ | ------------------------------------------------------- |
| `/quick-invitation?read_only.service=true` | The service dropdown is disabled and cannot be changed. |

***

#### **`read_only.recipients`**

When `true`, the "Guest" field becomes uneditable.

| Example                                       | Output                                               |
| --------------------------------------------- | ---------------------------------------------------- |
| `/quick-invitation?read_only.recipients=true` | The "Guest" field is disabled and cannot be changed. |

## Send invitations from an iframe

{% hint style="warning" %}
**Prerequisites**: If you want to use Apizee in an iframe, there are several prerequisites:

* For security reasons, communicate the domain of your application to our support team, so that we can authorize it
* Create a DNS entry in your application's domain (ex: apizee.your-domain.com) which is a CNAME of cloud.apizee.com. This subdomain / URL will be used when called the iframe
  {% endhint %}

The sample integration code is shown below:

```html
<iframe id="ApizeeApp"
        title="VisioAssistance"
        src="https://xxx.your-domain.com/quick-invitation" <!-- created CNAME entry to cloud.apizee.com -->
        allow="microphone;camera;geolocation;display-capture"
        allowfullscreen>
</iframe>
```

Add parameters to the URL to configure the form (see [#send-invitations-in-a-new-tab](#send-invitations-in-a-new-tab "mention") for a complete list of available parameters)

## Open the video assistance room in a new tab

{% hint style="warning" %}
Integrating Apizee in a 3rd-party solution requires you to use the REST APIs to provision for video assistance or a video chat room and get in return a URL to join the room. Please refer to [the page dedicated to REST APIs description](/apirtc-developer-portal/rest-apis-and-integration/apizee-api-rest-description.md) to get the corresponding steps.

In the examples below, choose the right URL to render either the agent/organizer side or the customer/participant side of the video communication room.
{% endhint %}

Simply retrieve the URL through the REST API (see [the page dedicated to REST API description](/apirtc-developer-portal/rest-apis-and-integration/apizee-api-rest-description.md) for the detailed steps) and insert it into an anchor link tag in your HTML page.

```html
<a href="<RETRIEVED URL>" target="_blank">Start video chat</a>
```

## loaderAgent module in 3rd-party applications

{% hint style="warning" %}
This integration option is only available for video assistance scenarios.
{% endhint %}

Your page should include the loaderAgent.js library:

```html
<script type="text/javascript" src="https://cdn.apirtc.com/agent/loaderAgent.js"></script>
```

This script file provides the `loadAgent` function with the following prototype:

```javascript
loadAgent(serverDomainRoot,
    apiCCkey,
    userInfos,
    agentAppCallback,
    useFrame,
    agentParams);
```

With:

* `serverDomainRoot`: Apizee platform url, for example "<https://cloud.apizee.com/>
* `apiCCkey`: The apiRTC or Apizee key to be found in your console (<https://cloud.apirtc.com/enterprise/api>)
* `userInfos`: javascript structure containing user-related information
* `agentAppCallback`: \[optional] a function called when an event is raised (callback)
* `useFrame`: \[optional] to allow the use of iframe during the call
* `agentParams`: \[optional] a structure containing additional parameters

Before being able to call the `loadAgent` function, you must go through 2 steps:

1. Retrieve a token for the agent with the endpoint `/token` (see [authentication](/apirtc-developer-portal/rest-apis-and-integration/introduction.md#authentication))
2. Use the endpoint `/v2/users/me` to retrieve the user info.

Example:

```bash
curl -X 'GET' 
    'https://cloud.apizee.com/api/v2/users/me' 
    -H 'accept: application/JSON' 
    -H 'Authorization: Bearer xyzaaa-c900-4dd2-8192-433269xxxxx' 
    -H 'X-CSRF-TOKEN: '

```

Response:

```json
    {
        "photo_url":
        "https://cloud.apizee.com/img/users/AMN34qakmrBmJWpo/default?t=1689179650",
        "enterpriseId": 1,
        "userId": 3456,
        "apiKey": "7a3dc7993234907508525829e02f2300", //the apiRTC key defined for your enterprise account
        "nickname": "Agent Martin",
        "token": "xyzaaa-c900-4dd2-8192-433xxxxxx",
        "is_agent": false,
        "ccs": "ccs6.apizee.com",
        "mail": "agentxxx@apizee.com"
    }
```

The fields `userId`, `apiKey`, `nickname` and `token` will be necessary to call LoadAgent.

### Agent Event Callback

This callback function allows executing actions following events raised by the Agent video module.

Define this function before calling it in LoadAgent:

```javascript
var agentAppCallback = function agentAppCallback(agent, type, params) {
    switch (type) {
    case "init":
        alert('Agent is loaded');
        break;
    case "updatePresence":
        break;
    ...
    }
};
```

### Event List

| Event type       | Description                                                                   | Params                                                                      |
| ---------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `init`           | Agent is loaded and ready to work.                                            | --                                                                          |
| `createNewIMDiv` | Fired when a new box container has been created.                              | `{ destId:Integer, nickname:String }`                                       |
| `openComBox`     | Fired when a box is opened.                                                   | jQuery object of the box container                                          |
| `minimize`       | Fired when a box is minimized.                                                | `destId:Integer`                                                            |
| `maximize`       | Fired when a box is maximized.                                                | `destId:Integer`                                                            |
| `close`          | Fired when a box is closed.                                                   | `destId:Integer`                                                            |
| `putInFrame`     | Fired when the page has been reloaded into navIframe.                         | --                                                                          |
| `showNewMessage` | Fired when a new message is shown.                                            | `{ nickname:String, destId:Integer, message:String, html:String }`          |
| `sendMessage`    | Fired when a message is sent                                                  | `{ destId:Integer, message:String }`                                        |
| `updatePresence` | Fired when the presence information of other users changes : online / offline | `{ eventType:String, time:String, connectedUsersList:Array, state:String }` |

### Code example

Example of use with the previously retrieved parameters:

```javascript
var serverDomainRoot = "https://cloud.apizee.com/",
    apiCCkey = "YOUR_APIKEY_HERE",
    userInfos = {
            id: 3456, //userId
            token: "xyzaaa-c900-4dd2-8192-433xxxxxx ", // apiKey
            nickname: "Agent Martin",
        };

var useFrame = true;
var agentParams = {
    directory: false,
    directoryStartOpen: false,
    template: 'agent-modern',
    useDefaultTheme: false
    culture: 'en'
};

var agentAppCallback = function agentAppCallback(agent, type, params) {
    switch (type) {
    case "init":
        alert('Agent is loaded');
        break;
    }
};

loadAgent(serverDomainRoot, user.apiKey, userInfos, agentAppCallback,
useFrame, agentParams);

```


---

# 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/3rd-party-software-integration.md?ask=<question>
```

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.