Сообщения в беседах с ботами

Статья
10/04/2023

Каждое сообщение в беседе Activity является объектом типа messageType: message. Когда пользователь отправляет сообщение, Microsoft Teams публикует действие сообщения боту. Teams отправляет объект JSON в конечную точку обмена сообщениями бота, а Teams разрешает только одну конечную точку для обмена сообщениями. Бот проверяет сообщение, чтобы определить его тип и ответить соответствующим образом.

Основные беседы обрабатываются через соединитель Bot Framework, один REST API. Этот API позволяет боту взаимодействовать с Teams и другими каналами. Пакет SDK Bot Builder предоставляет следующие возможности:

Простой доступ к соединителю Bot Framework.
Функциональные возможности для управления потоком и состоянием беседы.
Простые способы внедрения когнитивных служб, такие как обработка естественного языка (NLP).

Бот получает сообщения из Teams с помощью Text свойства и отправляет пользователям один или несколько ответов на сообщения.

Дополнительные сведения см. в разделе атрибуция пользователей для сообщений бота.

В следующей таблице перечислены действия, которые бот может получать и выполнять действия.

Тип	Объект полезных данных	Scope
Действие получения сообщения	Действие сообщения	Все
Получение действия по изменению сообщения	Действие изменения сообщения	Все
Действие получения отмены сообщения	Действие отмены сообщения	Все
Действие получения сообщения обратимого удаления	Действие обратимого удаления сообщений	Все

Действие получения сообщения

Чтобы получить текстовое Text сообщение, используйте свойство Activity объекта . В обработчике активности бота используйте объект контекста поворота Activity для чтения одного запроса сообщения.

В следующем коде показан пример получения действия сообщения:


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}


export class MyBot extends TeamsActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => {
            // Sends a message activity to the sender of the incoming activity.
            await context.sendActivity(`Echo: '${context.activity.text}'`);
            await next();
        });
    }
}


async def on_message_activity(self, turn_context: TurnContext):
    // Sends a message activity to the sender of the incoming activity.
    return await turn_context.send_activity(MessageFactory.text(f"Echo: {turn_context.activity.text}"))


