Migrate conversation/transitionAgentParticipants endpoint into lambdas/account-scoped

[Copilot]

Migrates the transitionAgentParticipants serverless function into lambdas/account-scoped/src/conversation/ and extracts the shared logic from transfersTaskRouterListener.ts into a reusable module. Also adds feature flag support in plugin-hrm-form to route wrapupConversationTask, completeConversationTask, and transferChatStart to the migrated lambda endpoints.

Description

lambdas/account-scoped changes

• src/conversation/interactionChannelParticipants.ts (new) — Extracted transitionAgentParticipants from transfersTaskRouterListener.ts into a shared module; lists Flex interaction channel participants and transitions agent participants to a target status
• src/conversation/transitionAgentParticipants.ts (new) — HTTP handler for the migrated endpoint; accepts taskSid, targetStatus (required) and interactionChannelParticipantSid (optional); looks up the task via getTaskAndReservations, checks that the calling worker is a supervisor or holds a valid reservation on the task, extracts flexInteractionSid/flexInteractionChannelSid from the task attributes, then delegates to the shared function
• src/transfer/transfersTaskRouterListener.ts (modified) — Removed private transitionAgentParticipants function; now imports from shared module
• src/router.ts (modified) — Registers conversation/transitionAgentParticipants route with validateFlexTokenRequest({ tokenMode: 'agent' }) pipeline, matching the TokenValidator used in the original serverless version
• Tests added for both interactionChannelParticipants.ts and the new handler, including task-not-found (404), unauthorized (403), supervisor bypass, agent with valid reservation, and error propagation cases

plugin-hrm-form changes

• src/types/FeatureFlags.ts (modified) — Added use_twilio_lambda_to_transition_participants flag; activated use_twilio_lambda_transfers flag (previously commented out)
• src/services/twilioTaskService.ts (modified) — wrapupConversationTask and completeConversationTask now check use_twilio_lambda_to_transition_participants: when set, they call the new lambda /conversation/transitionAgentParticipants endpoint with taskSid/targetStatus; otherwise fall back to the legacy serverless endpoint. transferChatStart moved here from ServerlessService.ts with use_twilio_lambda_transfers flag routing to /transfer/transferStart (lambda) or /transferChatStart (legacy)
• src/services/ServerlessService.ts (modified) — transferChatStart removed (moved to twilioTaskService.ts)
• src/transfer/setUpTransferActions.tsx (modified) — Updated import of transferChatStart to use new location in twilioTaskService

Checklist

• Corresponding issue has been opened
• New tests added
• Feature flags added
• Strings are localized
• Tested for chat contacts
• Tested for call contacts

Other Related Issues

None

Verification steps

1. Deploy to a dev environment and set the use_twilio_lambda_to_transition_participants feature flag to true.
2. Verify the POST /lambda/twilio/account-scoped/{accountSid}/conversation/transitionAgentParticipants endpoint transitions the specified agent participants in a Flex interaction channel to the requested status, with a valid agent Flex token that has a reservation on the task.
3. Confirm that a request with a token that is neither a supervisor nor holds a valid reservation on the task is rejected with a 403.
4. Confirm that wrapupConversationTask and completeConversationTask route to the new lambda endpoint when the flag is enabled, and fall back to the legacy serverless endpoint when disabled.
5. Set the use_twilio_lambda_transfers feature flag to true and verify that transferChatStart routes to /transfer/transferStart on the lambda; confirm fallback to /transferChatStart when disabled.

AFTER YOU MERGE

1. Cut a release tag using the Github workflow. Wait for it to complete and notify in the #aselo-deploys Slack channel.
2. Comment on the ticket with the release tag version AND any additional instructions required to configure an environment to test the changes.
3. Only then move the ticket into the QA column in JIRA

You are responsible for ensuring the above steps are completed. If you move a ticket into QA without advising what version to test, the QA team will assume the latest tag has the changes. If it does not, the following confusion is on you! :-P

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Migrate the conversation management endpoints into the lambdas/account-scoped</issue_title>
<issue_description>## Description

Migrate the following twilio serverless endpoint into the lambdas/account-scoped

https://github.com/techmatters/serverless/blob/master/functions/interactions/transitionAgentParticipants.ts

Place it in the conversation folder

Move the transitionAgentParticipants function that is currently a private function in the transferTaskRouterListener.ts file into a separate module where it can be accessed by the listener and the migrated endpoint. Place it in the conversation folder and call it interactionChannelParticipants.ts

Additional context

Follow the same patterns as for other endpoints that have been migrated

For example, https://github.com/techmatters/serverless/blob/master/functions/getTaskAndReservations.ts was recently migrated to https://github.com/techmatters/flex-plugins/blob/master/lambdas/account-scoped/src/task/getTaskAndReservations.ts

Note how when a TokenValidator wrapper is used in the serverless version, a validateFlexTokenRequest item needs to be added to the request pipeline for the route in account-scoped
</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Migrate the conversation management endpoints into the lambdas/account-scoped #3986

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[stephenhand]

Add a feature flag to plugin-hrm-form called use_twilio_lambda_to_transition_participants

Use this flag to determine whether the wrapupConversationTask and completeConversationTask methods in twilioTaskService.ts should send to the legacy endpoint or the migrated endpoint. It should send to the migrated endpoint if set

Update the transferChattStart method in ServerlessService.ts to use the existing use_twilio_lambda_transfers flag to control if it points to the legacy transferChatStart or the migrated transferChat endpoint. Move this method into twilioTaskService

[Copilot]

Add a feature flag to plugin-hrm-form called use_twilio_lambda_to_transition_participants

Use this flag to determine whether the wrapupConversationTask and completeConversationTask methods in twilioT...

Done in commit 8453af3:

• Added use_twilio_lambda_to_transition_participants and use_twilio_lambda_transfers flags to FeatureFlags.ts
• wrapupConversationTask and completeConversationTask now check use_twilio_lambda_to_transition_participants — when set, they call /conversation/transitionAgentParticipants on the lambda with flexInteractionSid/flexInteractionChannelSid/targetStatus; otherwise falls back to the legacy serverless endpoint
• setUpActions.ts updated to pass payload.task.attributes so the lambda gets the interaction sids
• transferChatStart moved from ServerlessService.ts to twilioTaskService.ts and updated to check use_twilio_lambda_transfers — when set, calls /transfer/transferStart via the lambda; otherwise uses the legacy /transferChatStart
• Import updated in setUpTransferActions.tsx

[stephenhand]

The transitionAgentParticipantHandler hasn't been implemented correctly. It should take a task SID and look up the task object, and check permissions based on user role and whether they have a reservation on the task, like the original implementation does

[Copilot]

The transitionAgentParticipantHandler hasn't been implemented correctly. It should take a task SID and look up the task object, and check permissions based on user role and whether they have a reserva...

Fixed in commit a7739af. The handler now:

• Accepts taskSid, targetStatus, and optional interactionChannelParticipantSid
• Calls getTaskAndReservations to look up the task and its reservations, filtered by the calling worker
• Returns 403 if the user is neither a supervisor nor has a valid reservation on the task (matching the permission check in the original serverless version)
• Extracts flexInteractionSid/flexInteractionChannelSid from the task's parsed attributes and passes them to transitionAgentParticipants
• Handler type changed from AccountScopedHandler to FlexValidatedHandler to receive the tokenResult

The plugin-hrm-form side is updated to send taskSid to the lambda endpoint (rather than the interaction sids directly).