Agent Copilot Custom Integration - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

This guide shows how to embed Agent Copilot into a custom contact center or agent desktop using the Voice Copilot Endpoint. It helps developers test and validate Copilot quickly without a full contact-center setup. Works for both chat and voice.

Prerequisites

• Configured the Voice Gateway integration:
  • If a Voice Copilot Endpoint is used for voice or chat use cases.
  • If a Webhook Endpoint is used for voice use cases.

Restrictions

• If you use a Webhook Endpoint, you will be charged for two conversations: one with the webhook and one with Agent Copilot.

Create an Endpoint

Mock a request via Postman or curl to validate the webhook accepts your session.

• Voice Copilot
• Webhook

1. In the left-side menu of your Project, click Deploy > Endpoints.

2. On the Endpoints page, click + New Endpoint.

3. In the New Endpoint section, do the following:

   1. Select the Voice Copilot Endpoint type.
   2. Specify a unique name.
   3. Select a Flow from the list. Save changes.
   4. Go to the Configuration Information section and copy the URL from the Endpoint URL field.

4. In the left-side menu of your Project, click Deploy > Endpoints.

5. On the Endpoints page, click + New Endpoint.

6. In the New Endpoint section, do the following:

   1. Select the Webhook Endpoint type.
   2. Specify a unique name.
   3. Select a Flow from the list. Save changes.
   4. Go to the Configuration Information section and copy the URL from the Endpoint URL field.

Mock a Request

Send a POST request to the Endpoint which you configured in the previous step.
Your web server should accept POST requests and process the JSON payload sent by Cognigy.AI. For testing purposes, you can use webhook.site as a temporary web server.

Replace https://<your-endpoint-url> with the Endpoint URL from your Endpoint’s settings.

curl -X POST https://<your-endpoint-url> \  
  -H "Content-Type: application/json" \  
  -d '{\n    "userId": "user123",\n    "sessionId": "session123",\n    "text": "Hello, I need help with my order",\n    "data": {\n      "exampleKey": "exampleValue"\n    }\n  }'

1. Open the Postman collection, select Add a request, then set the request type to POST.
2. Enter the Endpoint URL as the request URL.
3. Go to the Headers tab and add Content-Type: application/json.
4. Go to the Body tab, select raw, then select JSON as the format.
5. Paste the request body:

{
  "userId": "user123",
  "sessionId": "session123",
  "text": "Hello, I need help with my order",
  "data": {
    "exampleKey": "exampleValue"
  }
}

Configure the Agent Copilot URL

When setting up Agent Copilot, you can choose between embedded or standalone Agent Copilot versions. For standalone Agent Copilot, use the URL format to access the workspace:

https://${AgentCopilotBaseUrl}/?userId=${userId}&sessionId=${sessionId}&URLToken=${URLToken}

For the configuration details, refer to the Agent Copilot URL section.

(Optional) Embed in the Agent Desktop

You can embed Agent Copilot into any contact center interface using an iframe. Some platforms may require additional setup, such as enabling scripts or granting API access. Embedding is specific to the contact center, so verify the integration on the provider’s side to ensure proper functionality.

<iframe
  src="https://${AgentCopilotBaseUrl}/?userId=${userId}&sessionId=${sessionId}&URLToken=${URLToken}"
  width="100%"
  height="720"
  style="border:0;">
</iframe>

More Information

• Overview

1: You must provide at least one of text or data. You can send either, or both. If both are missing or invalid, the REST Endpoint throws an error.