Referência de API para o serviço do Bot Framework Connector

Artigo
12/27/2023

Observação

A API REST não é equivalente ao SDK. A API REST é fornecida para permitir a comunicação REST padrão, no entanto, o método preferido de interação com o Framework Bot é o SDK.

Dentro do Bot Framework, o serviço Bot Connector permite que seu bot troque mensagens com usuários em canais que são configurados no Portal do Bot Framework. O serviço usa REST padrão do setor e JSON por HTTPS.

URI base

Quando um usuário envia uma mensagem para o bot, a solicitação recebida contém um objeto Atividade com uma propriedade serviceUrl que especifica o ponto de extremidade para o qual o bot deve enviar a resposta. Para acessar o serviço do Bot Connector, use o valor serviceUrl como o URI de base para solicitações de API.

Quando você ainda não tiver uma URL de serviço para o canal, use https://smba.trafficmanager.net/teams/ como a URL de serviço. Para obter mais informações, confira como criar uma conversa e uma mensagem proativa no Teams.

Por exemplo, suponha que o bot receba a seguinte atividade quando o usuário envia uma mensagem ao bot.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/teams/",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

A propriedade serviceUrl dentro da mensagem do usuário indica que o bot deve enviar sua resposta para o ponto de extremidade https://smba.trafficmanager.net/teams/. A URL do serviço será o URI base para quaisquer solicitações subsequentes que o bot emita no contexto dessa conversa. Se o bot precisar enviar uma mensagem proativa ao usuário, salve o valor de serviceUrl.

O exemplo a seguir mostra a solicitação que o bot emite para responder à mensagem do usuário.

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de...
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have several times available on Saturday!",
    "replyToId": "bf3cc9a2f5de..."
}

Cabeçalhos

Cabeçalhos da solicitação

Além dos cabeçalhos de solicitação HTTP padrão, cada solicitação de API que você emitir deverá incluir um cabeçalho Authorization que especifique um token de acesso para autenticar o bot. Especifique o cabeçalho Authorization usando este formato:

Authorization: Bearer ACCESS_TOKEN

Para obter detalhes sobre como obter um token de acesso para o bot, consulte Autenticar solicitações do bot para o serviço do Bot Connector.

Cabeçalhos de resposta

Além dos cabeçalhos de resposta HTTP padrão, cada resposta conterá um cabeçalho X-Correlating-OperationId. O valor desse cabeçalho é uma ID que corresponde à entrada de log do Bot Framework que contém detalhes sobre a solicitação. Ao receber uma resposta de erro, você deverá capturar o valor desse cabeçalho. Se não for possível resolver o problema de maneira independente, inclua esse valor nas informações fornecidas à Equipe de suporte ao relatar o problema.

Códigos de status HTTP

O Código de status HTTP retornado com cada resposta indica o resultado da solicitação correspondente.

Observação

A tabela a seguir descreve as causas mais comuns dos códigos de status HTTP. Alguns erros são gerados pelo canal. Para obter mais informações, talvez seja necessário ler a documentação do desenvolvedor do canal.

Código de status de HTTP	Significado
200	Solicitação com êxito.
201	Solicitação com êxito.
202	A solicitação foi aceita para processamento.
204	A solicitação foi processada com êxito, mas nenhum conteúdo foi retornado.
400	A solicitação foi malformada ou está incorreta.
401	O bot ainda não está autenticado.
403	O bot não tem permissão para executar a operação solicitada.
404	O recurso solicitado não foi encontrado.
405	O canal não é compatível com a operação solicitada.
500	Ocorreu um erro interno no servidor.
503	O serviço está temporariamente indisponível.

Errors

Qualquer resposta que especifique um código de status HTTP no intervalo 4xx ou 5xx incluirá um objeto ErrorResponse no corpo da resposta que fornece informações sobre o erro. Se você receber uma resposta de erro no intervalo 4xx, inspecione o objeto ErrorResponse para identificar a causa do erro e resolver o problema antes de reenviar a solicitação.

Operações de conversa

Use essas operações para criar conversas, enviar mensagens (atividades) e gerenciar o conteúdo das conversas.

Importante

Nem todos os canais são compatíveis com todos os pontos de extremidade. No entanto, todos os canais devem oferecer suporte à resposta ao ponto de extremidade de atividade.

Por exemplo, somente a Direct Line e o Webchat oferecem suporte ao ponto de extremidade get conversations.

