사용자에게 자동 관리 알림 보내기

아티클
10/27/2023

적용 대상: SDK v4

일반적으로 봇은 사용자로부터 메시지를 받는 것에 대한 응답으로 사용자에게 직접 메시지를 보냅니다. 경우에 따라 봇은 사용자로부터 시작되지 않은 자극에 대한 응답으로 자동 관리 메시지인 메시지를 보내야 할 수 있습니다.

자동 관리 메시지는 다양한 시나리오에서 유용할 수 있습니다. 예를 들어, 사용자가 이전에 제품 가격을 모니터링할 것을 봇에게 요청한 경우 봇은 제품 가격이 20%까지 떨어질 경우 사용자에게 경고할 수 있습니다. 또는 봇이 사용자의 질문에 대한 응답을 컴파일하는 데 약간의 시간이 필요한 경우 지연을 사용자에게 알리고 그 동안 대화를 계속할 수 있습니다. 봇이 질문에 대한 응답 컴파일을 마치면 해당 정보를 사용자와 공유합니다.

이 문서에서는 일반적으로 봇에 대한 사전 대응 메시지에 대한 정보를 다룹니다. Microsoft Teams의 자동 관리 메시지에 대한 자세한 내용은

C#, JavaScript, Java 또는 Python의 Teams 대화 봇 샘플입니다.
자동 관리 메시지를 보내는 방법에 대한 Microsoft Teams 설명서입니다.

참고 항목

Bot Framework JavaScript, C#및 Python SDK는 계속 지원되지만 Java SDK는 2023년 11월에 종료되는 최종 장기 지원으로 사용 중지됩니다. 이 리포지토리 내의 중요한 보안 및 버그 수정만 수행됩니다.

Java SDK를 사용하여 빌드된 기존 봇은 계속 작동합니다.

새 봇 빌드의 경우 Power Virtual Agents 사용을 고려하고 올바른 챗봇 솔루션을 선택하는 방법을 읽어 보세요.

자세한 내용은 봇 빌드의 미래를 참조 하세요.

필수 조건

봇 기본 사항을 이해합니다.
C#, JavaScript, Java 또는 Python에서 자동 관리 메시지 샘플의 복사본입니다. 샘플은 이 문서에서 자동 관리 메시지를 설명하는 데 사용됩니다.

자동 관리 샘플 정보

일반적으로 애플리케이션으로서의 봇에는 다음과 같은 몇 가지 계층이 있습니다.

HTTP 요청을 수락하고 특히 메시징 엔드포인트를 지원하는 웹 애플리케이션입니다.
채널과의 연결을 처리하는 어댑터입니다.
일반적으로 봇 앱에 대한 대화형 추론을 처리하는 봇 클래스에 캡슐화된 턴에 대한 처리기입니다.

사용자의 들어오는 메시지에 대한 응답으로 앱은 어댑터의 프로세스 작업 메서드를 호출하여 턴 및 턴 컨텍스트를 만들고, 미들웨어 파이프라인을 호출한 다음, 봇의 턴 처리기를 호출합니다.

자동 관리 메시지를 시작하려면 봇 애플리케이션이 다른 입력을 받을 수 있어야 합니다. 자동 관리 메시지를 시작하기 위한 애플리케이션 논리는 SDK의 범위를 벗어납니다. 이 샘플의 경우 표준 메시지 엔드포인트 외에도 알림 엔드포인트를 사용하여 사전 대응 턴을 트리거합니다.

이 알림 엔드포인트의 GET 요청에 대한 응답으로 앱은 프로세스 활동 메서드와 유사하게 동작하는 어댑터의 계속 대화 메서드를 호출합니다. 계속 대화 방법:

자동 관리 턴에 사용할 사용자 및 콜백 메서드에 대한 적절한 대화 참조를 사용합니다.
사전 대응 턴에 대한 이벤트 활동 및 턴 컨텍스트를 만듭니다.
어댑터의 미들웨어 파이프라인을 호출합니다.
제공된 콜백 메서드를 호출합니다.
턴 컨텍스트는 대화 참조를 사용하여 사용자에게 메시지를 보냅니다.

