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

· Demo: https://api.demo.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: {{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