Operação	Descrição
Criar conversa	Cria uma nova conversa.
Excluir atividade	Exclui uma atividade existente.
Excluir membro da conversa	Remove um membro de uma conversa.
Obter membros da atividade	Obtém os membros da atividade especificada na conversa especificada.
Obter membro da conversa	Obtém detalhes sobre um membro de uma conversa.
Obter membros da conversa	Obtém os membros da conversa especificada.
Obter membros paginados da conversa	Obtém os membros da conversa especificada, uma página de cada vez.
Obter conversas	Obtém uma lista das conversas de que o bot participou.
Responder à atividade	Envia uma atividade (mensagem) para a conversa especificada, como uma resposta à atividade especificada.
Enviar histórico da conversa	Carrega uma transcrição de atividades anteriores para a conversa.
Enviar para conversa	Envia uma atividade (mensagem) para o final da conversa especificada.
Atualizar atividade	Atualiza uma atividade existente.
Carregar anexo ao canal	Carrega um anexo diretamente no armazenamento de blobs de um canal.

Criar conversa

Cria uma nova conversa.

POST /v3/conversations

Conteúdo	Descrição
Corpo da solicitação	Um objeto ConversationParameters
Retorna	Um objeto ConversationResourceResponse

Excluir atividade

Alguns canais permitem excluir uma atividade existente. Se tiver êxito, essa operação removerá a atividade especificada da conversa especificada.

DELETE /v3/conversations/{conversationId}/activities/{activityId}

Conteúdo	Descrição
Corpo da solicitação	N/D
Retorna	Um código de status HTTP que indica o resultado da operação. Nada é especificado no corpo da resposta.

Excluir membro da conversa

Remove um membro de uma conversa. Se esse membro for o último da conversa, a conversa também será excluída.

DELETE /v3/conversations/{conversationId}/members/{memberId}

Conteúdo	Descrição
Corpo da solicitação	N/D
Retorna	Um código de status HTTP que indica o resultado da operação. Nada é especificado no corpo da resposta.

Obter membros da atividade

Obtém os membros da atividade especificada na conversa especificada.

GET /v3/conversations/{conversationId}/activities/{activityId}/members

Conteúdo	Descrição
Corpo da solicitação	N/D
Retorna	Uma matriz de objetos ChannelAccount

Obter conversas

Obtém uma lista das conversas de que o bot participou.

GET /v3/conversations?continuationToken={continuationToken}

Conteúdo	Descrição
Corpo da solicitação	N/D
Retorna	Um objeto ConversationsResult

Obter membro da conversa

Obtém detalhes sobre um membro específico de uma conversa específica.

GET /v3/conversations/{conversationId}/members/{memberId}

Conteúdo	Descrição
Corpo da solicitação	N/D
Retorna	Um objeto ChannelAccount para o membro.

Obter membros da conversa

Obtém os membros da conversa especificada.

GET /v3/conversations/{conversationId}/members

Conteúdo	Descrição
Corpo da solicitação	N/D
Retorna	Uma matriz de objetos ChannelAccount para os membros da conversa.

Obter membros paginados da conversa

Obtém os membros da conversa especificada, uma página de cada vez.

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}

Conteúdo	Descrição
Corpo da solicitação	N/D
Retorna	Um objeto PagedMembersResult

Responder à atividade

Envia uma atividade (mensagem) para a conversa especificada, como uma resposta à atividade especificada. A atividade será adicionada como resposta a outra atividade, se houver suporte para isso no canal. Se o canal não der suporte a respostas aninhadas, essa operação se comportará como Enviar para conversa.

POST /v3/conversations/{conversationId}/activities/{activityId}

Conteúdo	Descrição
Corpo da solicitação	Um objeto Atividade
Retorna	Um objeto ResourceResponse

Enviar histórico da conversa

Carrega uma transcrição de atividades anteriores para a conversa para que o cliente possa renderizá-las.

POST /v3/conversations/{conversationId}/activities/history

Conteúdo	Descrição
Corpo da solicitação	Um objeto Transcript.
Retorna	Um objeto ResourceResponse.

Enviar para conversa

Envia uma atividade (mensagem) para a conversa especificada. A atividade será anexada ao final da conversa, de acordo com o carimbo de data/hora ou semântica do canal. Para responder a uma mensagem específica na conversa, use Responder à atividade.

POST /v3/conversations/{conversationId}/activities

Conteúdo	Descrição
Corpo da solicitação	Um objeto Atividade
Retorna	Um objeto ResourceResponse

Atualizar atividade

Alguns canais permitem editar uma atividade existente para refletir o novo estado de uma conversa de bot. Por exemplo, será possível remover botões de uma mensagem na conversa depois que o usuário clicar em um dos botões. Se tiver êxito, essa operação atualizará a atividade especificada dentro da conversa especificada.

PUT /v3/conversations/{conversationId}/activities/{activityId}

Conteúdo	Descrição
Corpo da solicitação	Um objeto Atividade
Retorna	Um objeto ResourceResponse

Carregar anexo ao canal

Carrega um anexo para a conversa especificada diretamente no armazenamento de blobs de um canal. Isso permite que você armazene dados em um armazenamento compatível.