샘플에는 다음 그림과 같이 사용자에게 자동 관리 메시지를 보내는 데 사용되는 봇, 메시지 엔드포인트 및 추가 엔드포인트가 있습니다.

Interaction diagram showing how the bot gets a conversation reference and uses it to send a proactive message.

대화 참조 검색 및 저장

Bot Framework Emulator가 봇에 연결되면 봇은 두 가지 대화 업데이트 작업을 받습니다. 봇의 대화 업데이트 작업 처리기에서 대화 참조는 아래와 같이 검색되어 사전에 저장됩니다.

Bots\ProactiveBot.cs

private void AddConversationReference(Activity activity)
{
    var conversationReference = activity.GetConversationReference();
    _conversationReferences.AddOrUpdate(conversationReference.User.Id, conversationReference, (key, newValue) => conversationReference);
}

protected override Task OnConversationUpdateActivityAsync(ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    AddConversationReference(turnContext.Activity as Activity);

    return base.OnConversationUpdateActivityAsync(turnContext, cancellationToken);
}

bots/proactiveBot.js

this.onConversationUpdate(async (context, next) => {
    this.addConversationReference(context.activity);

    await next();
});

addConversationReference(activity) {
    const conversationReference = TurnContext.getConversationReference(activity);
    this.conversationReferences[conversationReference.conversation.id] = conversationReference;
}

ProactiveBot.java

@Override
protected CompletableFuture<Void> onConversationUpdateActivity(TurnContext turnContext) {
    addConversationReference(turnContext.getActivity());
    return super.onConversationUpdateActivity(turnContext);
}

// adds a ConversationReference to the shared Map.
private void addConversationReference(Activity activity) {
    ConversationReference conversationReference = activity.getConversationReference();
    conversationReferences.put(conversationReference.getUser().getId(), conversationReference);
}

bots/proactive_bot.py

async def on_conversation_update_activity(self, turn_context: TurnContext):
    self._add_conversation_reference(turn_context.activity)
    return await super().on_conversation_update_activity(turn_context)

def _add_conversation_reference(self, activity: Activity):
    """
    This populates the shared Dictionary that holds conversation references. In this sample,
    this dictionary is used to send a message to members when /api/notify is hit.
    :param activity:
    :return:
    """
    conversation_reference = TurnContext.get_conversation_reference(activity)
    self.conversation_references[
        conversation_reference.user.id
    ] = conversation_reference

대화 참조에는 활동이 존재하는 대화를 설명하는 대화 속성이 포함되어 있습니다. 대화에는 대화에 참여하는 사용자를 나열하는 사용자 속성과 현재 활동에 대한 회신을 보낼 수 있는 위치를 나타내는 서비스 URL 속성이 포함됩니다. 사용자에게 자동 관리 메시지를 보내려면 유효한 대화 참조가 필요합니다. (Teams 채널의 경우 서비스 URL은 지역화된 서버에 매핑됩니다.)

참고 항목

실제 시나리오에서는 메모리에 개체를 사용하는 대신 데이터베이스에 대화 참조를 유지합니다.

사전 메시지 보내기

두 번째 컨트롤러인 알림 컨트롤러는 사용자에게 자동 관리 메시지를 보낼 책임이 있습니다. 다음 단계를 사용하여 사전 대응 메시지를 생성합니다.

자동 관리 메시지를 보낼 대화에 대한 참조를 검색합니다.
어댑터의 계속 대화 메서드를 호출하여 대화 참조 및 사용할 턴 처리기 대리자를 제공합니다. (계속 대화 메서드는 참조된 대화에 대한 턴 컨텍스트를 생성한 다음 지정된 턴 처리기 대리자를 호출합니다.)
대리자에서 턴 컨텍스트를 사용하여 사전 대응 메시지를 보냅니다. 여기서 대리자는 알림 컨트롤러에 정의되며 사용자에게 자동 관리 메시지를 보냅니다.

참고 항목

각 채널은 안정적인 서비스 URL을 사용해야 하지만 URL은 시간이 지남에 따라 변경됩니다. 서비스 URL에 대한 자세한 내용은 Bot Framework 활동 스키마의 기본 활동 구조 및 서비스 URL 섹션을 참조하세요.

