Direct Line Channel Explained for Custom Copilot Apps | Copilot Studio Day 57

Day 57 of 365 Days of Copilot Studio explains the Direct Line channel in Copilot Studio: how to connect a published agent to any custom web or mobile app so users get AI help inside the experience they already use.

Day 54 showed where a copilot can live inside custom apps. Day 55 placed custom apps inside an omnichannel plan. Day 56 gave the same agent a voice. This lesson goes one level deeper into the connection itself: Direct Line is the secure channel between your app and your agent.

This lesson builds on Day 54: Custom Apps, Day 55: Omnichannel Deployment, and Day 56: Voice Channel. If Day 54 was the what and where, Day 57 is the how for custom-owned experiences.

[!NOTE] Direct Line is the connection. Your custom app is the experience. You need both for a fully owned assistance journey.

Why Direct Line Channel?

Embed options are fast, but they hand you a fixed chat window. Direct Line exists for teams that need the assistant to feel native: your layout, your theme, your placement, your authentication flow, and your business context.

Reason	What it enables	Example
Full UX ownership	Design chat that matches your app instead of framing it.	An inline help panel inside a service portal.
Any client platform	Connect web, mobile, portal, or line-of-business apps.	Order help inside a customer mobile app.
Secure by design	Short-lived tokens keep secrets off the client.	One token per user session, refreshed silently.
Business context	Pass page, record, and role signals with each conversation.	Support that already knows the open case ID.

What Are We Building?

The target is a custom application with a Direct Line-powered chat experience. The user opens your app, the app opens a secure conversation with the published agent, and the agent helps with topics, knowledge, and actions - all inside your interface.

1. Build the agent: topics, knowledge, and actions for the top app scenarios.
2. Publish the agent: release a stable version for the app to call.
3. Enable Direct Line: get the channel connection details for your environment.
4. Add token exchange: generate short-lived tokens from your server.
5. Build the chat UX: design native chat, context passing, and error states.
6. Test and operate: validate real journeys, then monitor and improve.

How Direct Line Works

Every Direct Line conversation follows the same loop: secure session, message exchange, intelligence, response.

1. App requests a token: your server exchanges the secret for a short-lived token.
2. App starts a conversation: the client opens a conversation with that token.
3. User sends a message: Where is my order 12345?
4. Agent understands: matches a topic, reads approved knowledge, calls an action.
5. App renders the reply: text, cards, files, or next-step prompts in your UI.

Same Agent. Different App.

The same published Copilot Studio agent can serve a website, a mobile app, and an internal portal at once. The topics, knowledge, and actions stay shared. Only the app experience changes.

Area	Customer portal	Field mobile app
User input	User asks: Where is my order 12345?	Technician asks: Show me todays work orders.
Agent output	Order status with tracking and return options.	Assigned jobs with parts and site notes.
Strength	Rich layout, documents, links.	Compact, fast, offline-tolerant.

One agent. Every app experience you own.

Choose the Right Integration Path

Direct Line is the most flexible path, not the only path. Choose for the control you need, not by habit.

Approach	Control	Best for
Embed chat	Low	Fast rollout with a standard chat window.
Direct Line channel	High	Custom web or mobile experiences tied to the published agent.
Platform-native channels	Medium	Teams, website, messaging, and voice touchpoints from Day 55.

Need a native feel? Choose Direct Line.

Direct Line: Structured and Controlled

Direct Line suits teams that want predictable, governed app behavior: owned UI, explicit session handling, and server-side security decisions.

• Owned UI: your app renders every message, card, and state.
• Explicit sessions: your app starts, refreshes, reconnects, and ends conversations.
• Server-side trust: secrets, token exchange, and permission checks stay off the client.
• Topic-driven: the same tested topics serve every connected app.

Best for custom-owned conversations.

Direct Line in Action: Message Flow

Under the hood, the app and agent exchange activities: messages, typing indicators, events, and attachments.

1. Start event: the app announces context such as page or record ID.
2. User message: the user asks in natural language.
3. Agent activity: the reply arrives with text, cards, or suggested actions.
4. App renders: your UI displays the reply in your theme and layout.

Turn app screens into guided conversations.

What Is a Secret vs a Token?

This distinction is the heart of Direct Line security. Get it right once and every app benefits.

Credential	Lifetime	Where it lives
Secret	Long-lived	Your server and managed secrets only.
Token	Short-lived	Issued per session to the app client.

