Troubleshooting Direct Line and Web Chat integration issues

Requests to the Direct Line service return the following error while generating tokens or sending messages:

 401 Unauthorized

You may observe one or more of the following:

• Web Chat fails to connect.
• Browser console or service logs show errors such as:
  • Token generation failed: 401
  • Unauthorized
• Direct Line API requests return 401

This issue affects the Direct Line and Web Chat channels configured in HelixGPT Agent Studio when:

• The Direct Line or Web Chat secret is incorrectly copied from the Microsoft Azure portal.
• The secret is regenerated in the Microsoft Azure portal and not updated in HelixGPT Agent Studio.
• An incorrect Azure Bot Service resource is being referenced.

Perform the following steps to correct the configuration:

1. In the Microsoft Azure portal, open the Direct Line channel configuration for your bot.
2. Reveal the active secret and copy the value.
3. In HelixGPT Agent Studio, open the corresponding Microsoft Teams channel.
4. Verify that the Direct Line Secret matches the secret key value from the Microsoft Azure portal:
   • Make sure that no leading or trailing spaces are present.
   • Make sure that the value does not contain line breaks.
5. Save the configuration.

6. If the secret is recently regenerated in the Microsoft Azure portal, update it in all relevant environments, including staging, production, and testing.

7. After updating the secret:

   1. Attempt to generate a new Direct Line token.
   2. Confirm that:
      • Direct Line requests no longer return 401.
      • BMC HelixGPT successfully receives and responds to messages.

Direct Line requests fail with the following errors:

• 403 Forbidden
• Errors indicating that the bot is not part of the conversation.

You may observe one or more of the following:

• The initial connection or token generation succeeds, but subsequent messages fail.
• Possible errors:
  • 403 Forbidden
  • Bot not added to conversation

This issue affects Direct Line and Web Chat conversations when:

• Direct Line is configured but not fully enabled in the Azure Bot Service.
• The existing conversation has expired and is no longer valid for message exchange.

Perform the following steps:

1. In the Azure portal, open your Azure Bot Service resource.
2. Verify that the Direct Line channel is enabled.
3. If Direct Line access is restricted to specific domains or applications, verify that the client application or portal domain is included in the allowed list.
4. If the issue occurs after an extended period of inactivity:
   • Ensure that the client application initiates a new conversation.
   • Request a new Direct Line token when the previous conversation has expired.

5. After updating the configuration or starting a new conversation:

   1. Start a new conversation from your client application.
   2. Send a message and verify that:
      • No 403 Forbidden errors are returned.
      • BMC HelixGPT receives and replies to the message.

Messages sent through Direct Line clients do not receive responses, even though the same skill works correctly in Microsoft Teams.

You may observe one or more of the following:

• Messages sent through Web Chat or a Direct Line client receive no response.

This issue affects Direct Line and Web Chat channels that use the same bot and skill configuration that works in Microsoft Teams.
 

Possible reasons:

• The Direct Line webhook endpoint is not configured correctly.
• The BMC HelixGPT channel is not mapped to the correct skill.
• The assistant service encounters an error or times out before sending the buffered response.

1. In HelixGPT Agent Studio, confirm that the Direct Line channel is associated to the correct skill.

2. Validate Web Chat or Direct Line client configuration:

   • Make sure that the Direct Line client uses the correct Skill ID.
   • Make sure that the Direct Line secret matches the value configured in Microsoft Azure portal.

3. Review BMC HelixGPTserver-side logs at the time of the request:

   • Look for log entries indicating that:
     • Direct Line or Web Chat activity was detected.
     • Streaming was disabled.
     • A complete buffered response was generated and sent.

4. If errors appear in channel processing logs, address any underlying configuration, data, or skill issues indicated by the error messages.

5. Resend the same message from Web Chat or your Direct Line client.

6. Confirm that:
   • The request is received by BMC HelixGPT.
   • A full, complete response appears in Web Chat as a single message.

Adaptive cards are displayed in Web Chat, but interactive elements such as buttons or dropdowns do not trigger any bot actions.

You may observe one or more of the following:

• Adaptive cards render correctly in Web Chat.
• Buttons, dropdowns, or other interactive elements do not generate a bot response.

This issue affects only Direct Line and Web Chat clients when certain Adaptive Card actions, such as Action.Submit is not fully supported, or operates differently in Web Chat.

Recommendations:

1. Adjust skill design to reduce reliance on card interactivity in Web Chat:

   • Provide clear text instructions along with the card.
     • For example: “Type 1, 2, or 3 to select an option.”
   • Avoid using Action.Submit as the only way for users to provide important input.

2. To validate expected behavior:

   • Trigger the same Adaptive Card from:

     • A Microsoft Teams client.
     • A Web Chat or Direct Line client.
   • Confirm that:
     • Teams supports full card interactivity.
     • Web Chat displays the card but may require text‑based user responses.