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: https://api.vnext.ixhello.com

• US-Demo: https://api.demo.vnext.ixhello.com

• EU STG: https://api.stg.eu.vnext.ixhello.com

• EU PROD: https://api.eu.vnext.ixhello.com

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: https://api.company.com/cgw/process/v1/orgs/12345/flows/67890/sessions

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.

https://api.demo.vnext.ixhello.com/cgw/process/v1/orgs/095cf8eb-b79d-4542-9ae1-dbd9cce8ed28/flows/ff4c6b52-551a-49a4-95d7-7082390624a1/sessionsapi.demo.vnext.ixhello.com

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