POST /v3/conversations/{conversationId}/attachments

Conteúdo	Descrição
Corpo da solicitação	Um objeto AttachmentData.
Retorna	Um objeto ResourceResponse. A propriedade id especifica a ID do anexo que pode ser usado com a operação Obter informações do anexo e a operação Obter anexo.

Operações de Anexo

Use essas operações para recuperar informações sobre um anexo, bem como os dados binários para o próprio arquivo.

Operação	Descrição
Obter Informações do Anexo	Obtém informações sobre o anexo especificado, incluindo o nome e o tipo de arquivo e os modos de exibição disponíveis (por exemplo, original ou miniatura).
Obter anexo	Obtém a exibição especificada do anexo especificado como conteúdo binário.

Obter informações sobre anexos

Obtém informações sobre o anexo especificado, incluindo o nome e o tipo de arquivo e os modos de exibição disponíveis (por exemplo, original ou miniatura).

GET /v3/attachments/{attachmentId}

Conteúdo	Descrição
Corpo da solicitação	N/D
Retorna	Um objeto AttachmentInfo

Obter anexo

Obtém a exibição especificada do anexo especificado como conteúdo binário.

GET /v3/attachments/{attachmentId}/views/{viewId}

Conteúdo	Descrição
Corpo da solicitação	N/D
Retorna	Conteúdo binário que representa a exibição especificada do anexo especificado

Operações de estado (preterido)

O serviço de Estado do Microsoft Bot Framework foi desativado em 30 de março de 2018. Anteriormente, bots criados no Serviço de Bot de IA do Azure ou no SDK do Bot Builder tinham uma conexão padrão com esse serviço hospedado pela Microsoft para armazenar dados de estado do bot. Os bots deverão ser atualizados para usar seu próprio armazenamento de estado.

Operação	Descrição
`Set User Data`	Armazena dados de estado para um usuário específico em um canal.
`Set Conversation Data`	Armazena dados de estado para uma conversa específica em um canal.
`Set Private Conversation Data`	Armazena dados de estado para um usuário específico no contexto de uma conversa específica em um canal.
`Get User Data`	Recupera dados de estado que foram armazenados anteriormente para um usuário específico em todas as conversas em um canal.
`Get Conversation Data`	Recupera dados de estado que foram armazenados anteriormente para uma conversa específica em um canal.
`Get Private Conversation Data`	Recupera dados de estado que foram armazenados anteriormente para um usuário específico no contexto de uma conversa específica em um canal.
`Delete State For User`	Exclui os dados de estado que foram armazenados para um usuário.

Esquema

O esquema do Bot Framework define os objetos e suas propriedades que seu bot pode usar para se comunicar com um usuário.

Objeto	Descrição
Objeto Activity	Define uma mensagem trocada entre o bot e o usuário.
Objeto AnimationCard	Define um cartão que pode reproduzir GIFs animados ou vídeos curtos.
Objeto Attachment	Define informações adicionais para incluir na mensagem. Um anexo pode ser um arquivo de mídia (por exemplo, áudio, vídeo, imagem, arquivo) ou um cartão avançado.
Objeto AttachmentData	Descreve um anexo de dados.
Objeto AttachmentInfo	Descreve um anexo.
Objeto AttachmentView	Define um objeto que representa um modo de exibição disponível para um anexo.
Objeto AudioCard	Define um cartão que pode reproduzir um arquivo de áudio.
Objeto CardAction	Define uma ação para executar.
Objeto CardImage	Define uma imagem para exibir em um cartão.
Objeto ChannelAccount	Define um bot ou uma conta de usuário no canal.
Objeto ConversationAccount	Define uma conversa em um canal.
Objeto ConversationMembers	Define os membros de uma conversa.
Objeto ConversationParameters	Definir parâmetros para criar uma nova conversa
Objeto ConversationReference	Define um ponto específico em uma conversa.
Objeto ConversationResourceResponse	Define uma resposta a Criar conversa.
Objeto ConversationsResult	Define o resultado de uma chamada para Obter conversas.
Objeto Entity	Define um objeto de entidade.
Objeto Error	Define um erro.
Objeto ErrorResponse	Define uma resposta de API HTTP.
Objeto Fact	Define um par chave-valor que contém um fato.
Objeto GeoCoordinates	Define uma localização geográfica usando as coordenadas WSG84 (World Geodetic System).
Objeto HeroCard	Define um cartão com uma imagem grande, título, texto e botões de ação.
Objeto InnerHttpError	Objeto representando um erro HTTP interno.
Objeto MediaEventValue	Parâmetro suplementar para eventos de mídia.
Objeto MediaUrl	Define a URL para a fonte de um arquivo de mídia.
Objeto Mention	Define um usuário ou bot que foi mencionado na conversa.
Objeto MessageReaction	Define uma reação a uma mensagem.
Objeto PagedMembersResult	Página de membros retornada por Obter Membros Paginados da Conversa.
Objeto Place	Define um local que foi mencionado na conversa.
Objeto ReceiptCard	Define um cartão que contém um recibo para uma compra.
Objeto ReceiptItem	Define um item de linha dentro de um recibo.
Objeto ResourceResponse	Define um recurso.
Objeto SemanticAction	Define uma referência a uma ação através programática.
Objeto SignInCard	Define um cartão que permite ao usuário entrar em um serviço.
Objeto SuggestedActions	Define as opções que um usuário pode escolher.
Objeto TextHighlight	Refere-se a uma substring de conteúdo dentro de outro campo.
Objeto ThumbnailCard	Define um cartão com uma imagem em miniatura, título, texto e botões de ação.
Objeto ThumbnailUrl	Define a URL para a fonte de uma imagem.
Objeto Transcript	Uma coleção de atividades a ser carregada usando Enviar histórico da conversa.
Objeto VideoCard	Define um cartão que pode reproduzir vídeos.

