---
title: Third Party AI Assist Integration
slug: harmony/third-party-ai-assist-integration
createdAt: 2026-11-12T05:24:21.434Z
---

## Overview

Your agent assist product can receive live call audio from ECC 6X and show its results in the agent's right panel, and write the call's disposition, with no ECC code changes. Calls keep the same ID across transfers and bot-to-agent handovers.

You host two endpoints and ship one panel app. On every call in a campaign mapped to you:

1. The customer and the agent are connected.
2. ECC sends an HTTPS GET to your **stream URL endpoint** and reads a wss\:// URL from your reply.
3. Exotel opens a listen-only WebSocket to that URL and streams the call audio until the call ends.
4. Your **panel app**, in the agent's right panel, receives the call's interactionId from ECC and connects to your servers for results.
5. You match the two by ID: the stream's start.custom\_parameters.conversation\_id equals the panel's interactionId.

How results travel from your servers to your panel app is up to you, for example a WebSocket or polling.

![](https://api.archbee.com/api/optimize/SK2urIgCC2ml99YyqWOSl/dY8HiC-9evJGAvMwPAAju_image.png)

## Before you begin

You supply an Assistant URL and a panel app; an ECC admin installs and maps them.

**What you provide**

- Your **stream URL endpoint** (the Assistant URL), on HTTPS.
- An **audio WebSocket** endpoint on WSS.
- Your **panel app** as an .aaex package.
- The campaigns that should use your assist.

**What Exotel sets up**

1. **Installs your panel app:** App Manager → upload the .aaex → role **Executive** → location **Right Panel** → Install. Agents see it after they log out and back in.
2. **Maps your campaigns:** in the AI Assist Configuration app, each campaign's ID is mapped to your Assistant URL.
3. **Applies the mapping** by reloading the server preference. A new mapping takes effect only after this reload.

Your HTTPS and WSS hosts must be reachable from Exotel's servers. If you allowlist source IPs, ask Exotel for the ranges. Keep your hosts stable: a URL change needs a new mapping, and a new panel package if the panel's host changes.

## Stream URL endpoint

ECC calls this endpoint once per call, when the agent is connected, and streams to the url in your reply.

- **Method:** GET, no request body.
- **URL:** the Assistant URL saved for the campaign. Use https\://. Query parameters you include are sent back to you.
- **Auth:** ECC sends no credentials of its own. Put a long random secret in the URL and reject requests without it (see Security).
- **Reply:** HTTP 200 and JSON in this envelope, with the same wss\:// URL in url and response.data.url:

json

:::BlockQuote
\{
&#x20; "url": "wss\://assist.example.com/ingest/\<stream-secret>",
&#x20; "status": "success",
&#x20; "http\_code": 200,
&#x20; "method": "GET",
&#x20; "request\_id": "\<uuid>",
&#x20; "response": \{
&#x20;   "http\_code": 200,
&#x20;   "data": \{ "url": "wss\://assist.example.com/ingest/\<stream-secret>" },
&#x20;   "error\_data": null
&#x20; }
}
:::

Put any secret in the **path** of the wss\:// URL. A query string on the wss\:// URL is dropped before the connection is made.

## Audio stream

Exotel opens one listen-only WebSocket per call to your wss\:// URL and sends JSON text messages; you never send audio back.

| Event     | When                        | Fields you need                                                                                           |
| --------- | --------------------------- | --------------------------------------------------------------------------------------------------------- |
| connected | First message               | None                                                                                                      |
| start     | Once, right after connected | stream\_sid, start.call\_sid, start.custom\_parameters.conversation\_id, start.media\_format.sample\_rate |
| media     | Every 20 ms                 | media.payload (base64 audio), media.chunk, media.timestamp (ms)                                           |
| stop      | The call ends               | stop.reason, for example canceled or call ended                                                           |

dtmf and mark events may also appear; ignore them.

start

json

:::BlockQuote
\{
&#x20; "event": "start",
&#x20; "stream\_sid": "\<stream\_sid>",
&#x20; "sequence\_number": "1",
&#x20; "start": \{
&#x20;   "stream\_sid": "\<stream\_sid>",
&#x20;   "call\_sid": "\<call\_sid>",
&#x20;   "account\_sid": "\<account>",
&#x20;   "from": "\<caller number>",
&#x20;   "to": "\<called number>",
&#x20;   "custom\_parameters": \{ "conversation\_id": "\<ECC interactionId>" },
&#x20;   "media\_format": \{ "encoding": "base64", "sample\_rate": "8000", "bit\_rate": "128kbps" }
&#x20; }
}
:::

- **Audio:** base64 of 16-bit little-endian PCM, mono, 8000 Hz; 20 ms per message (320 bytes).
- **IDs:** conversation\_id is the only ECC identifier in the stream. There is no agent ID or campaign ID.
- **Refused connections:** if you refuse the handshake, Exotel retries for a few seconds, then stops for that call.

## Agent panel app

Your UI runs inside ECC's agent desktop as an ECC App Framework package in the Right Panel.

**Package**

- A zip named .aaex, at most 10 MB, with these files at its root: manifest.json, index.html (entry point), logo-small.png, logo-medium.png, logo-large.png, plus your JS and CSS.
- manifest.json fields: name, version, minimumRequiredAmeyoVersion, incompatibleAmeyoVersions, description.
- ECC refuses a second upload with the same name and version, so raise version each time.

**Omni SDK**

1. Load the SDK from \<ECC origin>/omniapp/sdk/ameyo-sdk.js.
2. Call initialize(\{context: "app", origin, instanceId: "ameyoIframe"}).
3. Register interactionConnected. Its interactionId matches the stream's conversation\_id.
4. On load, also call interaction.getCurrentInteraction(), so a reload mid-call picks the call up again.
5. Register interactionDisconnected for call end.
6. Read the agent with session.getCurrentUser().userId.

The panel can call your own HTTPS or WSS host directly.

**Call data and events**

- **Call data:** interactionConnected and getCurrentInteraction() also give campaignId, queueId, channelDetails.callId, channelDetails.associationType (how the call reached this agent), customerCrtObjectId and customerDetails (customer ID, phone). getCurrentInteraction() adds relationId, the customer record and its maskable fields.
- **Duplicate events:** ECC can send the same event several times within a second. Act once per interactionId and event.
- **Event names:** interaction rejects an unknown event name with "Unsupported event" (code 4002).

## Transfers

Warm and cold transfers need no extra work: the call keeps its ID and its single audio stream.

- **Same ID:** the interactionId doesn't change, so the stream's conversation\_id still matches.
- **One stream per call:** the stream continues across agents. ECC doesn't call your stream URL endpoint again.
- **Receiving agent:** their panel gets interactionConnected with the same interactionId, and associationType transfer.association (to an agent) or transfer.to.queue.association (to a queue). The panel loads while the call is still being offered, so it can show context before the agent answers.
- **Transferring agent:** their panel gets interactionTransferred with transferType (transferToUser or transferToQueue) and transferContextId (the target agent or queue ID). In a warm transfer it gets interactionEnded only when that agent leaves.
- **Context:** keep results per conversation\_id, and the receiving agent's panel can show everything from before the transfer.
- **Speaker:** the stream doesn't say which agent is speaking. Use the panel events to know who owns the call.

## Bot to agent handover

When an ECC voicebot hands a call to an agent, the ECC interaction ID stays the same, so the bot and your agent assist can link the two halves by that ID.

- **What the bot receives:** ECC's interaction\_id and call\_id, URL-encoded in start.custom\_parameters.call\_setup\_url.
- **What your agent assist receives:** after handover, the stream's conversation\_id and the panel's interactionId equal that interaction\_id. The panel sees associationType voicebot.transfer.to.queue.association.
- **Call leg:** the bot stream's leg\_sid equals your stream's call\_sid.
- **For bot builders:** use ECC's interaction\_id as your conversation ID, so the bot's transcript can be found by the same key.
- **Bot context:** your stream starts when the agent is connected, so it carries no bot audio. To show the agent what happened with the bot, the bot shares its transcript or summary keyed by interaction\_id.

No phone number is needed to link the two, so number masking doesn't affect this.

## Dispositions

Your panel app can read a campaign's disposition codes and save the call's disposition with notes.

1. **Find the campaign:** interaction.getSelectedCampaignForInteraction() returns campaignId, campaignName, processId and the wrap-up time (wrapTimeout, in seconds).
2. **Read the codes:** configuration.getDispositionCodesWithDispositionClass(campaignId), with campaignId as a number. It returns classes (classId, className), each with its codes (dispositionCodeId, dispositionCodeName).
3. **Save the disposition:** interaction.disposeInteraction("voice", interactionId, dispositionCodeId, notes), after the call disconnects, during wrap-up. ECC replies "ok", closes wrap-up at once, and the notes appear as Call Notes on the call record.

- **Use lowercase "voice".** Uppercase "VOICE" returns success but saves nothing.
- **Not during the live call.** A disposition saved then applies only to the agent's leg, and later attempts fail with VoiceCampaign.disp.not.req.for.assoc.
- **Agent's own choice:** no SDK event tells the panel which disposition the agent picked.

## Security

The integration is protected by secrets you control at each hop; treat call audio and transcripts as customer personal data.

| Hop                       | Protection                            | What you do                                                                                          |
| ------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| ECC → stream URL endpoint | Secret in the Assistant URL           | Use a random secret of 32 bytes or more; return 401 without it; compare in constant time             |
| Exotel → audio WebSocket  | Secret in the wss\:// path you return | Refuse the handshake (403) without it                                                                |
| Panel app → your server   | Key in your .aaex package             | Assume any agent can read it; never let a client list calls or pick a conversation\_id without proof |

- **Logs:** mask secrets in URLs and paths; web servers and proxies log them by default.
- **Rotation:** a new stream secret needs an Assistant URL update; a new panel key needs a new package.
- **Transport:** HTTPS and WSS only.

## Limits and FAQs

**Can a campaign use both my assist and Exotel's AI Assist?** No. Each campaign maps to one Assistant URL; a campaign mapped to you stops using Exotel's AI Assist.

**Can I tell from the stream which agent is on the call?** No. The stream carries only conversation\_id. Your panel app knows the agent from the SDK, so join the two by ID.

**Do I send anything back on the audio WebSocket?** No. The stream is listen-only.

**Do agents need to do anything after the app is installed?** They log out and back in once to see the panel.

**Which IP addresses will connect to me?** Ask Exotel for the ranges if you allowlist source IPs.
