Dialogue Cloud

On Premises

Configure Copilot Studio node

Introduced in DC2025.01

Use the Copilot Studio node in Dialogue Studio to hand off a text conversation from Dialogue Studio to a Microsoft Copilot Studio agent using the Bot Framework Direct Line channel.

Prerequisites

Get the token endpoint

  1. Go to copilotstudio.microsoft.com, open the Agents tab, and select your existing agent.

    If you don’t have one yet, select New agent (top left).

    Note

    Copilot Studio uses a short conversational onboarding (an AI chat). For this integration step it’s enough to create the agent; detailed topics and behavior can be configured later.

  2. In the top navigation, select Channels.

  3. Choose Direct Line Speech.

  4. Next to Token endpoint, select Copy. Save this URL—you’ll paste it into Dialogue Studio.

Add a Copilot Studio configuration

Create one configuration per agent. The configuration stores the token and bot endpoints.

  1. Open your Dialogue Studio flow.
  2. Drag a Copilot Studio node onto the canvas and double‑click it.
  3. If no configuration exists, select Add new configuration (pencil icon).
    1. In Token URL, paste the token endpoint you copied earlier.
    2. In Bot URL, enter the base URL for your region:

      • Global: https://directline.botframework.com/v3/directline/

      • Europe: https://europe.directline.botframework.com/v3/directline/

      • India: https://india.directline.botframework.com/v3/directline/

        Note

        A request might fail if you use the global base URI for a regional bot, as some requests could go beyond geographical boundaries. Microsoft maintains the regional URLs. Learn: Direct Line API 3.0 reference.

    3. Delay (ms) (optional) — the interval, in milliseconds, that the node waits before polling Copilot Studio for the next reply. The default is 200. If the node reaches the delay without receiving a reply, it escalates to the next Skill so the customer isn’t left waiting. Increase the value for generative‑AI prompts that reference external content (for example, Dataverse Dataverse lets you securely store and manage data that's used by business applications. Data within Dataverse is stored within a set of tables. A table is a set of rows (formerly referred to as records) and columns (formerly referred to as fields/attributes). [From: Microsoft Docs] or public web pages). Learn more.

      1. For text‑only responses, we recommend setting Delay to 2000 ms.

      2. When using generative AI, response times may vary; consider setting Delay to the maximum value.

  4. Select Save.

Troubleshooting

  • The node currently assumes SIP The Session Initiation Protocol, or SIP, is a protocol for multimedia communication (audio, video and data communication). SIP is also used for Voice over IP (VoIP). SIP has interactions with other Internet protocols such as HTTP and SMTP.-format sender identifiers in some parts of its state handling. If your channel provides a tel:+... sender URI (common for WhatsApp / SMS), the node will fail or be unable to start the conversation.

    • Workaround: normalize senderUri (e.g., convert tel:+3112345679 to sip:31123456789@domain.com) through a formatting/normalization function node.

  • 401/403 (Unauthorized/Forbidden) — The node couldn't authenticate or isn't allowed to use Direct Line.

    • Confirm you are using a stand‑alone Copilot Studio subscription (Teams‑only plans can't create Direct Line tokens).

    • Verify the Token URL is the Copilot Studio token endpoint for your agent; regenerate the channel secret if needed.

    • Make sure your account has the Environment Maker or Copilot Studio Author role in the right environment.

  • 403 after inactivity (Direct Line token/session expiration)

    • The node uses Bot Framework Direct Line tokens and calls can return 403 if authentication expires or the token is no longer valid.

    • Current limitation: 4xx responses are treated as non-recoverable by the node (no automatic re-auth / refresh), which can break late replies.

    • Workaround: restart the conversation (clear stored state / reset flowId) or restart the flow to force a new token/session.

  • 404 / bad endpoint — Wrong bot url or region mismatch.

    • Use the region‑correct Direct Line base URL (Global, Europe, India). Using the global URL for a regional bot can fail.

  • Immediate escalation / no reply — The node escalates when no activities arrive after the wait period.

    • Increase Delay (ms) and Max Empty Polls to allow Copilot time to respond (generative prompts may need seconds).

    • Ensure your Copilot agent has a default greeting/response for the first turn.

  • Missing or duplicated messages — Watermark/state issues.

    • Start a fresh conversation (set flowId to null or clear stored state) to reset the Direct Line watermark.

    • Avoid multiple flows consuming the same sender reference at once.

  • HTML / Markdown formatting in message output

    • The node’s output may contain HTML line breaks (<br>) and Markdown-style format **bold**`). Some text channels (notably WhatsApp/SMS) don’t render these as intended, causing messages to look broken or hard to read.

    • Workaround: post-process the output in a Function node to convert HTML/Markdown to channel-safe plain text.

  • Suggested actions are rendered as HTML buttons

    • If the bot returns suggested actions, the node currently formats them as HTML <button> elements. This is not suitable for most text channels (and can be inconsistent even in web chat experiences depending on the client).

      Workaround: Transform suggested actions into a plain text “Options: 1)… 2)…” list in your flow through a formatting/normalization function node.

  • Speech/SSML content appears in text output

    • Some responses include activity.speak (speech/TTS content), which can contain SSML fragments (for example <break .../>). The node currently appends this to the normal text output, which is not appropriate for text-only channels.

    • Workaround: Only use text variations, do not use speech variations.

  • Wrong language or skill routing

    • msg.payload.culture and msg.payload.skill override the node’s configuration. Check upstream nodes.

  • Retry behavior & rate limits

    • The node retries transient errors up to 3 times with a 1000ms back‑off; 4xx errors are treated as non‑recoverable.

    • If you encounter 429 or intermittent 5xx, reduce request frequency and raise Delay (ms).

Example Copilot flow

Use the example flow below as a starting point and adapt it to your routing and channel strategy.

Copy
JSON
[{"id":"41fd37c6577286d4","type":"tab","label":"Copilot Studio — Demo","disabled":false,"info":"","env":[]},{"id":"6dd624e65e85025c","type":"group","z":"41fd37c6577286d4","name":"Copilot web chat example","style":{"stroke":"#000000","fill":"#dbcbe7","label":true,"color":"#000000"},"nodes":["9497122456fbfd17","5986da9e84c582dd","d427b9b8fdcccf68","b0079bb66fdd34da","12e2eacd78067b3a","68ae90b3aac2fde0","8dd8a7349fa55318","1c312de4cee68c9d","10b39ed636bae194","c12c2e6b9e87d283","3035184a04fe3c73"],"x":94,"y":299,"w":1432,"h":262},{"id":"9497122456fbfd17","type":"any-red-copilot","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"Copilot Studio","culture":"en-US","cultureDataType":"str","skill":"OtherChat","skillDataType":"str","config":"","x":840,"y":420,"wires":[["5986da9e84c582dd","68ae90b3aac2fde0"],["d427b9b8fdcccf68","8dd8a7349fa55318"]]},{"id":"5986da9e84c582dd","type":"debug","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"Copilot response","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","statusVal":"","statusType":"auto","x":1170,"y":340,"wires":[]},{"id":"d427b9b8fdcccf68","type":"debug","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"Copilot escalation","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","statusVal":"","statusType":"auto","x":1170,"y":520,"wires":[]},{"id":"b0079bb66fdd34da","type":"debug","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"Incoming text","active":false,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","statusVal":"","statusType":"auto","x":510,"y":520,"wires":[]},{"id":"12e2eacd78067b3a","type":"wait-for-message","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"Wait next message","flowid":"1234","x":1410,"y":400,"wires":[]},{"id":"68ae90b3aac2fde0","type":"say","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"Say Copilot response","text":"payload","dataType":"msg","x":1180,"y":400,"wires":[["12e2eacd78067b3a"]]},{"id":"8dd8a7349fa55318","type":"enqueue","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"","skill":"payload.skill","dataType":"msg","flowid":"9999","x":1140,"y":460,"wires":[]},{"id":"1c312de4cee68c9d","type":"incoming-message","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"","key":"","x":210,"y":480,"wires":[["b0079bb66fdd34da","10b39ed636bae194"]]},{"id":"10b39ed636bae194","type":"switch","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"Check for channel","property":"payload.channelId","propertyType":"msg","rules":[{"t":"eq","v":"0","vt":"str"},{"t":"eq","v":"1","vt":"str"},{"t":"eq","v":"3","vt":"str"},{"t":"eq","v":"4","vt":"num"},{"t":"eq","v":"5","vt":"str"},{"t":"else"}],"checkall":"true","repair":false,"outputs":6,"x":530,"y":440,"wires":[["3035184a04fe3c73"],["3035184a04fe3c73"],["3035184a04fe3c73"],["9497122456fbfd17"],["3035184a04fe3c73"],["3035184a04fe3c73"]],"outputLabels":["Email","SMS","WhatsApp","WebChat","Generic",""]},{"id":"c12c2e6b9e87d283","type":"comment","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"Readme for channel IDs","info":"With the channel IDs you can easily route customers based on the channel they are using:\n\n0\tEmail\n1\tSMS\n3\tWhatsApp\n4\tWebChat\n5\tGeneric\n\nThis example shows how all channels, except Email, can be routed to the chatbot.","x":550,"y":360,"wires":[]},{"id":"3035184a04fe3c73","type":"enqueue","z":"41fd37c6577286d4","g":"6dd624e65e85025c","name":"","skill":"Support","dataType":"str","flowid":"1234","x":820,"y":480,"wires":[]}]