Chat Directline

Chat via DirectLine

Send a single utterance to a published agent via the DirectLine v3 REST API. Use this for agents with no authentication (authenticationmode 1) or manual authentication (authenticationmode 3).

Instructions

1. Run the script with --token-endpoint (from detect-mode output) and the utterance from $ARGUMENTS:

``bash node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js \ --token-endpoint "" "" ``

If the user provided a DirectLine secret instead:

``bash node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js \ --directline-secret "" "" ``

1. Parse the JSON output from stdout.

Normal response (status: "ok")

{
  "status": "ok",
  "protocol": "directline",
  "utterance": "hello",
  "conversation_id": "abc123-XYZ",
  "directline_token": "eyJ...",
  "watermark": "3",
  "start_activities": [ ... ],
  "activities": [ ... ]
}

Display the agent's response from the activities array:

• Text: activities where type === "message" — show text
• Suggested actions: suggestedActions.actions array
• Adaptive cards: attachments with contentType === "application/vnd.microsoft.card.adaptive"

Save conversation_id, directline_token, and watermark — needed for follow-ups.

Sign-in required (status: "signin_required")

The agent requires the user to authenticate (manual auth agents):

{
  "status": "signin_required",
  "protocol": "directline",
  "signin_url": "https://...",
  "resume_command": "...",
  "followup_command": "..."
}

1. Show the signin_url to the user, ask for the validation code
2. Send the code: node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js
3. Re-send the utterance: node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js

Use resume_command and followup_command exactly as given.

Multi-turn

Pass all three values from the previous response:

node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js \
  --token-endpoint "" "" \
  --conversation-id "" --directline-token "" --watermark ""

• directline_token is bound to the conversation — do NOT fetch a new token. Always reuse from the previous response.
• watermark tracks seen activities — pass it to avoid duplicates.
• Tokens expire after ~30 minutes. If expired, start a new conversation (omit --conversation-id).

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | Token endpoint rejected | Agent not published or wrong URL | Verify agent is published | | Conversation not found | Token expired (>30 min) | Start a new conversation |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/skills-for-copilot-studio
• License: MIT

Install and usage instructions live in the source repository linked above.