• Never ship the secret in web, mobile, or portal client code.
• Generate tokens server-side and hand one token per user session.
• Refresh before expiry so long conversations never break mid-task.

Give Users a Native Experience

Combine the agent with your app chrome so help feels built-in, not bolted on.

• Inline panel: help beside the form, record, or dashboard.
• Full assistant page: deep tasks with history and documents.
• Compact helper: quick answers without leaving the workflow.

Same agent, native feel everywhere.

From Embed Code to Direct Line

Embed approach	Direct Line approach
Paste a chat window. Fixed layout, fast launch.	Connect your own UI. Help appears where the task happens, like Check order 12345 becomes live status plus return options.

Move beyond the generic chat box.

Enable Direct Line in Copilot Studio

1. Agent: open the published, production-ready agent.
2. Channels: go to the channel and custom app integration area.
3. Direct Line: enable the channel for your environment.
4. Connection details: collect the endpoint and channel configuration for developers.

• One channel: serves web, mobile, and portal clients together.
• Environment-aware: keep development, test, and production details separate.

Choose the connection your app needs.

Direct Line Is Not the App

Capability	What you configure	Includes
Enable Direct Line	Channel connection capabilities	Connect a published agent to custom clients over a secure channel.
Build the app	Client experience and trust	Chat UI, token exchange, sign-in, context, error handling, monitoring.
Fully connected experience	Both together	Users get native help that completes real business tasks.

Handle Token Lifecycle

Tokens expire by design. Plan refresh and reconnect before users notice.

Situation	App behavior	User experience
Token nearing expiry	Server issues a fresh token silently.	Conversation continues without interruption.
Network drop	Client reconnects with conversation ID and watermark.	History resumes where it left off.
Token rejected	Client requests a new token and restarts cleanly.	Clear message, no dead end.

• Request tokens per user session, not per message.
• Refresh proactively, not after a failure.
• Log token failures as operational signals.

What If the Session Drops?

1. Connection lost: the client detects the network or socket drop.
2. Reconnect: the app resumes with the same conversation ID and watermark.
3. Agent continues: missed replies are retrieved, not repeated from scratch.

• Keep the conversation going.
• Show honest connection states.
• Offer retry and human help paths.

Design graceful recovery for real networks.

Keep Conversations Connected

Real apps get interrupted. Support conversation continuity so users never start over.

1. Conversation ID: ties every message to one session.
2. Watermark: tracks what the client has already seen.
3. Resume: fetches missed activities after reconnect.
4. End cleanly: closes sessions with history and next steps intact.

More native. Less fragile.

Shape the Chat Experience

Area	What to design	Options
Message rendering	Decide how replies look in your app.	Text, markdown, adaptive cards, files, citations.
Conversation behavior	Control turn-taking and feedback.	Typing indicators, suggested actions, undo, retry.
Context passing	Decide what the app tells the agent.	Page, record ID, role, transaction identifiers.
Failure states	Plan what happens when things break.	Offline copy, retry, escalation, support contact.

Design how help looks, behaves, and recovers.

Secure Every Conversation

A custom channel means custom responsibility. Treat the app as part of your security boundary.

• Secrets server-side: managed vaults and environment-specific settings.
• Per-user tokens: never share tokens across users or devices.
• Sign-in where it matters: require identity for private data and actions.
• Validate server-side: recheck permissions before data access and writes.

One agent. Zero shortcuts on trust.

Pass Context Without Leaking Data

Context makes answers precise. Restraint keeps them safe.

User opens case 4821. App sends a start event with case ID and user role. The agent checks permissions, reads the approved case record, then answers: Your case 4821 is awaiting parts, arriving Thursday. No account numbers, no extra records, no client-side secrets.

Minimal context. Maximum relevance.

Direct Line Can Do More Than Text

A Direct Line app is not just a message box. Connected to business systems, it completes work inside the app.

User: Where is my order 12345? App: sends the message plus account context. The agent connects to knowledge (SharePoint, Docs), actions (Power Automate), data (Dataverse, CRM), and APIs (external systems), retrieves Order 12345 - Shipped, arriving tomorrow, then renders status, tracking, and a return action in your UI.

Powered by your business data. Turn app screens into outcomes.

AI When Possible. Human When Needed.