Objeto de Atividade

Define uma mensagem trocada entre o bot e o usuário.

Propriedade	Type	Descrição
action	String	A ação a aplicar ou que foi aplicada. Use a propriedade tipo para determinar o contexto da ação. Por exemplo, se tipo for contactRelationUpdate, o valor da propriedade ação será adicionar se o usuário adicionou o bot à lista de contatos ou remover se o usuário removeu o bot da lista de contatos.
attachmentLayout	String	Layout dos anexos de cartão avançado que a mensagem inclui. Um desses valores: carrossel, lista. Para obter mais informações sobre anexos de cartão avançado, consulte Adicionar anexos de cartão avançado às mensagens.
attachments	Attachment[]	Matriz de objetos Anexo que define informações adicionais para incluir na mensagem. Cada anexo pode ser um arquivo (por exemplo, áudio, vídeo, imagem) ou um cartão avançado.
callerId	String	Uma cadeia de caracteres que contém um IRI que identifica o chamador de um bot. Esse campo não se destina a ser transmitido eletronicamente. Em vez disso, ele é preenchido por bots e clientes com base em dados verificáveis criptograficamente que declara a identidade dos chamadores (por exemplo, tokens).
channelData	Objeto	Um objeto que contém conteúdo específico do canal. Alguns canais fornecem recursos que exigem informações adicionais que não podem ser representadas usando o esquema de anexo. Para esses casos, defina essa propriedade para o conteúdo específico do canal, conforme definido na documentação do canal. Para obter mais informações, consulte Implementar funcionalidade específica do canal.
channelId	String	Uma ID que identifica exclusivamente o canal. Definida pelo canal.
code	String	Código indicando por que a conversa encerrou.
conversa	ConversationAccount	Um objeto ConversationAccount que define a conversa à qual a atividade pertence.
deliveryMode	String	Uma dica de entrega para sinalizar os caminhos de entrega alternativos do destinatário para a atividade. Um desses valores: normal, notification.
entidades	object[]	Matriz de objetos que representa as entidades mencionadas na mensagem. Objetos nessa matriz podem ser qualquer objeto Schema.org. Por exemplo, a matriz pode incluir objetos Menção que identificam alguém que foi mencionado na conversa e objetos Local que identificam um local mencionado na conversa.
expiration	String	A hora na qual a atividade deve ser considerada "expirada" e não deve ser apresentada ao destinatário.
from	ChannelAccount	Um objeto ChannelAccount que especifica o remetente da mensagem.
historyDisclosed	Booliano	Sinalizador que indica se o histórico é ou não divulgado. Valor padrão é falso.
id	String	ID que identifica exclusivamente a atividade no canal.
importance	String	Define a importância de uma Atividade. Um destes valores: low, normal, high.
inputHint	String	Valor que indica se o bot está aceitando, esperando ou ignorando a entrada do usuário após a entrega da mensagem ao cliente. Um desses valores: acceptingInput, expectingInput, ignoringInput.
label	String	Um rótulo descritivo da atividade.
listenFor	String[]	Lista de frases e referências que os sistemas de preparação da fala e de linguagem devem escutar.
locale	String	Localidade do idioma que deve ser usado para exibir texto dentro da mensagem, no formato `<language>-<country>`. O canal usa essa propriedade para indicar o idioma do usuário, para que o bot possa especificar cadeia de caracteres de exibição nesse idioma. O valor padrão é en-US.
localTimestamp	String	Data e hora em que a mensagem foi enviada no fuso horário local, expressa no formato ISO-8601.
localTimezone	String	Contém o nome do fuso horário local da mensagem, expresso no formato de banco de dados de fuso horário IANA. Por exemplo, America/Los_Angeles.
membersAdded	ChannelAccount[]	Matriz de objetos ChannelAccount que representam a lista de usuários que participaram da conversa. Presente apenas se a atividade tipo for "conversationUpdate" e os usuários ingressarem na conversa.
membersRemoved	ChannelAccount[]	Matriz de objetos ChannelAccount que representam a lista de usuários que saíram da conversa. Presente apenas se a atividade tipo for "conversationUpdate" e os usuários saírem da conversa.
name	String	Nome da operação a invocar ou o nome do evento.
reactionsAdded	MessageReaction[]	A coleção de reações adicionadas à conversa.
reactionsRemoved	MessageReaction[]	A coleção de reações removidas da conversa.
recipient	ChannelAccount	Um objeto ChannelAccount que especifica o destinatário da mensagem.
relatesTo	ConversationReference	Um objeto ConversationReference que define um ponto específico em uma conversa.
replyToId	String	A ID da mensagem à qual essa mensagem responde. Para responder a uma mensagem que o usuário enviou, defina essa propriedade como a ID da mensagem do usuário. Nem todos os canais dão suporte a respostas encadeadas. Nesses casos, o canal ignorará essa propriedade e usará a semântica ordenada por tempo (carimbo de data/hora) para acrescentar a mensagem à conversa.
semanticAction	SemanticAction	Um objeto SemanticAction que representa uma referência a uma ação programática.
serviceUrl	String	URL que especifica o ponto de extremidade de serviço do canal. Definida pelo canal.
speak	String	Texto a ser falado pelo bot em um canal habilitado para fala. Para controlar várias características de fala do bot como voz, velocidade, volume, pronúncia e tom, especifique essa propriedade no formato SSML (Linguagem de Marcação de Sintetização de Voz).
suggestedActions	SuggestedActions	Um objeto SuggestedActions que define as opções a partir das quais o usuário poderá escolher.
summary	String	Resumo das informações que a mensagem contém. Por exemplo, para uma mensagem enviada em um canal de email, essa propriedade pode especificar os primeiros 50 caracteres da mensagem de email.
text	String	Texto da mensagem que é enviada do usuário para o bot ou do bot para o usuário. Consulte a documentação do canal para os limites impostos sobre o conteúdo dessa propriedade.
textFormat	String	Formato do texto da mensagem. Um desses valores: markdown, plain, xml. Para detalhes sobre o formato de texto, consulte Criar mensagens.
textHighlights	TextHighlight[]	A coleção de fragmentos de texto a serem realçados quando a atividade contém um valor replyToId.
timestamp	String	Data e hora em que a mensagem foi enviada no fuso horário UTC, expressa no formato ISO-8601.
topicName	String	Tópico da conversa à qual a atividade pertence.
tipo	String	Tipo de atividade. Um destes valores: message, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff. Para detalhes sobre tipos de atividade, consulte Visão geral das atividades.
value	Objeto	Valor em aberto.
valueType	String	O tipo do objeto de valor da atividade.