{
    "type": "message",
    "id": "1485983408511",
    "timestamp": "2017-02-01T21:10:07.437Z",
    "localTimestamp": "2017-02-01T14:10:07.437-07:00",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "channelId": "msteams",
    "from": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB39ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen",
        "aadObjectId": "7faf8ab2-3d56-4244-b585-20c8a42ed2b8"
    },
    "conversation": {
        "conversationType": "personal",
        "id": "a:17I0kl9EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-"
    },
    "recipient": {
        "id": "28:c9e8c047-2a74-40a2-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "textFormat": "plain",
    "text": "Hello Teams TestBot.Sending bold-italic rich text",
    "attachments": [
      {
            "contentType": "text/html",
            "content": "<div><div>Hello Teams TestBot. Sending <strong>bold</strong>-<em>italic</em> rich text.</div>\n</div>"
      } 
    ],
    "entities": [
      { 
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo"
      }
    ],
    "channelData": {
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "locale": "en-US"
}

Получение уведомления о прочтении

Параметр Уведомления о прочтении в Teams позволяет отправителю сообщения чата получать уведомления о том, что его сообщение было прочитано получателем в чатах "один на один" и в групповых чатах. После того как получатель прочитает сообщение, рядом с ним появится значок Просмотрено . Вы также можете настроить бота для получения событий получения уведомлений о прочтении с помощью параметра Уведомления о прочтении . Событие уведомления о прочтении помогает улучшить взаимодействие с пользователем следующими способами:

Вы можете настроить бота для отправки последующего сообщения, если пользователь приложения не прочитал сообщение в личном чате.
Вы можете создать цикл обратной связи с помощью уведомлений о прочтении, чтобы настроить взаимодействие с ботом.

Примечание.

Уведомления о прочтении поддерживаются только в сценариях чата между пользователями и ботами.
Уведомления о прочтении ботов не поддерживают области группового, канала и группового чата.
Если администратор клиента или пользователь отключает параметр Уведомления о прочтении , бот не получает событие уведомления о прочтении.

Чтобы получать события уведомлений о прочтении для бота, убедитесь в следующем:

Добавьте разрешение RSCChatMessageReadReceipt.Read.Chat в манифест приложения следующим образом:

Манифест приложения версии 1.12 или более поздней версии
Манифест приложения версии 1.11 или более ранней версии

    
"webApplicationInfo": {
    
     "id": "38f0ca43-1c38-4c39-8097e-47f62c686500",
     "resource": ""
},
"authorization": {
    "permissions": {
    "orgwide": [],
     "resourceSpecific": [
        {
        "name": "ChatMessageReadReceipt.Read.Chat",
        "type": "Application"
        }
        ]
     }
 }

    
 “webApplicationInfo”: {

     "id": "123456c8-67d2-4f54-b74e-408b195c4cbc",
     "resource": "https: //AnyString",
     "applicationPermissions": [
     "ChatMessageReadReceipt.Read.Chat"
     ]
 }

Вы также можете добавить разрешения RSC с помощью API Graph. Дополнительные сведения см. в статье consentedPermissionSet.

Переопределите метод OnTeamsReadReceiptAsync обработчиком IsMessageRead .

Вспомогательный IsMessageRead метод полезен для определения того, считывается ли сообщение получателями. compareMessageId Если значение меньше или равно LastReadMessageId, сообщение было прочитано. Переопределите OnTeamsReadReceiptAsync метод для получения уведомлений о прочтении с помощью IsMessageRead вспомогательного метода:


protected override async Task OnTeamsReadReceiptAsync(ReadReceiptInfo readReceiptInfo, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken) 
{
    var lastReadMessageId = readReceiptInfo.LastReadMessageId;
   if (IsMessageRead("{id of the message that you care}", LastReadMessageId))
   {
        await turnContext.SendActivityAsync(MessageFactory.Text("User read the bot's message"), cancellationToken);    
    }
}

Ниже приведен пример запроса на событие получения уведомлений о прочтении, получаемого ботом:

{
    "name": "application/vnd.microsoft.readReceipt",
    "type": "event",
    "timestamp": "2023-08-16T17:23:11.1366686Z",
    "id": "f:b4783e72-9d7b-2ed9-ccef-ab446c873007",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1-8Iuh70W9pRqV8tQK8o2nVjxz33RRGDKLf4Bh7gKnrzN8s7e4vCyrFwjkPbTCX_Co8c4aXwWvq3RBLr-WkkVMw",
        "aadObjectId": "5b649834-7412-4cce-9e69-176e95a394f5"
    },
    "conversation": {
        "conversationType": "personal",
        "tenantId": "6babcaad-604b-40ac-a9d7-9fd97c0b779f",
        "id": "a:1xlimp68NSUxEqK0ap2rXuwC9ITauHgV2M4RaDPkeRhV8qMaFn-RyilMZ62YiVdqs8pp43yQaRKvv_U2S2gOS5nM-y_pOxVe4BW1qMGPtqD0Bv3pw-nJXF0zhDlZHMZ1Z"
    },
    "recipient": {
        "id": "28:9901a8b6-4fef-428b-80b1-ddb59361adeb",
        "name": "Test Bot"
    },
    "channelData": {
        "tenant": {
            "id": "6babcaad-604b-40ac-a9d7-9fd97c0b779f"
        }
    },
    "value": {
        "lastReadMessageId": "1692206589131"
    }
}

Параметр администратора квитанции на чтение или пользовательский параметр включен для клиента, чтобы бот получал события получения уведомлений о прочтении. Администратор клиента или пользователь должны включить или отключить параметр уведомления о прочтении.

