# IFrame integration reference

## Search parameters

The agent-side interface is accessible at <https://app.apizee.com/agent/> .\
It is a web application configured through query string parameters. Here's a list of all the available parameters.

### Required parameters

The following parameters are mandatory for Embed to start:

<table><thead><tr><th width="135">Parameter</th><th width="182">stands for</th><th width="201">Default</th><th>Description</th></tr></thead><tbody><tr><td>iK<mark style="color:red;">*</mark></td><td>identificationKey</td><td>none</td><td>the identification key of your company, mandatory</td></tr><tr><td>cN<mark style="color:red;">*</mark></td><td>conversationName</td><td>empty</td><td>the <strong>ApiRTC</strong> <strong>Conversation</strong> <strong>name</strong>, mandatory</td></tr></tbody></table>

{% hint style="info" %}
The identification key is provided by your customer success manager after registering to our services.

Please contact our sales team at <contact@apizee.com>.
{% endhint %}

### Optional parameters

<table><thead><tr><th width="135">Parameter</th><th width="182">stands for</th><th width="201">Default</th><th>Description</th></tr></thead><tbody><tr><td>gP</td><td>guestPhone</td><td>empty</td><td>phone number to be pre-set in the invitation form</td></tr><tr><td>iI</td><td>installationId</td><td>APZ_AGENT_</td><td>used as a header for local-storage keys</td></tr><tr><td>l</td><td>lang</td><td>browser config</td><td>to force language to <em>fr</em> or <em>en</em> (must be in ISO 639-1 format)</td></tr><tr><td>eR</td><td>externalReferences</td><td>empty</td><td><p>references for the interaction creation.<br></p><p>The expected format is :<br><code>[</code><br><code>{ "name": "ticketId", "reference": "12345"</code><br><code>{ "name": "crmCase", "reference": "AZE-987"</code><br><code>]</code><br><br>But encoded for URL via, for example, in JavaScript : <code>encodeURIComponent(JSON.stringify(data));</code></p></td></tr></tbody></table>

## PostMessage API

The agent-side application has a real-time messaging feature that enables 2-way communication through the standard [Window: postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) mechanism:

* From the agent-side app to the host platform
* From the host platform to the agent-side app

### From the agent-side app to the host platform

To enable the host application to receive events from the agent-side app, it has to register a listener on the `window` DOM element on events of type "message":

```js
const AGENT_APP_DOMAIN = "https://app.apizee.com";
const receiveMessage = (event) => {
  if (event.origin !== AGENT_APP_DOMAIN) return;

  const message = event.data;

  switch (message.type) {
    case "ready": {
      // web-agent app is ready to receive messages
      break;
    }
    case "snapshot": {
      const dataUrl = message.dataUrl;
      // display or store the snapshot dataUrl.
      break;
    }
    ...
    default:
      console.warn(`Unhandled message.type ${message.type}.`);
  }
};

window.addEventListener("message", receiveMessage);
```

The received data contains at least a \`type\` attribute which describes the type of event triggered by the agent-side app.

For example, when a snapshot is taken,

* the agent-side app trigger an event containing a message of type \`snapshot\`.
* the event holder of the host application catches the event, reads the message's type, and executes the corresponding processing (e.g. grab the `dataUrl` field of the message and store the image somewhere)

Here's the list of all the available events and the fields of each event of the agent-side app.

<table data-full-width="false"><thead><tr><th>message type</th><th>field(s)</th><th>Description</th></tr></thead><tbody><tr><td>ready</td><td>N/A</td><td>an <strong>agent</strong> is ready to receive messages</td></tr><tr><td>sms_sent</td><td><pre><code>name: string,
phone: string,
link: string
</code></pre></td><td>a sms has been sent to guest <strong>name</strong> and <strong>phone</strong> with <strong>link</strong></td></tr><tr><td>snapshot</td><td><pre class="language-json"><code class="lang-json">dataUrl: string,
contact: {
    id: string,
    conversationName: string,
    userData: apiRTC.UserData
}
</code></pre></td><td>a snapshot taken on a <strong>Stream</strong> from a <strong>Contact</strong> is received</td></tr><tr><td>subscribed_streams</td><td><pre><code>length: Number
</code></pre></td><td>the number of subscribed streams changes</td></tr></tbody></table>

### From the host platform to the agent-side app

The host application can control the agent-side app by using the standard DOM `postMessage` method of the Iframe element:

```js
const AGENT_APP_DOMAIN = "https://app.apizee.com";
iframe.contentWindow.postMessage(
  {
    type: "conversation",
    name: "new_conversation_name",
  },
  AGENT_APP_DOMAIN
);
```

{% hint style="danger" %}
The host application must wait for a message of type \`ready\` from the agent-side app before starting to post any message.
{% endhint %}

Here's the list of all the available actions and the list of fields for each message type of the agent-side app.

<table><thead><tr><th>message type</th><th>field(s):type</th><th>Description</th></tr></thead><tbody><tr><td>configuration</td><td><pre><code>installationId: string;
callStatsMonitoringInterval?: number;
logLevel: string;
</code></pre></td><td>configures the application</td></tr><tr><td>conversation</td><td><pre><code>name: string
</code></pre></td><td>set the <strong>Conversation</strong> name</td></tr><tr><td>guest_data</td><td><pre><code>userId?: string,
username?: string,
name?: string
[key: string]: string | undefined;
</code></pre></td><td>set the guest data</td></tr></tbody></table>