Search

Use a Single Polling Thread per Session

Only one thread per session should run the polling loop, whether for an Agent or Consumer session. 

Running multiple concurrent getMessages requests for the same session can lead to race conditions, duplicated processing, out-of-order message handling, unnecessary server load, and unexpected behavior. 

Each session should therefore have a single dedicated thread or process responsible for polling messages from the Chat server.

Do Not Send Concurrent getMessages Requests

If no new data is available, the getMessages request remains open for up to 30 seconds before returning a response. This behavior is intentional and is part of the long-polling mechanism used by the Chat service. 

During this period, the client application must not initiate another getMessages request for the same session. Sending overlapping requests can result in unnecessary network traffic, increased server load, delayed message processing, session instability, or inconsistent sequencing behavior. 

A new getMessages request should only be initiated after the previous request has completed.

Always Track and Send the Sequence Number

The sequence number should always be tracked and included in subsequent getMessages requests. 

If no sequence number is provided, the Chat server assumes the client requires the entire available message history for the session and returns all available data. For long-running sessions, this can result in very large payloads, increased bandwidth usage, higher memory consumption, and slower processing times. 

Using the latest sequence number ensures that only newly available messages are returned, significantly improving performance and scalability.

Immediately Restart Polling After Receiving Data

When new data is available, the getMessages request returns immediately rather than waiting for the full polling timeout.

To maintain near real-time communication and minimize latency, the client should:

• receive the response,
• immediately initiate the next getMessages request, and
• process the returned data asynchronously in a separate thread or worker process.

This prevents message retrieval from being delayed by downstream processing operations.

Separate Polling from Message Processing

The thread responsible for calling getMessages should remain dedicated to message retrieval and should never be blocked by response processing logic.

For large message payloads or complex processing operations, synchronous handling within the polling thread can introduce delays that impact message delivery timing, responsiveness, session synchronization, and overall application stability.

As a best practice, the polling thread should focus exclusively on retrieving messages from the Chat server, and a separate processing layer or thread pool should handle parsing, business logic, database operations, UI updates, or other downstream tasks.

This architecture improves scalability and helps maintain consistent polling behavior under heavy load.

Properly Handle and Recover from Error Responses

All error responses returned by the Chat REST API must be properly parsed, logged, and handled by the client application.

Examples may include:

• 502 Bad Gateway
• 504 Gateway Timeout
• temporary network interruptions
• proxy or load balancer errors

Transient errors should not terminate the polling mechanism or invalidate the client workflow. The application should implement appropriate retry and recovery logic to ensure polling can continue after temporary failures.

Improper error handling may result in stalled chat sessions, missed messages, broken polling loops, or unnecessary session termination.

Avoid API Calls After Session Invalidation

Once a Chat session has been invalidated or terminated, any subsequent API requests associated with that session will fail. This commonly occurs when the end user disconnects, the agent session ends, the session times out, or the conversation is explicitly terminated.

Applications should therefore ensure that:

• session state is properly tracked,
• polling loops are stopped immediately after session termination, and
• no additional API calls (such as concludeEngagements) are sent after the session becomes invalid.

Failure to properly synchronize session termination can result in errors such as 403 INVALID_SESSION_ID, failed engagement closure requests, unnecessary retries or logging noise.

Proper session lifecycle management is essential to maintaining a stable Chat REST API integration.