Orchestration Server - Troubleshooting

Digital Person Session fails to start

Steps to Troubleshoot Orchestration Server Connection Issues

Step 1: Open the Browser Network WebSocket Console

1. Launch your browser's developer tools.

2. Navigate to the "Network" tab and filter for WebSocket (ws) connections.
   

Step 2: Launch the Studio Project

Run your Studio project in the browser.

Step 3: Inspect the WebSocket Connection

1. In the "Name" section of the Network tab, click on “?access_token...”.
   
   

2. Check the console messages for any "Close" event messages.
   
   

   • If the message indicates a reason of controlFailed:
      This means our Digital People servers were unable to connect to your Orchestration Server.

     • Our servers attempt this connection before the Digital Person session starts.

     • If the connection fails, the session will not start, and the controlMessage will not appear in the console.

Step 4: Resolve Connection Issues

Follow these steps to fix the connection problem:

1. Verify the Orchestration Server URL:
   
   

   • Ensure the "Orchestration Server URL" in your Studio project settings is correct.

2. If Developing Locally:
   
   

   • Confirm the “I’m developing locally” option is enabled.

   • Check that your local machine's IP and subnet mask are correctly configured.

     • Tip: Use an online tool like IP Subnet Calculator. Look for the "short" address after clicking calculate to find your local machine's IP and subnet mask.

3. If Deployed to a Public Cloud:
   
   

   • Ensure the “I’m developing locally” option is disabled.

   • Verify that the correct public URL for your Orchestration Server is specified.

4. Confirm the Orchestration Server is Running and Accessible:
   
   

   • The Orchestration Server must be publicly accessible for our servers to connect.

5. How to Check Accessibility:
   
   

   • Open your browser and enter the Orchestration Server address in the address bar.

     • If the server is running, you should see a “cannot GET /” error. This is expected, as browsers cannot establish a WebSocket connection.

• If no response is received:

  • The server may not be running, the URL may be incorrect, or the server is not publicly accessible.

6. Test Using a WebSocket Tool:
   
   

   • Use a third-party WebSocket testing site, like PieHost WebSocket Tester, to verify public accessibility.

7. If the Server is Not Accessible:
   
   

   • Review your hosting settings and make the necessary adjustments.

   • Retest the connection after addressing the issue.

Digital Person does not speak/respond

If your Digital Person session starts successfully but does not respond when you speak or type a question, there is likely an issue with your Orchestration Code. Please review the information below and check your code for potential issues.

Orchestration Messaging

When an end user interacts with a Digital Person by speaking or typing a message, our platform generates a conversationRequest message and transmits it to your Orchestration Server via a WebSocket connection.

Your Orchestration code must handle this message by extracting the input.text variable and processing it as needed. For example, your code could retrieve the text from the conversationRequest message, forward it to a conversational service (e.g., NLP or LLM), and wait for a response. Once the service returns a response, your code must format it into a conversationResponse message and send it back to our platform through the WebSocket connection. This allows our platform to generate a spoken reply.

Links

For more information please see the following link. https://soulmachines-support.atlassian.net/wiki/spaces/SSAS/pages/76513281/Linking+an+Orchestration+Server#Orchestration-Server-Messages

To download an example Orchestration Server please visit the link below:
https://github.com/soulmachines/orchestration-nodejs