Propriedade	Type	Descrição
aspect	Booliano	Taxa de proporção do espaço reservado de miniatura/mídia. Os valores permitidos são “16:9” e “4:3”.
autoloop	Booliano	Sinalizador que indica se deve repetir a lista de GIFs animados quando o último encerrar. Configure essa propriedade como true para reproduzir automaticamente a animação, caso contrário, como false. O valor padrão é true.
autostart	Booliano	Sinalizador que indica se deverá reproduzir automaticamente a animação quando o cartão for exibido. Defina essa propriedade como true para reproduzir automaticamente a animação, caso contrário, como false. O valor padrão é true.
buttons	CardAction[]	Matriz de objetos CardAction que permitem ao usuário executar uma ou mais ações. O canal determina o número de botões que você pode especificar.
duration	String	O comprimento do conteúdo de mídia, no formato de duração ISO 8601.
imagem	ThumbnailUrl	Um objeto ThumbnailUrl que especifica a imagem a ser exibida no cartão.
media	MediaUrl[]	Matriz de objetos MediaUrl. Quando esse campo contém mais de uma URL, cada URL é um formato alternativo do mesmo conteúdo.
shareable	Booliano	Sinalizador que indica se a animação pode ser compartilhada com outras pessoas. Configure esta propriedade para true se a animação puder ser compartilhada, caso contrário, para false. O valor padrão é true.
subtitle	String	Subtítulo a ser exibido sob o título do cartão.
text	String	Descrição ou solicitação para exibir sob o título ou subtítulo do cartão.
title	String	Título do cartão.
value	Objeto	Parâmetro suplementar para esse cartão.

