> 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: · Prod: · Demo:
API: Start Session Creates a new session, begins flow execution, and runs until the first interactive node is reached or the flow completes.
Endpoint: {{API-GateWay-baseURL}}/cgw/process/v1/orgs/:orgId/flows/:flowId/sessions

Path Parameters

| Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------- | | orgId | string | Yes | Organization identifier | | flowId | string | Yes | Flow identifier to execute |

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: {{API-GateWay-baseURL}}/cgw/process/v1/orgs/:orgId/sessions/:sessionId/messages | |

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: {{API-GateWay-baseURL}}/cgw/process/v1/orgs/:orgId/sessions/:sessionId | |

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: {{API-GateWay-baseURL}}/cgw/process/v1/orgs/:orgId/sessions/:sessionId | |

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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.