서비스 URL이 변경되면 이전 대화 참조는 더 이상 유효하지 않으며 대화를 계속하기 위한 호출은 오류 또는 예외를 생성합니다. 이 경우 봇은 자동 관리 메시지를 다시 보내기 전에 사용자에 대한 새 대화 참조를 획득해야 합니다.

Controllers\NotifyController.cs

봇의 알림 페이지가 요청되면 알림 컨트롤러는 사전에서 대화 참조를 검색합니다. 그런 다음, 컨트롤러는 ContinueConversationAsync 및 BotCallback 메서드를 사용하여 자동 관리 메시지를 보냅니다.

[Route("api/notify")]
[ApiController]
public class NotifyController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly string _appId;
    private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

    public NotifyController(IBotFrameworkHttpAdapter adapter, IConfiguration configuration, ConcurrentDictionary<string, ConversationReference> conversationReferences)
    {
        _adapter = adapter;
        _conversationReferences = conversationReferences;
        _appId = configuration["MicrosoftAppId"] ?? string.Empty;
    }

    public async Task<IActionResult> Get()
    {
        foreach (var conversationReference in _conversationReferences.Values)
        {
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, conversationReference, BotCallback, default(CancellationToken));
        }
        
        // Let the caller know proactive messages have been sent
        return new ContentResult()
        {
            Content = "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,
        };
    }

    private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
    {
        await turnContext.SendActivityAsync("proactive hello");
    }
}

index.js

서버의 /api/notify 페이지를 요청할 때마다 서버는 사전에서 대화 참조를 검색합니다. 그런 다음 서버는 이 메서드를 continueConversation 사용하여 사전 대응 메시지를 보냅니다. 매개 continueConversation 변수는 이 턴에 대한 봇의 턴 처리기 역할을 하는 함수입니다.

    res.setHeader('Content-Type', 'text/html');
    res.writeHead(200);
    res.write('<html><body><h1>Proactive messages have been sent.</h1></body></html>');
    res.end();
});

NotifyController.java

봇의 알림 페이지가 요청되면 알림 컨트롤러는 사전에서 대화 참조를 검색합니다. 그런 다음 컨트롤러는 이 메서드를 continueConversation 사용하여 자동 관리 메시지를 보냅니다.

@RestController
public class NotifyController {
    /**
     * The BotFrameworkHttpAdapter to use. Note is is provided by dependency
     * injection via the constructor.
     *
     * @see com.microsoft.bot.integration.spring.BotDependencyConfiguration
     */
    private final BotFrameworkHttpAdapter adapter;

    private ConversationReferences conversationReferences;
    private String appId;

    @Autowired
    public NotifyController(
        BotFrameworkHttpAdapter withAdapter,
        Configuration withConfiguration,
        ConversationReferences withReferences
    ) {
        adapter = withAdapter;
        conversationReferences = withReferences;
        appId = withConfiguration.getProperty("MicrosoftAppId");
    }

    @GetMapping("/api/notify")
    public ResponseEntity<Object> proactiveMessage() {
        for (ConversationReference reference : conversationReferences.values()) {
            adapter.continueConversation(
                appId, reference, turnContext -> turnContext.sendActivity("proactive hello").thenApply(resourceResponse -> null)
            );
        }

        // Let the caller know proactive messages have been sent
        return new ResponseEntity<>(
            "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            HttpStatus.ACCEPTED
        );
    }
}

봇의 알림 페이지를 요청받을 때마다 서버는 사전에서 대화 참조를 검색합니다. 그런 다음, 서버는 _send_proactive_message를 사용하여 자동 관리 메시지를 보냅니다.

    for conversation_reference in CONVERSATION_REFERENCES.values():
        await ADAPTER.continue_conversation(
            conversation_reference,
            lambda turn_context: turn_context.send_activity("proactive hello"),
            APP_ID,
        )


APP = web.Application(middlewares=[aiohttp_error_middleware])

자동 관리 메시지를 보내려면 어댑터에 봇에 대한 앱 ID가 필요합니다. 프로덕션 환경에서는 봇의 앱 ID를 사용할 수 있습니다. 에뮬레이터를 사용하여 로컬로 봇을 테스트하려면 빈 문자열("")을 사용할 수 있습니다.

봇 테스트