Propriedade	Type	Descrição
content	Objeto	O conteúdo do anexo. Se o anexo for um cartão avançado, defina essa propriedade para o objeto cartão avançado. Essa propriedade e a propriedade contentUrl são mutuamente exclusivas.
contentType	String	O tipo de mídia do conteúdo no anexo. Para arquivos de mídia, defina essa propriedade para tipos de mídia conhecidos, como image/png, audio/wav e video/mp4. Para cartões avançados, defina essa propriedade para um desses tipos específicos do fornecedor: application/vnd.microsoft.card.adaptive: um cartão avançado que pode conter qualquer combinação de texto, fala, imagens, botões e campos de entrada. Defina a propriedade de conteúdo para um objeto AdaptiveCard. application/vnd.microsoft.card.animation: um cartão avançado que reproduz animação. Defina a propriedade de conteúdo para um objeto AnimationCard. application/vnd.microsoft.card.audio: um cartão avançado que reproduz arquivos de áudio. Defina a propriedade de conteúdo como um objeto AudioCard. application/vnd.microsoft.card.hero: um cartão Hero. Defina e propriedade de conteúdo para um objeto HeroCard. application/vnd.microsoft.card.receipt: um cartão de recebimento. Defina e propriedade de conteúdo para um objeto ReceiptCard. application/vnd.microsoft.card.signin: um cartão de entrada do usuário. Defina e propriedade de conteúdo para um objeto SignInCard. application/vnd.microsoft.card.thumbnail: um cartão de Miniatura. Defina a propriedade de conteúdo para um objeto ThumbnailCard. application/vnd.microsoft.card.video: um cartão avançado que reproduz vídeos. Defina a propriedade de conteúdo para um objeto VideoCard.
contentUrl	String	URL para o conteúdo do anexo. Por exemplo, se o anexo for uma imagem, será possível definir contentUrl como a URL que representa o local da imagem. Os protocolos com suporte são: HTTP, HTTPS, arquivo e dados.
name	String	Nome do anexo.
thumbnailUrl	String	URL para uma imagem em miniatura que o canal pode usar se for compatível com o uso de uma forma alternativa menor de conteúdo ou contentUrl. Por exemplo, se você definir contentType como application/word e definir contentUrl como o local do documento do Word, talvez inclua uma imagem em miniatura que represente o documento. O canal pode exibir a imagem em miniatura em vez do documento. Quando o usuário clicar na imagem, o canal abrirá o documento.

Propriedade	Type	Descrição
size	Número	Tamanho do arquivo.
viewId	String	ID da exibição.

Propriedade	Type	Descrição
aspect	String	Proporção da miniatura especificada na propriedade da imagem. Os valores válidos são 16:9 e 4:3.
autoloop	Booliano	Sinalizador que indica se deverá reproduzir a lista de arquivos de áudio quando o último encerrar. Defina essa propriedade como true para reproduzir automaticamente os arquivos de áudio, caso contrário, como false. O valor padrão é true.
autostart	Booliano	Sinalizador que indica se deverá reproduzir automaticamente o áudio quando o cartão for exibido. Defina essa propriedade como true para reproduzir automaticamente o áudio, caso contrário, como false. O valor padrão é true.
buttons	CardAction[]	Matriz de objetos CardAction que permitem ao usuário executar uma ou mais ações. O canal determina o número de botões que você pode especificar.
duration	String	O comprimento do conteúdo de mídia, no formato de duração ISO 8601.
imagem	ThumbnailUrl	Um objeto ThumbnailUrl que especifica a imagem a ser exibida no cartão.
media	MediaUrl[]	Matriz de objetos MediaUrl. Quando esse campo contém mais de uma URL, cada URL é um formato alternativo do mesmo conteúdo.
shareable	Booliano	Sinalizador que indica se os arquivos de áudio podem ser compartilhados com outras pessoas. Defina essa propriedade como true se o áudio puder ser compartilhado, caso contrário, false. O valor padrão é true.
subtitle	String	Subtítulo a ser exibido sob o título do cartão.
text	String	Descrição ou solicitação para exibir sob o título ou subtítulo do cartão.
title	String	Título do cartão.
value	Objeto	Parâmetro suplementar para esse cartão.

Propriedade	Type	Descrição
channelData	String	Dados específicos do canal associados a esta ação.
displayText	String	Texto a ser exibido no feed do chat se o botão receber cliques.
imagem	String	URL da imagem que será exibida no botão, ao lado do rótulo de texto.
text	String	Texto da ação.
title	String	Descrição de texto exibida no botão.
tipo	String	Tipo de ação a ser executada. Para obter uma lista de valores válidos, consulte Adicionar anexos de cartão avançado às mensagens.
value	Objeto	Parâmetro suplementar para a ação. O comportamento dessa propriedade variará de acordo com a ação tipo. Para obter mais informações, consulte Adicionar anexos de cartão avançado às mensagens.