1. User: I need help with order 12345. Asks inside your app.
2. Copilot agent: Checks the order and offers tracked options.
3. Escalation: Hands off with conversation ID, context, and history.
4. Human agent: Sees the app page, record, and transcript. Continues seamlessly.

Conversation context travels along: user intent, record IDs, previous steps, and full history. No need to repeat yourself.

Escalate without leaving the app.

Direct Line Agent in Action

1. User opens the portal: I need help with my order.
2. App starts a session: token issued, context attached.
3. Agent retrieves the order: checks CRM or ERP data. Let me check that for you.
4. App renders status: Order 12345 - Processed, Shipped, Arriving tomorrow.
5. Issue resolved: Great! Thank you!

Bring order journeys inside your app.

Direct Line for Employee Apps

Employee opens the IT portal: My account is locked. The embedded agent understands and helps.

1. Understand request: identify the issue using natural language.
2. Verify identity: confirm the signed-in user and role.
3. Trigger action: reset access through a secure connector.
4. Resolve or escalate: confirm resolution or hand over with context.

Turn repetitive IT tickets into in-app workflows. Faster help. Happier employees. More productive teams.

Great Direct Line Scenarios

• Customer portals: order, case, and account help beside the record.
• Mobile apps: compact assistance for field, retail, and onboarding.
• Employee systems: HR, IT, finance, and operations guidance.
• Partner portals: controlled answers with strict data boundaries.
• Line-of-business apps: task help where the work already happens.
• Support consoles: triage plus handoff with full transcript.

Start with high-volume, repeatable app journeys.

Direct Line Needs App Testing

Test the app people actually use - not just ideal chat paths.

• Token paths: issue, refresh, expiry, and rejection.
• Conversation paths: multi-turn journeys and interruptions.
• Reconnect: drops, watermarks, and history resume.
• Rich content: cards, attachments, links, and files.
• Context and auth: roles, permissions, and wrong-record handling.
• Escalation: handoff with transcript and record context.

Real apps. Real confidence.

From Build to Production

1. Build agent: create and configure your agent.
2. Publish agent: release the version the app will call.
3. Enable Direct Line: collect channel connection details.
4. Add token service: build server-side issue and refresh.
5. Build chat UX: render messages, cards, states, and errors natively.
6. Test: validate journeys, security, reconnects, and actions.
7. Operate: monitor, improve, and scale.

Connect. Test. Then go live. Build today for real impact tomorrow.

How Everything Connects

1. User: customer, employee, or partner.
2. Custom app: web, mobile, portal, or business system.
3. Direct Line channel: secure app-to-agent connection.
4. Copilot Studio agent: topics, knowledge, and actions.
5. Business systems: CRM, ERP, ITSM, databases, APIs.

Direct Line connects your app to business outcomes.

Design for Your App, Not for Copilot Studio

Different surface. Different experience. People expect your app patterns, not a generic bot window.

Generic (detached): a floating chat box with no record awareness asks for order number, email, and purchase date on every visit.

Native (connected): the portal already knows case 4821, so help asks: Still about case 4821?

• Short: keep replies scannable on small screens.
• Clear: use your app vocabulary and tone.
• Contextual: reuse what the screen already shows.
• Recoverable: every error offers a next step.

Avoid pasting a generic window onto a specific workflow. Direct Line UX needs its own design.

Production Checklist

• Custom app scenario, owner, audience, and success metrics are documented.
• Direct Line is selected as the integration path for the right reasons.
• Agent, topics, knowledge, and actions are tested for app phrasings.
• Secrets live server-side; clients receive short-lived tokens only.
• Token issue, refresh, expiry, and rejection paths are tested.
• Conversation ID, watermark, reconnect, and resume behavior are validated.
• App context is minimal, documented, and permission-checked server-side.
• Sign-in, roles, and data boundaries are enforced for private workflows.
• Cards, attachments, links, and files render correctly on web and mobile.
• Error, offline, fallback, and escalation paths are tested end to end.
• Monitoring covers sessions, token health, action health, fallback, and satisfaction.
• Release notes, support ownership, and improvement rhythm are assigned.

Key Takeaway

Own the experience, not just the agent. A Direct Line-connected app keeps your UI, your identity model, and your workflows while the Copilot Studio agent brings topics, knowledge, actions, and escalation.

When channel, tokens, context, chat UX, business systems, testing, and human handoff work together, your app becomes the front door to real outcomes. Next: Day 58: Azure Bot Service Integration Explained for Copilot Studio.