> For the complete documentation index, see [llms.txt](https://dev.apirtc.com/apirtc-developer-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.apirtc.com/apirtc-developer-portal/rest-apis-and-integration/3rd-party-software-integration.md).

# 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);

```