아직 설치하지 않은 경우 Bot Framework Emulator를 설치합니다.
머신에서 로컬로 샘플을 실행합니다.
에뮬레이터를 시작하고 봇에 연결합니다.
봇의 api/notify 페이지를 로드합니다. 그러면 에뮬레이터에서 자동 관리 메시지가 생성됩니다.

추가 정보

요구 사항

자동 관리 메시지를 보내기 전에 봇에 대화 참조가 필요합니다. 봇은 사용자로부터 받은 모든 활동에서 대화 참조를 검색할 수 있지만, 일반적으로 봇이 사전 대응 메시지를 보내기 전에 사용자가 적어도 한 번 이상 봇과 상호 작용해야 합니다.

사용자가 적어도 한 번 이상 봇에 메시지를 표시하지 않는 한 많은 채널에서 봇이 사용자에게 메시지를 전달하는 것을 금지합니다. 일부 채널은 예외를 허용합니다. 예를 들어 Teams 채널을 사용하면 봇이 봇을 포함하는 이미 설정된 그룹 대화에서 개인에게 자동 관리(또는 1대1) 메시지를 보낼 수 있습니다.

디자인 고려 사항

봇에서 자동 관리 메시지를 구현하는 경우 짧은 시간 내에 몇 가지 자동 관리 메시지를 보내지 마세요. 일부 채널은 봇이 사용자에게 메시지를 보낼 수 있는 빈도에 제한을 적용하고 이러한 제한을 위반하는 경우 봇을 사용하지 않도록 설정합니다.

가장 간단한 유형의 자동 관리 메시지의 경우 봇은 현재 상태 또는 대화 항목과 관계없이 트리거될 때 메시지를 대화에 교차합니다. 이 시나리오에서 자동 관리 메시지는 정상적인 대화 흐름을 중단합니다.

알림을 보다 원활하게 처리하려면 대화 상태에서 플래그를 설정하거나 큐에 알림을 추가하는 등 알림을 대화 흐름에 통합하는 다른 방법을 고려합니다.

사전 대응 턴 정보

계속 대화 메서드는 대화 참조 및 턴 콜백 처리기를 사용하여 다음을 수행합니다.

봇 애플리케이션이 자동 관리 메시지를 보낼 수 있는 차례를 만듭니다. 어댑터는 이름이 "ContinueConversation"으로 설정된 이 턴에 대한 활동을 만듭니다 event .
어댑터의 미들웨어 파이프라인을 통해 턴을 보냅니다.
턴 콜백 처리기를 호출하여 사용자 지정 논리를 수행합니다.

자동 관리 메시지 샘플에서 턴 콜백 처리기는 알림 컨트롤러에 정의되고 봇의 일반 턴 처리기를 통해 자동 관리 작업을 보내지 않고 대화에 직접 메시지를 보냅니다. 또한 샘플 코드는 사전 대응 턴에서 봇의 상태에 액세스하거나 업데이트하지 않습니다.

많은 봇은 상태 저장 상태이며 상태를 사용하여 여러 차례에 걸쳐 대화를 관리합니다. 계속 대화 메서드가 턴 컨텍스트를 만들면 턴에 연결된 올바른 사용자 및 대화 상태가 있으며 자동 관리 턴을 봇의 논리로 통합할 수 있습니다. 자동 관리 메시지를 인식하기 위해 봇 논리가 필요한 경우 몇 가지 옵션을 사용할 수 있습니다. 다음이 가능합니다.

봇의 턴 처리기를 턴 콜백 처리기로 제공합니다. 그러면 봇은 "ContinueConversation" 이벤트 활동을 받습니다.
턴 콜백 처리기를 사용하여 먼저 턴 컨텍스트에 정보를 추가한 다음, 봇의 턴 처리기를 호출합니다.

두 경우 모두 사전 대응 이벤트를 처리하도록 봇 논리를 디자인해야 합니다.

다음 단계

순차적 대화 흐름 구현

사용자에게 자동 관리 알림 보내기

필수 조건

자동 관리 샘플 정보

대화 참조 검색 및 저장

사전 메시지 보내기

봇 테스트

추가 정보

요구 사항

디자인 고려 사항

사전 대응 턴 정보

다음 단계

추가 리소스