После включения бота в сценарии чата пользователя бота бот быстро получает событие уведомления о прочтении, когда пользователь считывает сообщение бота. Вы можете отслеживать вовлеченность пользователей, подсчитывая количество событий, а также отправлять контекстное сообщение.

Отправка сообщения

Чтобы отправить текстовое сообщение, укажите строку, которую нужно отправить в качестве действия. В обработчике действий бота используйте метод объекта контекста поворота SendActivityAsync для отправки одного ответа сообщения. Используйте метод объекта для отправки SendActivitiesAsync нескольких ответов.

В следующем коде показан пример отправки сообщения при добавлении пользователя в беседу:


protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}


    this.onMembersAddedActivity(async (context, next) => {
        await Promise.all((context.activity.membersAdded || []).map(async (member) => {
            if (member.id !== context.activity.recipient.id) {
              
                // Sends an activity to the sender of the incoming activity.
                await context.sendActivity(
                    `Welcome to the team ${member.givenName} ${member.surname}`
                );
            }
        }));

        await next();
    });


async def on_members_added_activity(
    self, members_added: [ChannelAccount], turn_context: TurnContext
):
    for member in teams_members_added:
        // Sends a message activity to the sender of the incoming activity.
        await turn_context.send_activity(f"Welcome your new team member {member.id}")
    return


{
    "type": "message",
    "from": {
        "id": "28:c9e8c047-2a34-40a1-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "conversation": {
        "id": "a:17I0kl8EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-",
        "name": "Convo1"
   },
   "recipient": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB25ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen"
    },
    "text": "My bot's reply",
    "replyToId": "1632474074231"
}

HTTP Request: {Service URL of your bot}/v3/conversations/{conversationId}/activities

{
    "type": "message",
    "from": {
        "id": "28:c9e8c047-2a34-40a1-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "conversation": {
        "id":"a:17I0kl8EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-",
        "name": "Convo1"
    },
    "recipient": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB25ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen"
    },
    "text": "My bot's reply"
}

Примечание.

Разделение сообщений происходит, когда текстовое сообщение и вложение отправляются в одной и той же полезной нагрузке действия. Teams разделяет это действие на два отдельных действия: одно с текстовым сообщением, а другое с вложением. При разделении действия вы не получаете идентификатор сообщения в ответ, который используется для упреждающего обновления или удаления сообщения. Вместо разбиения сообщений рекомендуется отправлять отдельные действия.
Отправленные сообщения можно локализовать для обеспечения персонализации. Дополнительные сведения см. в статье Локализация приложения.

Сообщения, отправляемые между пользователями и ботами, включают в себя данные внутреннего канала в сообщении. Эти данные позволяют боту правильно взаимодействовать по этому каналу. Пакет SDK Bot Builder позволяет изменять структуру сообщений.

Получение действия редактирования сообщения

При редактировании сообщения бот получает уведомление о действии изменения сообщения.

Чтобы получить уведомление об изменении сообщения в боте, можно переопределить OnTeamsMessageEditAsync обработчик.

Ниже приведен пример уведомления об изменении сообщения с использованием OnTeamsMessageEditAsync при редактировании отправленного сообщения:


