> For the complete documentation index, see [llms.txt](https://docs.ixhello.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ixhello.com/ixhc2/integrations/executing-flow-via-api-headless-execution/universal-messaging-api.md). # Universal Messaging API ### Overview The Headless Flow Execution API enables execution of conversational flows without relying on traditional interaction channels such as voice or chat. It allows external systems to directly interact with flows through REST APIs. ### Key Benefits * Channel Independence: Run flows without requiring UI-based interaction (voice/chat) * Seamless Integration: Easily integrates with third-party systems * Programmatic Control: Enables granular control over flow execution lifecycle ### Core Capabilities * Execute flows entirely via REST APIs * Maintain stateful sessions for conversational flow interactions * Inject context variables dynamically at runtime * Return real-time flow state and responses ### API Details: #### Base URLs: * US Prod: * US-Demo: * EU STG: * EU PROD:
API: Start Session Creates a new session, begins flow execution, and runs until the first interactive node is reached or the flow completes.
Endpoint: <baseURL>/cgw/process/v1/orgs/<orgId>/flows/<flowId>/sessions

Path Parameters

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------------------- | | orgId | string | Yes | Unique identifier of the organization. | | flowId | string | Yes | Unique identifier of the flow for which a session is created. | #### Example Request URL **Example 1:** URL: Where: * `12345` = Organization ID * `67890` = Flow ID **Example 2:** This URL is a REST API endpoint used to retrieve flow session data for a specific flow within an organization. {% embed url="" %} #### Path Components | Component | Description | | -------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `https://api.demo.vnext.ixhello.com` | Base API domain hosted environment. | | `cgw` | Likely stands for Core Gateway or Customer Gateway, which routes API requests to the appropriate service. | | `process` | Service responsible for flow execution, orchestration, and process management. | | `v1` | API version 1. | | `orgs` | Collection of organizations (tenants). | | `095cf8eb-b79d-4542-9ae1-dbd9cce8ed28` | Unique Organization ID identifying the tenant. | | `flows` | Collection of configured flows within the organization. | | `ff4c6b52-551a-49a4-95d7-7082390624a1` | Unique Flow ID identifying a specific flow. | | `sessions` | Represents instances/executions of the flow. | #### Hierarchical Representation Organization -> 095cf8eb-b79d-4542-9ae1-dbd9cce8ed283 -> Flow4 -> ff4c6b52-551a-49a4-95d7-7082390624a15 -> Sessions

Request Body

``` { "variables": { "customerName": "John Doe", "accountNumber": "12345" }, "metadata": { "externalSessionId": "quiq-session-abc123", "channel": "api" } } ``` | Field | Type | Required | Description | | -------------------------- | ------ | -------- | --------------------------------------------------------- | | variables | object | No | Key-value pairs injected into the flow's variable context | | metadata | object | No | Opaque metadata stored with the session | | metadata.externalSessionId | string | No | Caller's own session ID for correlation | | metadata.channel | string | No | Channel identifier (default: "api") | Notes / Limitations * Sessions are valid for maximum of 1 hour * Supports text-based interaction only (currently) * Authentication is handled via organization-level API keys * No UI interaction—fully backend-driven

Response (201 created) — flow in wait state

``` { "sessionId": "6e16376b-fd09-4a9a-a49a-9ba4c3901563", "flowId": "8c996034-eeff-4efc-b04e-4fb410d6f2b0", "status": "awaiting_input", "messages": [ { "id": "msg-001", "type": "text", "text": "Welcome to Concentrix Airlines!", ... }, { "id": "msg-002", "type": "text", "text": "How can I help you today?", ... } ], "createdAt": "2026-03-20T10:00:00.000Z", "expiresAt": "2026-03-20T11:00:00.000Z" } ```

Response (201 Created) — Flow completed without interaction

``` { "sessionId": "...", "flowId": "...", "status": "completed", "messages": [ { "type": "output", "text": "Your request has been processed.", ... }, { "type": "end", ... } ], "completedAt": "2026-03-20T10:00:02.500Z" } ``` | API: Send Message | Sends a user message (or transfer result) to an active session. The Channel Gateway forwards to the Runtime Engine and returns accumulated messages until the next wait state or session end. | | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Endpoint: \/cgw/process/v1/orgs/\/sessions/\/message | |

Request Body — Text Input (when status: "awaiting_input")

``` { "text": "I'd like to check my flight status" } ``` { "text": "I'd like to check my flight status" }

Request Body — Transfer Result (when status: "awaiting_transfer")

``` { "transferResult": { "status": "success", // or "failed" or "hangup" "failReason": "optional reason when failed" } } ``` | Field | Type | Required | Description | | ------------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------- | | text | string | Conditional | Required when session status is awaiting\_input | | transferResult | object | Conditional | Required when session status is awaiting\_transfer | | transferResult.status | enum | Yes | "success" → success exit · "failed" → error exit · "hangup" → error exit. Maps to event.channel.transfer.completed. | | transferResult.failReason | string | No | Optional reason string when status is "failed" | | | | | | | API: Get Session | Retrieves the current status, metadata, and context variables of a session. Can be called at any point during the session lifecycle — all session variables accumulated so far are returned. | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Endpoint: \/cgw/process/v1/orgs/\/sessions/\ | |

Response (200 OK)

``` { "sessionId": "6e16376b-...", "flowId": "8c996034-...", "status": "awaiting_input", "variables": { "customerName": "Jane", "bookingRef": "CX12345" }, "metadata": { "externalSessionId": "quiq-session-abc123" }, "messageCount": 7, "createdAt": "2026-03-20T10:00:00.000Z", "expiresAt": "2026-03-20T11:00:00.000Z", "lastActivityAt": "2026-03-20T10:02:01.500Z" } ``` | Field | Type | Description | | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | variables | object | All session context variables at the time of the call. Includes variables injected at session start and any values set by the flow during execution. Present at any session lifecycle state. | #### Use Cases of This Call * Enables visibility into the current state of flow variables, allowing users to identify which variables are available at a given point in the flow. * Primarily used as a debugging tool to inspect and validate variable values during execution. * In certain scenarios, it can provide practical value beyond debugging by exposing relevant data that can be leveraged within the conversation flow. * Useful for understanding which variables can be utilized by the client to process or personalize the conversation effectively. | API: End Session |

Terminates an active session. The flow execution is aborted and session state is cleaned up.

| | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Endpoint: \/cgw/process/v1/orgs/\/sessions/\ | |

Response (200 OK)

``` { "sessionId": "6e16376b-...", "status": "terminated", "reason": "client_requested", "terminatedAt": "2026-03-20T10:06:00.000Z" } ``` Session variables are not returned on termination — the session is force-terminated and may not have reached an End node. Use Get Session before terminating to retrieve the current session context if needed. #### Notes / Limitations * Sessions are valid for maximum of 1 hour * Supports text-based interaction only (currently) * Authentication is handled via organization-level API keys * No UI interaction—fully backend-driven --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.ixhello.com/ixhc2/integrations/executing-flow-via-api-headless-execution/universal-messaging-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.