Propriedade	Type	Descrição
alt	String	Descrição da imagem. É necessário incluir a descrição para dar suporte à acessibilidade.
tap	CardAction	Um objeto CardAction que especificará a ação a ser executada se o usuário tocar ou clicar na imagem.
url	String	URL para a origem da imagem ou o binário base64 da imagem (por exemplo, `data:image/png;base64,iVBORw0KGgo...`).

Propriedade	Type	Descrição
aadObjectId	String	A ID de objeto da conta no Microsoft Entra ID.
id	String	ID exclusiva para o usuário ou bot neste canal.
name	String	Exibir nome amigável do bot ou do usuário.
role	String	Função da entidade por trás da conta. Usuário ou bot.

Propriedade	Type	Descrição
id	String	A ID da conversa.
members	ChannelAccount[]	Lista de membros nesta conversa.

Propriedade	Type	Descrição
activity	Atividade	A mensagem inicial a ser enviada para a conversa quando ela for criada.
bot	ChannelAccount	Informações de conta do canal necessárias para rotear uma mensagem para o bot.
channelData	Objeto	Conteúdo específico do canal para criar a conversa.
isGroup	Booliano	Indica se essa é uma conversa em grupo.
members	ChannelAccount[]	Informações de conta do canal necessárias para rotear uma mensagem para cada usuário.
tenantId	String	A ID de locatário na qual a conversa deve ser criada.
topicName	String	Tópico da conversa. Essa propriedade será usada apenas se um canal der suporte.

Propriedade	Type	Description
activityId	String	ID que identifica exclusivamente a atividade à qual esse objeto faz referência.
bot	ChannelAccount	Um objeto ChannelAccount que identifica o bot na conversa à qual esse objeto faz referência.
channelId	String	Uma ID que identifica exclusivamente o canal na conversa à qual esse objeto faz referência.
conversa	ConversationAccount	Um objeto ConversationAccount que define a conversação à qual esse objeto faz referência.
serviceUrl	String	URL que especifica o ponto de extremidade de serviço do canal na conversa à qual esse objeto faz referência.
usuário	ChannelAccount	Um objeto ChannelAccount que identifica o usuário na conversa à qual esse objeto faz referência.

Propriedade	Type	Description
activityId	String	ID da atividade, se enviada.
id	String	ID do recurso.
serviceUrl	String	Ponto de extremidade de serviço em que as operações relacionadas à conversa podem ser executadas.

Propriedade	Type	Descrição
conversations	ConversationMembers[]	Os membros em cada uma das conversas.
continuationToken	String	O token de continuação que pode ser usado em chamadas posteriores a Obter conversas.

Propriedade	Type	Descrição
code	String	Código do erro.
innerHttpError	InnerHttpError	Objeto representando o erro HTTP interno.
message	String	Uma descrição do erro.

Propriedade	Type	Descrição
chave	String	Nome do fato. Por exemplo, Check-in. A chave é usada como um rótulo ao exibir o valor do fato.
value	String	Valor do fato. Por exemplo, 10 de outubro de 2016.

Propriedade	Type	Descrição
elevation	Número	Elevação da localização.
latitude	Número	Latitude da localização.
longitude	Número	Longitude da localização.
name	String	Nome da localização.
tipo	String	O tipo desse objeto. Sempre definido para GeoCoordinates.

Propriedade	Type	Descrição
statusCode	Número	Código de status HTTP da solicitação com falha.
Corpo	Objeto	Corpo da solicitação com falha.

Propriedade	Type	Descrição
profile	String	Dica que descreve o conteúdo da mídia.
url	String	URL para a origem do arquivo de mídia.

Propriedade	Type	Descrição
mentioned	ChannelAccount	Um objeto ChannelAccount que especifica o usuário ou o bot que foi mencionado. Alguns canais, como Slack, atribuem nomes por conversa, portanto, é possível que o nome mencionado do bot (na propriedade do destinatário da mensagem) seja diferente do identificador especificado quando você registrou o bot. No entanto, as IDs da conta para ambos seriam as mesmas.
text	String	O usuário ou bot como mencionado na conversa. Por exemplo, se a mensagem for "@ColorBot escolha uma nova cor para mim," essa propriedade será definida como @ColorBot. Nem todos os canais definem essa propriedade.
tipo	String	Tipo desse objeto. Sempre defina para Menção.

Propriedade	Type	Descrição
address	Objeto	Endereço de um local. Essa propriedade pode ser uma cadeia de caracteres ou um objeto complexo do tipo PostalAddress.
geo	GeoCoordinates	Um objeto GeoCoordinates que especifica as coordenadas geográficas do lugar.
hasMap	Objeto	Mapa para o local. Essa propriedade pode ser uma cadeia de caracteres (URL) ou um objeto complexo do tipo Map.
name	String	Nome do local.
tipo	String	Tipo desse objeto. Sempre defina para Local.

