Socket.IO - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

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

As of Cognigy.AI 4.97.0, the Handover Providers section in the Endpoint settings is deprecated. From Cognigy.AI 2026.4 on, the Handover Settings section in the Endpoint settings is in read-only mode. You can’t use this section to configure new handover providers. You can still view configured handover provider settings, but you can’t change them. To configure handover providers, use the Handover Providers interface, which offers greater flexibility for managing your integration with contact centers. For a smooth migration, refer to the migration guide.

The Socket.IO Endpoint enables you to connect your AI Agent to the Socket.IO client.

Prerequisites

• Familiarity with the Socket.IO library.
• Setup of the Cognigy Socket.IO client.

Generic Endpoint Settings

Learn about the generic Endpoint settings on the following pages:

• Endpoints Overview
• NLU Connectors
• Data Protection & Analytics
• Transformer Functions
• Real-Time Translation Settings
• Handover Settings
• Inject and Notify
• Copilot

How to Set Up

Setup on the Cognigy.AI Side

1. Configure a Socket.IO Endpoint
   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 Socket.IO Endpoint type.
      2. Specify a unique name.
      3. Select a Flow from the list. Save changes.
   4. In the Endpoint editor, go to the Configuration Information section and copy the URL from the Endpoint URL field. The Endpoint URL consists of two parts separated by a slash:
      • The server address (<Socket-Endpoint-URL>), for example, https://endpoint-trial.cognigy.ai.
      • The token (<URLToken>) that comes after the slash, for example, 0e77b9a19f33cb68b3f528b3b28d4b32386162559160ceb9ec85036d83dd8f8b.

For further configuration, you need to use these two parts separately.

Setup on the Third-Party Provider Side

1. Send a Request

const { SocketClient } = require("@cognigy/socket-client");

(async () => {
  // Create the SocketClient with the server address + URL Token + optional options
  const client = new SocketClient(
    "https://endpoint-trial.cognigy.ai",             // the Socket.IO Endpoint server address
    "0e77b9a19f33cb68b3f528b3b28d4b32386162559160ceb9ec85036d83dd8xxx", // the Socket.IO URL token
    {
      userId: "user@cognigy.com",
      sessionId: "session123",
      forceWebsockets: true
    }
  );

// Listen for messages from the AI Agent
  client.on("output", (output) => {
    console.log("AI Agent:", output.text);
    console.log("Additional data:", output.data);
  });

// Listen for errors
  client.on("error", (error) => {
    console.error("AI Agent error:", error.message);
  });

// Listen for finalPing (bot done processing)
  client.on("finalPing", () => {
    console.log("AI Agent finished processing a message");
  });

// Connect to the Socket.IO Endpoint
  await client.connect();

// Send a message — BASIC
  client.sendMessage("Hello from test!");

// Send a message — WITH EXTRA DATA
  client.sendMessage(
    "Example text with custom data",
    {
      passthroughIP: "127.0.0.1", // custom IP if needed
      resetFlow: false,           // false means: continue Flow
      key: "value"                // any custom data for your Flow
    }
  );

// Reset the Flow if needed
  // client.sendMessage(
  //   "Starting fresh!",
  //   {
  //     resetFlow: true
  //   }
  // );
})();

Messages are sent using the processInput event with a payload in the following format:

{
    "URLToken": "urlToken",
    "sessionId": "sessionId",
    "userId": "user@cognigy.com",
    "passthroughIP": "127.0.0.1",
    "resetFlow": "false",  // Resets the Flow and starts a new one from the beginning
    "text": "Example text",  // Can be skipped with "resetFlow": true
    "data": {
        "key": "value"
    }
}

2. Get a Response

Messages can be received by listening to the output event. The responses have the following format:

AI Agent: I’d be happy to help. Could you please provide your order number?
Additional data: {}
AI Agent finished processing a message

{
  "type":"output",
  "data":
  {
    "text":"responseText",
    "data":
    {
      "key":"value"
    }
  }
}

Last modified onJune 15, 2026.