protected override async Task OnTeamsMessageEditAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken) 
{ 
var replyActivity = MessageFactory.Text("message is updated"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
}


{
"type":"messageUpdate",
"timestamp":"2022-10-28T17:19:39.4615413Z",
"localTimestamp":"2022-10-28T10:19:39.4615413-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_PM4mubmQZsYPx7jDyLeLf_YVA9sVPV08KMAFMjJWB_EUGveb9EVDh9TslNp9qjnzEBy3kgw01Jf1Kg",
    "name":"Mike Wilber",
    "aadObjectId":"520e4d1e-2108-43ee-a092-46a9507c6200"caching
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1pweuGJ44RkB90tiJNQ_I6g3vyuP4CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqRPB"
},
"recipient":{
    "id":"28:0d569679-gb4j-479a-b0d8-238b6e6b1149",
    "name":"TestBot"
},
"entities":[
    {
        "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"editMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}

Для получения уведомлений о действиях для обработки обновлений сообщений с помощью пакета SDK для бота можно использовать метод регистрации функции событий или метод переопределения метода :

Регистрация функции событий:


this.onTeamsMessageEditEvent(async (context, next) => {
  let editedMessage = context.activity.text;
  await context.sendActivity(`The edited message is ${editedMessage}"`);
  next();
})

Переопределение метода:


async onTeamsMessageEdit(context) {
    let editedMessage = context.activity.text;
    await context.sendActivity(`The edited message is ${editedMessage}"`);
}

PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}

{
    "type": "message",
    "text": "This message has been updated"
}

Получение действия отмены сообщения

При отмене удаления сообщения бот получает уведомление об активности отмены сообщения.

Чтобы получить уведомление о действиях отмены сообщения в боте, можно переопределить OnTeamsMessageUndeleteAsync обработчик.

Ниже приведен пример уведомления об OnTeamsMessageUndeleteAsync отмене сообщения при восстановлении удаленного сообщения.


protected override async Task OnTeamsMessageUndeleteAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{ 
var replyActivity = MessageFactory.Text("message is undeleted"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
}


{
"type":"messageUpdate",
"timestamp":"2022-10-28T17:19:39.4615413Z",
"localTimestamp":"2022-10-28T10:19:39.4615413-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_TM4mubmQZsYEo7jDyLeLf_YVA9sVPVO7KMAFMjJWB_EUGveb9EVDh9LgoNp9qjnzEBy4kgw83Jf1Kg",
    "name":"Alex Wilber",
    "aadObjectId":"976e4d1e-2108-43ee-a092-46a9507c5606"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1tewuGJ44RkB90tiJNQ_I4q8vyuN5CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqXQL"
},
"recipient":{
    "id":"28:0d469698-ab9d-479a-b0d8-758b6e6b1234",
    "name":"Testbot"
},
"entities":[
    {
           "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"undeleteMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}

Регистрация функции событий:


this.onTeamsMessageUndeleteEvent(async (context, next) => {
    let undeletedMessage = context.activity.text;
    let messageId = context.activity.id;
    await context.sendActivity(`Previously the message was deleted. After undeleting, the message is now: "${undeletedMessage}"`);
next();
})

Переопределение метода:


async onTeamsMessageUndelete(context) {
    let undeletedMessage = context.activity.text;
    let messageId = context.activity.id;
    await context.sendActivity(`Previously the message was deleted. After undeleting, the message is now: "${undeletedMessage}"`);
}

PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}

{
    "type": "message",
    "text": "This message has been updated"
}

Получение действия с обратимым удалением сообщений

При обратимом удалении сообщения бот получает уведомление об активности обратимого удаления сообщения.

Чтобы получить уведомление об активности сообщения обратимого удаления в боте, можно переопределить OnTeamsMessageSoftDeleteAsync обработчик.

Ниже приведен пример уведомления об активности обратимого удаления сообщений при OnTeamsMessageSoftDeleteAsync обратимом удалении сообщения:


protected override async Task OnTeamsMessageSoftDeleteAsync(ITurnContext<IMessageDeleteActivity> turnContext, CancellationToken cancellationToken) 
{ 
var replyActivity = MessageFactory.Text("message is soft deleted"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
}


{
"type":"messageDelete",
"timestamp":"2022-10-28T17:19:43.1612052Z",
"localTimestamp":"2022-10-28T10:19:43.1612052-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_TM4mubmQZsYEo7jDyLeLf_YVA9sVPVO7KMAFMjJWB_EUGveb9EVDh9LgoNp9qjnzEBy4kgw83Jf1Kg",
    "name":"Alex Wilber",
    "aadObjectId":"976e4d1e-2108-43ee-a092-46a9507c5606"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1tewuGJ44RkB90tiJNQ_I4q8vyuN5CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqXQL"
},
"recipient":{
    "id":"28:0d469698-ab9d-479a-b0d8-758b6e6b1235",
    "name":"Testbot"
},
"entities":[
    {
        "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"softDeleteMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}

Регистрация функции событий:


this.onTeamsMessageSoftDeleteEvent(async (context, next) => {
    let messageId = context.activity.id;
      await context.sendActivity(`The deleted message id is ${messageId}`);
    next();
})

Переопределение метода:


async onTeamsMessageSoftDelete(context) {
    let messageId = context.activity.id;
    await context.sendActivity(`The deleted message id is ${messageId}`);
}

Отправка предлагаемых действий

Предлагаемые действия позволяют боту предоставлять кнопки, которые пользователь может выбрать для ввода данных. Предлагаемые действия улучшают взаимодействие с пользователем, позволяя пользователю отвечать на вопрос или делать выбор с помощью кнопки, а не вводить ответ с помощью клавиатуры. Когда пользователь нажимает кнопку, она остается видимой и доступной в расширенных карточках, но не для предлагаемых действий. Это не позволяет пользователю выбирать устаревшие кнопки в беседе.

Чтобы добавить предлагаемые действия в сообщение, задайте suggestedActions свойство объекта действия, чтобы указать список карта объектов действий, представляющих кнопки, которые будут представлены пользователю. Дополнительные сведения см. в статье sugestedActions.

Ниже приведен пример реализации и опыта предлагаемых действий.

"suggestedActions": {
    "actions": [
      {
        "type": "imBack",
        "title": "Action 1",
        "value": "Action 1"
      },
      {
        "type": "imBack",
        "title": "Action 2",
        "value": "Action 2"
      }
    ],
    "to": [<list of recepientIds>]
  }

Ниже показан пример предлагаемых действий.

Действия, предлагаемые ботом

Примечание.

SuggestedActions поддерживаются только для чат-ботов с текстовыми сообщениями и адаптивными карточками.
SuggestedActions не поддерживаются для чат-ботов с вложениями для любого типа беседы.
imBack — это единственный поддерживаемый тип действия, и Teams отображает до трех предлагаемых действий.

Данные канала Teams

Объект channelData содержит сведения, относящиеся к Teams, и является окончательным источником идентификаторов команд и каналов. При необходимости эти идентификаторы можно кэшировать и использовать в качестве ключей для локального хранилища. В TeamsActivityHandler пакете SDK извлекает важную информацию из channelData объекта, чтобы сделать его доступным. Однако вы всегда можете получить доступ к исходным данным из turnContext объекта .

Объект channelData не включается в сообщения в личных беседах, так как они происходят за пределами канала.

Типичный channelData объект в действии, отправляемом боту, содержит следующие сведения:

eventType: тип события Teams передается только в случаях изменения канала.
tenant.id: Microsoft Entra идентификатор клиента передается во всех контекстах.
team: передается только в контекстах канала, а не в личном чате.
- id: GUID для канала.
- name: имя команды, переданное только в случаях переименования команды.
channel: передается только в контекстах каналов, когда упоминается бот, или для событий в каналах в командах, где бот добавляется.
- id: GUID для канала.
- name: имя канала передается только в случаях изменения канала.
channelData.teamsTeamId:Устаревшие. Это свойство включается только для обеспечения обратной совместимости.
channelData.teamsChannelId:Устаревшие. Это свойство включается только для обеспечения обратной совместимости.

Пример объекта channelData

В следующем коде показан пример объекта channelData (событие channelCreated):

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

Содержимое сообщения

Сообщения, полученные от бота или отправляемые ей, могут содержать различные типы содержимого сообщений.

Формат	От пользователя к боту	От бота к пользователю	Примечания
Форматированный текст	✔️	✔️	Бот может отправлять форматированный текст, изображения и карточки. Пользователи могут отправлять боту форматированный текст и изображения.
Изображения	✔️	✔️	Максимум 1024 × 1024 пикселя и 1 МБ в формате PNG, JPEG или GIF. Не поддерживает анимированный GIF-файл.
Карточки	❌	✔️	Сведения о поддерживаемых картах см. в статье Справочник по карта Teams.
Эмодзи	✔️	✔️	В настоящее время Teams поддерживает эмодзи через UTF-16, например U+1F600 для улыбки лица.

Сообщения с картинкой

Чтобы улучшить сообщение, можно добавить изображения в виде вложений к сообщению. Дополнительные сведения о вложениях см. в статье Добавление мультимедийных вложений в сообщения.

Изображения могут иметь не более 1024 × 1024 пикселей и 1 МБ в формате PNG, JPEG или GIF. GIF с анимацией не поддерживается.

Укажите высоту и ширину каждого изображения с помощью XML. В Markdown размер изображения по умолчанию — 256×256. Например:

Используйте: <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>.
Не используйте: ![Duck on a rock](http://aka.ms/Fo983c).

Бот беседы может включать адаптивные карточки, которые упрощают бизнес-процессы. Адаптивные карточки предоставляют расширенные настраиваемые текст, речь, изображения, кнопки и поля ввода.

Адаптивные карточки

Адаптивные карточки можно создать в боте и отображать в нескольких приложениях, таких как Teams, ваш веб-сайт и т. д. Дополнительные сведения см. в разделе Адаптивные карточки.

В следующем коде показан пример отправки простой адаптивной карточки:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
    {
        "items": [
        {
            "size": "large",
            "text": " Simple Adaptivecard Example with a Textbox",
            "type": "TextBlock",
            "weight": "bolder",
            "wrap": true
        },
        ],
        "spacing": "extraLarge",
        "type": "Container",
        "verticalContentAlignment": "center"
    }
    ]
}

Добавление уведомлений в сообщение

Отправить уведомление из приложения можно двумя способами:

Задав Notification.Alert свойство в сообщении бота.
Отправляя уведомление веб-канала действий с помощью API Graph.

Вы можете добавить уведомления в сообщение с помощью Notification.Alert свойства . Уведомления оповещают пользователей о событии в приложении, например о новых задачах, упоминаниях или комментариях. Эти оповещения связаны с тем, над чем работают пользователи или что они должны смотреть, вставляя уведомление в веб-канал действий. Чтобы уведомления активируются из сообщения бота TeamsChannelData , задайте для свойства objects Notification.Alertзначение true. Если возникает уведомление, это зависит от параметров Teams отдельного пользователя, и вы не можете переопределить эти параметры.

Если вы хотите создать произвольное уведомление, не отправляя пользователю сообщение, можно использовать API Graph. Дополнительные сведения см. в статье Отправка уведомлений веб-канала действий с помощью API Graph, а также в рекомендациях.

Примечание.

В поле Сводка отображается любой текст от пользователя в виде уведомления в веб-канале.

В следующем коде показан пример добавления уведомлений в сообщение:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Returns a simple text message.
  var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
  message.TeamsNotifyUser();

  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(message);
}


this.onMessage(async (turnContext, next) => {
    let message = MessageFactory.text("You'll get a notification, if you've turned them on.");
    teamsNotifyUser(message);
    // Sends an activity to the sender of the incoming activity.
    await turnContext.sendActivity(message);

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Справочные материалы для SDK


async def on_message_activity(self, turn_context: TurnContext):
    message = MessageFactory.text("You'll get a notification, if you've turned them on.")
    teams_notify_user(message)
    // Sends an activity to the sender of the incoming activity.
    await turn_context.send_activity(message)

{
  "type": "message",
  "timestamp": "2017-04-24T21:46:00.9663655Z",
  "localTimestamp": "2017-04-24T14:46:00.9663655-07:00",
  "serviceUrl": "https://callback.com",
  "channelId": "msteams",
  "from": {
    "id": "28:e4fda94a-4b80-40eb-9bf0-6314491bc793",
    "name": "The bot"
  },
  "conversation": {
    "id": "a:1pL6i0oY3C0K8oAj8"
  },
  "recipient": {
    "id": "29:1rsVJmSSFMScF0YFyCXpvNWlo",
    "name": "User"
  },
  "text": "John Phillips assigned you a weekly todo",
  "summary": "Don't forget to meet with Marketing next week",
  "channelData": {
    "notification": {
      "alert": true
    }
  },
  "replyToId": "1493070356924"
}

Коды состояния из интерфейсов API бесед бота

Обеспечьте соответствующую обработку этих ошибок в приложении Teams. В следующей таблице перечислены коды ошибок и описания, при которых создаются ошибки.

Код состояния	Код ошибки и значения сообщений	Описание	Повторный запрос	Действие разработчика
400	Код: `Bad Argument` Сообщение: *сценарий	Недопустимые полезные данные запроса, предоставляемые ботом. Дополнительные сведения см. в сообщении об ошибке.	Нет	Переоценка полезных данных запроса на наличие ошибок. Проверьте возвращенное сообщение об ошибке для получения дополнительных сведений.
401	Код: `BotNotRegistered` Сообщение. Регистрация для этого бота не найдена.	Регистрация этого бота не найдена.	Нет	Проверьте идентификатор и пароль бота. Убедитесь, что идентификатор бота (Microsoft Entra идентификатор) зарегистрирован на портале разработчика Teams или через регистрацию канала бота Azure в Azure с включенным каналом Teams.
403	Код: `BotDisabledByAdmin` Сообщение. Администратор клиента отключил этот бот	Администратор клиента заблокировал взаимодействие между пользователем и приложением бота. Администратор клиента должен разрешить использование приложения для пользователя в политиках приложений. Дополнительные сведения см. в разделе Политики приложений.	Нет	Остановите публикацию в беседе до тех пор, пока пользователь явно не инициирует взаимодействие с ботом, указывая, что бот больше не заблокирован.
403	Код: `BotNotInConversationRoster` Сообщение. Бот не входит в список бесед.	Бот не является частью беседы. Приложение необходимо переустановить в беседе.	Нет	Перед отправкой другого запроса на беседу подождите `installationUpdate` событие, указывающее на то, что бот будет добавлен снова.
403	Код: `ConversationBlockedByUser` Сообщение. Пользователь заблокировал беседу с ботом.	Пользователь заблокировал бот в личном чате или канале с помощью параметров модерации.	Нет	Удалите беседу из кэша. Остановите попытки публикации в беседах, пока пользователь явно не инициирует взаимодействие с ботом, указывая, что бот больше не заблокирован.
403	Код: `ForbiddenOperationException` Сообщение. Бот не установлен в личных область пользователя	Упреждающее сообщение отправляется ботом, который не устанавливается в личных область.	Нет	Перед отправкой другого запроса на беседу установите приложение в личных область.
403	Код: `InvalidBotApiHost` Сообщение: Недопустимый узел API бота. Для клиентов GCC вызовите `https://smba.infra.gcc.teams.microsoft.com`.	Бот назвал общедоступную конечную точку API для беседы, которая принадлежит клиенту GCC.	Нет	Обновите URL-адрес службы для беседы `https://smba.infra.gcc.teams.microsoft.com` и повторите запрос.
403	Код: `NotEnoughPermissions` Сообщение: *сценарий	У бота нет необходимых разрешений для выполнения запрошенного действия.	Нет	Определите требуемое действие из сообщения об ошибке.
404	Код: `ActivityNotFoundInConversation` Сообщение: беседа не найдена.	Указанный идентификатор сообщения не найден в беседе. Сообщение не существует или удаляется.	Нет	Проверьте, является ли идентификатор отправленного сообщения ожидаемым значением. Удалите идентификатор, если он был кэширован.
404	Код: `ConversationNotFound` Сообщение: беседа не найдена.	Беседа не найдена, так как она не существует или удалена.	Нет	Проверьте, является ли отправленный идентификатор беседы ожидаемым значением. Удалите идентификатор, если он был кэширован.
412	Код: `PreconditionFailed` Сообщение. Сбой предварительного условия, повторите попытку.	Сбой предварительного условия для одной из зависимостей из-за нескольких одновременных операций в одном диалоге.	Да	Повторите попытку с экспоненциальной задержкой.
413	Код: `MessageSizeTooBig` Сообщение: слишком большой размер сообщения.	Размер входящего запроса был слишком велик. Дополнительные сведения см. в разделе Форматирование сообщений бота.	Нет	Уменьшите размер полезных данных.
429	Код: `Throttled` Сообщение: Слишком много запросов. Также возвращает время повторной попытки после.	Слишком много запросов, отправленных ботом. Дополнительные сведения см. в разделе Ограничение скорости.	Да	Повторите попытку с помощью `Retry-After` заголовка для определения времени отката.
500	Код: `ServiceError` Сообщение: *различные	Внутренняя ошибка сервера.	Нет	Сообщите о проблеме в сообществе разработчиков.
502	Код: `ServiceError` Сообщение: *различные	Проблема с зависимостью службы.	Да	Повторите попытку с экспоненциальной задержкой. Если проблема не исчезнет, сообщите о ней в сообществе разработчиков.
503		Служба недоступна.	Да	Повторите попытку с экспоненциальной задержкой. Если проблема не исчезнет, сообщите о ней в сообществе разработчиков.
504		Время ожидания шлюза.	Да	Повторите попытку с экспоненциальной задержкой. Если проблема не исчезнет, сообщите о ней в сообществе разработчиков.

Руководство по повторным попыткам кодов состояния

Общие рекомендации по повторным попыткам для каждого кода состояния перечислены в следующей таблице. Бот должен избегать повторных попыток кодов состояния, которые не указаны:

Код состояния	Стратегия повторных попыток
403	Повторите попытку, вызвав API `https://smba.infra.gcc.teams.microsoft.com` GCC для `InvalidBotApiHost`.
412	Повторите попытку с экспоненциальной задержкой.
429	Повторите попытку с помощью `Retry-After` заголовка, чтобы определить время ожидания в секундах и между запросами, если доступно. В противном случае повторите попытку с экспоненциальной задержкой с идентификатором потока, если это возможно.
502	Повторите попытку с экспоненциальной задержкой.
503	Повторите попытку с экспоненциальной задержкой.
504	Повторите попытку с экспоненциальной задержкой.

Пример кода

Название примера	Описание	Node.js	.NETCore	Python	.NET	Манифест
Бот для беседы в Teams	В этом примере приложения показано, как использовать различные события бесед бота, доступные в Bot Framework версии 4.	Просмотр	Просмотр	Просмотр	Н/Д	Просмотр
Локализация приложений Teams	В этом примере показана локализация приложений Teams с помощью бота и вкладки.	Просмотр	Недоступно	Недоступно	Просмотр	Н/Д

Следующее действие

Меню команд бота

Сообщения в беседах с ботами

Действие получения сообщения

Получение уведомления о прочтении

Отправка сообщения

Получение действия редактирования сообщения

Получение действия отмены сообщения

Получение действия с обратимым удалением сообщений

Отправка предлагаемых действий

Данные канала Teams

Пример объекта channelData

Содержимое сообщения

Сообщения с картинкой

Адаптивные карточки

Добавление уведомлений в сообщение

Коды состояния из интерфейсов API бесед бота

Руководство по повторным попыткам кодов состояния

Пример кода

Следующее действие

См. также

Обратная связь

Дополнительные ресурсы