Propriedade	Type	Descrição
imagem	CardImage	Um objeto CardImage que especifica a imagem em miniatura para exibir ao lado do item de linha.
price	String	Uma cadeia de caracteres formatada como moeda que especifica o preço total de todas as unidades compradas.
quantity	String	Uma cadeia numérica que especifica o número de unidades compradas.
subtitle	String	Subtítulo a ser exibido abaixo do título do item de linha.
tap	CardAction	Um objeto CardAction que especifica a ação a ser executada se o usuário tocar ou clicar no item de linha.
text	String	Descrição do item de linha.
title	String	Título do item de linha.

Compartilhar via

Referência de API para o serviço do Bot Framework Connector

URI base

Cabeçalhos

Cabeçalhos da solicitação

Cabeçalhos de resposta

Códigos de status HTTP

Errors

Operações de conversa

Criar conversa

Excluir atividade

Excluir membro da conversa

Obter membros da atividade

Obter conversas

Obter membro da conversa

Obter membros da conversa

Obter membros paginados da conversa

Responder à atividade

Enviar histórico da conversa

Enviar para conversa

Atualizar atividade

Carregar anexo ao canal

Operações de Anexo

Obter informações sobre anexos

Obter anexo

Operações de estado (preterido)

Esquema

Objeto de Atividade

Objeto AnimationCard

Objeto Attachment

Objeto AttachmentData

Objeto AttachmentInfo

Objeto AttachmentView

Objeto AudioCard

Objeto CardAction

Objeto CardImage

Objeto ChannelAccount

Objeto ConversationAccount

Objeto ConversationMembers

Objeto ConversationParameters

Objeto ConversationReference

Objeto ConversationResourceResponse

Objeto ConversationsResult

Objeto Entity

Objeto Error

Objeto ErrorResponse

Objeto Fact

Objeto GeoCoordinates

Objeto HeroCard

Objeto InnerHttpError

Objeto MediaEventValue

Objeto MediaUrl

Objeto Mention

Objeto MessageReaction

Objeto PagedMembersResult

Objeto Place

Objeto ReceiptCard

Objeto ReceiptItem

Objeto ResourceResponse

Objeto SemanticAction

Objeto SignInCard

Objeto SuggestedActions

Objeto TextHighlight

Objeto ThumbnailCard

Objeto ThumbnailUrl

Objeto Transcript

Objeto VideoCard

Recursos adicionais

Propriedade	Type	Descrição
entidades	Objeto	Um objeto em que o valor de cada propriedade é um objeto Entity.
id	String	ID desta ação.
state	String	Estado desta ação. Valores permitidos: start, continue, done.

Propriedade	Type	Descrição
actions	CardAction[]	Matriz de objetos CardAction que definem as ações sugeridas.
to	String[]	Matriz de cadeias de caracteres que contém as IDs dos destinatários para os quais as ações sugeridas devem ser exibidas.

Propriedade	Type	Descrição
occurrence	Número	Ocorrência do campo de texto dentro do texto referenciado, se houver vários.
text	String	Define o snippet de texto a ser realçado.

Propriedade	Type	Descrição
aspect	String	Taxa de proporção do vídeo. 16:9 ou 4:3.
autoloop	Booliano	Sinalizador que indica se deverá reproduzir a lista de vídeos quando o último encerrar. Defina esta propriedade como true para reproduzir automaticamente os vídeos, caso contrário, como false. O valor padrão é true.
autostart	Booliano	Sinalizador que indica se deverá reproduzir automaticamente os vídeos quando o cartão for exibido. Defina essa propriedade para true para reproduzir automaticamente os vídeos, caso contrário, como false. O valor padrão é true.
buttons	CardAction[]	Matriz de objetos CardAction que permitem ao usuário executar uma ou mais ações. O canal determina o número de botões que você pode especificar.
duration	String	O comprimento do conteúdo de mídia, no formato de duração ISO 8601.
imagem	ThumbnailUrl	Um objeto ThumbnailUrl que especifica a imagem a ser exibida no cartão.
media	MediaUrl[]	Matriz de MediaUrl. Quando esse campo contém mais de uma URL, cada URL é um formato alternativo do mesmo conteúdo.
shareable	Booliano	Sinalizador que indica se os vídeos podem ser compartilhados com outras pessoas. Defina esta propriedade para true se os vídeos puderem ser compartilhados, caso contrário, como false. O valor padrão é true.
subtitle	String	Subtítulo a ser exibido sob o título do cartão.
text	String	Descrição ou solicitação para exibir sob o título ou subtítulo do cartão.
title	String	Título do cartão.
value	Objeto	Parâmetro suplementar para esse cartão