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

Artigo
10/27/2023

Nota

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 interagir com o Bot Framework é o SDK.

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

URI Base

Quando um usuário envia uma mensagem para seu bot, a solicitação de entrada contém um objeto Activity com uma serviceUrl propriedade que especifica o ponto de extremidade para o qual seu bot deve enviar sua resposta. Para acessar o serviço Bot Connector, use o valor como o serviceUrl URI 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, consulte como criar uma conversa e uma mensagem proativa no Teams.

Por exemplo, suponha que seu bot recebe a seguinte atividade quando o usuário envia uma mensagem para o 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 serviceUrl propriedade 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 desta conversa. Se o bot precisar enviar uma mensagem proativa para o usuário, salve o valor do 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 do pedido

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

Authorization: Bearer ACCESS_TOKEN

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

Cabeçalhos de resposta

Além dos cabeçalhos de resposta HTTP padrão, cada resposta conterá um X-Correlating-OperationId cabeçalho. O valor desse cabeçalho é uma ID que corresponde à entrada de log do Bot Framework, que contém detalhes sobre a solicitação. Quando você receber uma resposta de erro, você deve capturar o valor desse cabeçalho. Se não conseguir resolver o problema de forma independente, inclua este valor nas informações que fornece à equipa de Suporte quando comunica o problema.

Códigos de estado HTTP

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

Nota

A tabela a seguir descreve os códigos de status HTTP mais comuns. 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 estado de HTTP	Significado
200	O pedido foi bem-sucedido.
201	O pedido foi bem-sucedido.
202	O pedido foi aceite para processamento.
204	O pedido foi bem-sucedido, mas nenhum conteúdo foi devolvido.
400	O pedido estava mal formado ou incorreto.
401	O bot ainda não está autenticado.
403	O bot não está autorizado a executar a operação solicitada.
404	O recurso solicitado não foi encontrado.
405	O canal não suporta a operação solicitada.
500	Ocorreu um erro interno do servidor.
503	O serviço está temporariamente indisponível.

Erros

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ção

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

Importante

Nem todos os canais suportam todos os endpoints. No entanto, todos os canais devem suportar a resposta ao ponto de extremidade da atividade .

Por exemplo, apenas a Linha Direta e o Web Chat suportam o ponto de extremidade de obtenção de conversas .

Operation	Descrição
Criar conversação	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 dentro da conversa especificada.
Obter membro da conversação	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 de conversas nas quais o bot participou.
Responder à atividade	Envia uma atividade (mensagem) para a conversa especificada, como uma resposta à atividade especificada.
Enviar histórico de conversas	Carrega uma transcrição de atividades anteriores para a conversa.
Enviar para conversação	Envia uma atividade (mensagem) para o final da conversa especificada.
Atualizar atividade	Atualiza uma atividade existente.
Carregar anexo para o canal	Carrega um anexo diretamente no armazenamento de blob de um canal.

Criar conversa

Cria uma nova conversa.

POST /v3/conversations

Conteúdo	Descrição
Corpo do pedido	Um objeto ConversationParameters
Devoluções	Um objeto ConversationResourceResponse

Excluir atividade

Alguns canais permitem que você exclua uma atividade existente. Se bem-sucedida, essa operação remove a atividade especificada da conversa especificada.

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

Conteúdo	Descrição
Corpo do pedido	n/d
Devoluções	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 foi o último membro da conversa, a conversa também será excluída.

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

Conteúdo	Descrição
Corpo do pedido	n/d
Devoluções	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 dentro da conversa especificada.

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

Conteúdo	Descrição
Corpo do pedido	n/d
Devoluções	Uma matriz de objetos ChannelAccount

Obter conversas

Obtém uma lista de conversas nas quais o bot participou.

GET /v3/conversations?continuationToken={continuationToken}

Conteúdo	Descrição
Corpo do pedido	n/d
Devoluções	Um objeto ConversationsResult

Obter membro da conversação

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

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

Conteúdo	Descrição
Corpo do pedido	n/d
Devoluções	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 do pedido	n/d
Devoluções	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 do pedido	n/d
Devoluções	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 o canal a suportar. Se o canal não oferecer suporte a respostas aninhadas, essa operação se comportará como Enviar para conversa.

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

Conteúdo	Descrição
Corpo do pedido	Um objeto Activity
Devoluções	Um objeto ResourceResponse

Enviar histórico de conversas

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 do pedido	Um objeto Transcript .
Devoluções	Um objeto ResourceResponse .

Enviar para conversação

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 dentro da conversa, use Responder à atividade .

POST /v3/conversations/{conversationId}/activities

Conteúdo	Descrição
Corpo do pedido	Um objeto Activity
Devoluções	Um objeto ResourceResponse

Atualizar atividade

Alguns canais permitem editar uma atividade existente para refletir o novo estado de uma conversa de bot. Por exemplo, você pode remover botões de uma mensagem na conversa depois que o usuário clicou em um dos botões. Se for bem-sucedida, esta operação atualiza a atividade especificada na conversação especificada.

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

Conteúdo	Descrição
Corpo do pedido	Um objeto Activity
Devoluções	Um objeto ResourceResponse

Carregar anexo para o canal

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

POST /v3/conversations/{conversationId}/attachments

Conteúdo	Descrição
Corpo do pedido	Um objeto AttachmentData .
Devoluções	Um objeto ResourceResponse . A propriedade id especifica a ID do anexo que pode ser usada com a operação Obter informações de anexo e a operação Obter anexo.

Operações de penhora

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

Operation	Descrição
Obter informações do anexo	Obtém informações sobre o anexo especificado, incluindo nome de arquivo, tipo de arquivo e as exibições 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 de anexos

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

GET /v3/attachments/{attachmentId}

Conteúdo	Descrição
Corpo do pedido	n/d
Devoluções	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 do pedido	n/d
Devoluções	Conteúdo binário que representa a exibição especificada do anexo especificado

Operações estatais (preteridas)

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

Operation	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 de 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 dados de estado que foram armazenados anteriormente para um usuário.

Esquema

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

Objeto	Descrição
Objeto de atividade	Define uma mensagem que é trocada entre bot e usuário.
Objeto AnimationCard	Define um cartão que pode reproduzir GIFs animados ou vídeos curtos.
Objeto de anexo	Define informações adicionais a serem incluídas na mensagem. Um anexo pode ser um arquivo de mídia (por exemplo, áudio, vídeo, imagem, arquivo) ou um cartão rico.
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 uma placa que pode reproduzir um arquivo de áudio.
Objeto CardAction	Define uma ação a ser executada.
Objeto CardImage	Define uma imagem a ser exibida em um cartão.
Objeto ChannelAccount	Define um bot ou 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 para Criar conversa.
Objeto ConversationsResult	Define o resultado de uma chamada para Obter conversas.
Objeto da entidade	Define um objeto de entidade.
Objeto de erro	Define um erro.
Objeto ErrorResponse	Define uma resposta de API HTTP.
Objeto do facto	Define um par chave-valor que contém um fato.
Objeto GeoCoordinates	Define uma localização geográfica usando as coordenadas do World Geodetic System (WSG84).
Objeto HeroCard	Define um cartão com uma imagem grande, título, texto e botões de ação.
InnerHttpError objeto	Objeto que representa um erro HTTP interno.
Objeto MediaEventValue	Parâmetro suplementar para eventos de mídia.
Objeto MediaUrl	Define a URL para a origem de um arquivo de mídia.
Objeto de menção	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 Paged de Conversa.
Colocar objeto	Define um lugar que foi mencionado na conversa.
Objeto ReceiptCard	Define um cartão que contém um recibo de 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 programática.
Objeto SignInCard	Define um cartão que permite que um usuário entre em um serviço.
Objeto SuggestedActions	Define as opções entre as quais 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 o URL para a origem de uma imagem.
Objeto de transcrição	Uma coleção de atividades a serem carregadas usando o Enviar Histórico de Conversas.
Objeto VideoCard	Define um cartão que pode reproduzir vídeos.

Objeto de atividade

Define uma mensagem que é trocada entre bot e usuário.

Propriedade	Tipo	Descrição
action	String	A ação a aplicar ou que foi aplicada. Use a propriedade type para determinar o contexto da ação. Por exemplo, se type for contactRelationUpdate, o valor da propriedade action será adicionado se o usuário adicionou seu bot à lista de contatos ou removerá se removeu seu bot da lista de contatos.
attachmentLayout	String	Layout dos anexos de cartão avançados que a mensagem inclui. Um desses valores: carrossel, lista. Para obter mais informações sobre anexos de cartões avançados, consulte Adicionar anexos de cartões avançados a mensagens.
Anexos	Anexo[]	Matriz de objetos Attachment que define informações adicionais a serem incluídas na mensagem. Cada anexo pode ser um arquivo (por exemplo, áudio, vídeo, imagem) ou um cartão rico.
callerId	String	Uma cadeia de caracteres que contém um IRI que identifica o chamador de um bot. Este campo não se destina a ser transmitido através do fio, mas é preenchido por bots e clientes com base em dados criptograficamente verificáveis que afirmam 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	Um ID que identifica exclusivamente o canal. Definido pelo canal.
code	String	Código que indica por que a conversa terminou.
conversa	ConversaConta	Um objeto ConversationAccount que define a conversa à qual a atividade pertence.
Modo de entrega	String	Uma dica de entrega para sinalizar ao destinatário caminhos de entrega alternativos para a atividade. Um destes valores: normal, notificação.
entidades	objeto[]	Matriz de objetos que representa as entidades que foram mencionadas na mensagem. Os objetos nessa matriz podem ser qualquer objeto Schema.org . Por exemplo, a matriz pode incluir objetos Mention que identificam alguém que foi mencionado na conversa e objetos Place que identificam um local que foi mencionado na conversa.
expiração	String	O momento em que 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.
históriaDivulgado	Boolean	Sinalizador que indica se o histórico é divulgado ou não. O valor predefinido é falso.
id	String	ID que identifica exclusivamente a atividade no canal.
Importância	String	Define a importância de uma Atividade. Um destes valores: baixo, normal, alto.
inputDica	String	Valor que indica se o bot está aceitando, esperando ou ignorando a entrada do usuário depois que a mensagem é entregue ao cliente. Um destes valores: acceptingInput, expectingInput, ignoringInput.
rótulo	String	Um rótulo descritivo para a atividade.
ouvirPor	String[]	Lista de frases e referências que os sistemas de preparação da fala e da linguagem devem ouvir.
localidade	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 seu bot possa especificar cadeias de caracteres de exibição nesse idioma. O valor padrão é en-US.
carimbo localTimestamp	String	Data e hora em que a mensagem foi enviada no fuso horário local, expressa no formato ISO-8601 .
localFuso horário	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, América/Los_Angeles.
membrosAdicionado	ChannelAccount[]	Matriz de objetos ChannelAccount que representa a lista de usuários que ingressaram na conversa. Apresente somente se o tipo de atividade for "conversationUpdate" e os usuários tiverem ingressado na conversa.
membrosRemovido	ChannelAccount[]	Matriz de objetos ChannelAccount que representa a lista de usuários que saíram da conversa. Apresente somente se o tipo de atividade for "conversationUpdate" e os usuários deixarem a conversa.
Designação	Cadeia (de carateres)	Nome da operação a invocar ou o nome do evento.
reaçõesAdicionado	MensagemReação[]	A coleção de reações aumentou a conversa.
reaçõesRemovido	MensagemReação[]	A coleção de reações foi retirada da conversa.
destinatário	ChannelAccount	Um objeto ChannelAccount que especifica o destinatário da mensagem.
refere-se a	ConversaReferência	Um objeto ConversationReference que define um ponto específico em uma conversa.
replyToId	String	O ID da mensagem à qual esta 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 suportam respostas encadeadas. Nesses casos, o canal ignorará essa propriedade e usará semântica ordenada por tempo (carimbo de data/hora) para acrescentar a mensagem à conversa.
semanticAction	Ação Semântica	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. Definido pelo canal.
falar	String	Texto a ser falado pelo bot em um canal habilitado para fala. Para controlar várias características da fala do bot, como voz, taxa, volume, pronúncia e tom, especifique essa propriedade no formato SSML (Speech Synthesis Markup Language).
Ações sugeridas	Ações sugeridas	Um objeto SuggestedActions que define as opções das quais o usuário pode escolher.
Resumo	String	Resumo das informações contidas na mensagem. Por exemplo, para uma mensagem que é 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 de usuário para bot ou bot para usuário. Consulte a documentação do canal para ver os limites impostos ao conteúdo desta propriedade.
textFormat	String	Formato do texto da mensagem. Um destes valores: markdown, plain, xml. Para obter detalhes sobre o formato de texto, consulte Criar mensagens.
textoDestaques	TextoDestaque[]	A coleção de fragmentos de texto para realçar quando a atividade contém um valor replyToId .
Carimbo de data/hora	String	Data e hora em que a mensagem foi enviada no fuso horário UTC, expressa no formato ISO-8601 .
nome_tópico	String	Tema da conversa a que pertence a atividade.
tipo	String	Tipo de atividade. Um destes valores: message, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff. Para obter detalhes sobre os tipos de atividade, consulte Visão geral das atividades.
valor	Objeto	Valor aberto.
valueType	String	O tipo do objeto de valor da atividade.

Propriedade	Tipo	Descrição
Aspeto	Boolean	Proporção do espaço reservado para miniatura/mídia. Os valores permitidos são "16:9" e "4:3".
Autoloop \|	Boolean	Sinalizador que indica se a lista de GIFs animados deve ser repetida quando o último terminar. Defina essa propriedade como true para reproduzir automaticamente a animação, caso contrário, false. O valor padrão é true.
Início Automático	Boolean	Sinalizador que indica se a animação deve ser reproduzida automaticamente quando o cartão é exibido. Defina essa propriedade como true para reproduzir automaticamente a animação, caso contrário, false. O valor padrão é true.
botões	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.
Duração	String	O comprimento do conteúdo multimédia, no formato de duração ISO 8601.
imagem	ThumbnailUrl	Um objeto ThumbnailUrl que especifica a imagem a ser exibida no cartão.
MÍDIA	MediaUrl[]	Matriz de objetos MediaUrl . Quando este campo contém mais do que um URL, cada URL é um formato alternativo do mesmo conteúdo.
partilhável	Boolean	Sinalizador que indica se a animação pode ser compartilhada com outras pessoas. Defina essa propriedade como true se a animação puder ser compartilhada, caso contrário, false. O valor padrão é true.
subtítulo	String	Subtítulo para exibir sob o título do cartão.
text	String	Descrição ou prompt para exibir sob o título ou subtítulo do cartão.
title	String	Título do cartão.
valor	Objeto	Parâmetro suplementar para este cartão.

Propriedade	Tipo	Descrição
Conteúdo	Objeto	O conteúdo do anexo. Se o anexo for um rich card, defina essa propriedade como o objeto rich card. Esta 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 como tipos de mídia conhecidos, como image/png, audio/wav e video/mp4. Para cartões avançados, defina essa propriedade como um destes 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 content como um objeto AdaptiveCard . application/vnd.microsoft.card.animation: um cartão avançado que reproduz animação. Defina a propriedade content como um objeto AnimationCard . application/vnd.microsoft.card.audio: um cartão avançado que reproduz arquivos de áudio. Defina a propriedade content como um objeto AudioCard . application/vnd.microsoft.card.hero: Um cartão de herói. Defina a propriedade content como um objeto HeroCard . application/vnd.microsoft.card.receipt: um cartão de recibo. Defina a propriedade content como um objeto ReceiptCard . application/vnd.microsoft.card.signin: um cartão de entrada do usuário. Defina a propriedade content como um objeto SignInCard . application/vnd.microsoft.card.thumbnail: Um cartão de miniatura. Defina a propriedade content como um objeto ThumbnailCard . application/vnd.microsoft.card.video: um cartão avançado que reproduz vídeos. Defina a propriedade content como um objeto VideoCard .
contentUrl	String	URL do conteúdo do anexo. Por exemplo, se o anexo for uma imagem, você poderá definir contentUrl como a URL que representa o local da imagem. Os protocolos suportados são: HTTP, HTTPS, Arquivo e Dados.
Designação	Cadeia (de carateres)	Nome do anexo.
thumbnailUrl	String	URL para uma imagem em miniatura que o canal pode usar se suportar o uso de uma forma alternativa menor de conteúdo ou contentUrl. Por exemplo, se você definir contentType como application/word e definir contentUrl para o local do documento do Word, poderá incluir uma imagem em miniatura que represente o documento. O canal pode exibir a imagem em miniatura em vez do documento. Quando o usuário clica na imagem, o canal abre o documento.

Propriedade	Tipo	Descrição
tamanho	Número	Tamanho do ficheiro.
viewId	String	Ver ID.

Propriedade	Tipo	Descrição
Aspeto	String	Proporção da miniatura especificada na propriedade image . Os valores válidos são 16:9 e 4:3.
Autoloop \|	Boolean	Sinalizador que indica se a lista de arquivos de áudio deve ser reproduzida quando o último terminar. Defina essa propriedade como true para reproduzir automaticamente os arquivos de áudio, caso contrário, false. O valor padrão é true.
Início Automático	Boolean	Sinalizador que indica se o áudio deve ser reproduzido automaticamente quando o cartão é exibido. Defina essa propriedade como true para reproduzir automaticamente o áudio, caso contrário, false. O valor padrão é true.
botões	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.
Duração	String	O comprimento do conteúdo multimédia, no formato de duração ISO 8601.
imagem	ThumbnailUrl	Um objeto ThumbnailUrl que especifica a imagem a ser exibida no cartão.
MÍDIA	MediaUrl[]	Matriz de objetos MediaUrl . Quando este campo contém mais do que um URL, cada URL é um formato alternativo do mesmo conteúdo.
partilhável	Boolean	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.
subtítulo	String	Subtítulo para exibir sob o título do cartão.
text	String	Descrição ou prompt para exibir sob o título ou subtítulo do cartão.
title	String	Título do cartão.
valor	Objeto	Parâmetro suplementar para este cartão.

Propriedade	Tipo	Descrição
channelData	String	Dados específicos do canal associados a esta ação.
displayText	String	Texto a ser exibido no feed de bate-papo se o botão for clicado.
imagem	String	URL da imagem que aparecerá no botão, ao lado do rótulo de texto.
text	String	Texto da ação.
title	String	Descrição do texto que aparece no botão.
tipo	String	Tipo de ação a realizar. Para obter uma lista de valores válidos, consulte Adicionar anexos de cartão avançado a mensagens.
valor	Objeto	Parâmetro suplementar para a ação. O comportamento desta propriedade irá variar de acordo com o tipo de ação. Para obter mais informações, consulte Adicionar anexos de cartão avançado a mensagens.

Propriedade	Tipo	Descrição
Alt	String	Descrição da imagem. Você deve incluir a descrição para oferecer suporte à acessibilidade.
toque em	CardAction	Um objeto CardAction que especifica a ação a ser executada se o usuário tocar ou clicar na imagem.
URL	String	URL para a fonte da imagem ou o binário base64 da imagem (por exemplo, `data:image/png;base64,iVBORw0KGgo...`).

Propriedade	Tipo	Descrição
aadObjectId	String	ID de objeto desta conta no Microsoft Entra ID.
id	String	ID exclusivo para o usuário ou bot neste canal.
Designação	Cadeia (de carateres)	Nome amigável de exibição do bot ou usuário.
Função	String	Papel da entidade por trás da conta. Usuário ou bot.

Propriedade	Tipo	Descrição
id	String	O ID da conversa.
Membros	ChannelAccount[]	Lista de membros nesta conversa.

Propriedade	Tipo	Descrição
atividade	Atividade	A mensagem inicial a ser enviada para a conversa quando ela for criada.
bot	ChannelAccount	Informações da conta do canal necessárias para rotear uma mensagem para o bot.
channelData	Objeto	Carga útil específica do canal para criar a conversa.
isGroup	Boolean	Indica se esta é uma conversa de grupo.
Membros	ChannelAccount[]	Informações da conta do canal necessárias para encaminhar uma mensagem para cada usuário.
tenantId	String	O ID do locatário no qual a conversa deve ser criada.
nome_tópico	String	Tema da conversa. Essa propriedade só é usada se um canal oferecer suporte a ela.

Propriedade	Tipo	Description
activityId	Cadeia (de carateres)	ID que identifica exclusivamente a atividade à qual este objeto faz referência.
bot	ChannelAccount	Um objeto ChannelAccount que identifica o bot na conversa à qual esse objeto faz referência.
channelId	String	Um ID que identifica exclusivamente o canal na conversa a que este objeto faz referência.
conversa	ConversaConta	Um objeto ConversationAccount que define a conversa à qual esse objeto faz referência.
serviceUrl	String	URL que especifica o ponto de extremidade de serviço do canal na conversa a que este objeto faz referência.
Utilizador	ChannelAccount	Um objeto ChannelAccount que identifica o usuário na conversa à qual esse objeto faz referência.

Propriedade	Tipo	Description
activityId	Cadeia (de carateres)	ID da atividade, se enviado.
id	String	ID do recurso.
serviceUrl	String	Ponto de extremidade do serviço onde as operações relativas à conversação podem ser executadas.

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

Propriedade	Tipo	Descrição
code	String	Código de erro.
innerHttpError	InnerHttpError	Objeto que representa o erro HTTP interno.
mensagem	String	Uma descrição do erro.

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

Propriedade	Tipo	Descrição
elevação	Número	Elevação do local.
latitude	Número	Latitude do local.
longitude	Número	Longitude do local.
Designação	Cadeia (de carateres)	Nome do local.
tipo	String	O tipo deste objeto. Sempre definido como GeoCoordinates.

Propriedade	Tipo	Descrição
statusCode	Número	Código de status HTTP da solicitação com falha.
corpo	Objeto	Corpo do pedido falhado.

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

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

Propriedade	Tipo	Descrição
Endereço	Objeto	Endereço de um lugar. Esta propriedade pode ser uma cadeia de caracteres ou um objeto complexo do tipo PostalAddress.
Geo	GeoCoordenadas	Um objeto GeoCoordinates que especifica as coordenadas geográficas do local.
hasMapa	Objeto	Mapa para o local. Esta propriedade pode ser uma cadeia de caracteres (URL) ou um objeto complexo do tipo Map.
Designação	Cadeia (de carateres)	Nome do local.
tipo	String	Tipo deste objeto. Sempre definido como Lugar.

Propriedade	Tipo	Descrição
imagem	CardImage	Um objeto CardImage que especifica a imagem em miniatura a ser exibida ao lado do item de linha.
Preço	String	Uma cadeia de caracteres formatada em moeda que especifica o preço total de todas as unidades compradas.
Quantidade	String	Uma cadeia numérica que especifica o número de unidades compradas.
subtítulo	String	Subtítulo a ser exibido sob o título do item de linha.
toque em	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.

Share via

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

URI Base

Cabeçalhos

Cabeçalhos do pedido

Cabeçalhos de resposta

Códigos de estado HTTP

Erros

Operações de conversação

Criar conversa

Excluir atividade

Excluir membro da conversa

Obter membros da atividade

Obter conversas

Obter membro da conversação

Obter membros da conversa

Obter membros paginados da conversa

Responder à atividade

Enviar histórico de conversas

Enviar para conversação

Atualizar atividade

Carregar anexo para o canal

Operações de penhora

Obter informações de anexos

Obter anexo

Operações estatais (preteridas)

Esquema

Objeto de atividade

Objeto AnimationCard

Objeto de anexo

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 da entidade

Objeto de erro

Objeto ErrorResponse

Objeto do facto

Objeto GeoCoordinates

Objeto HeroCard

InnerHttpError objeto

Objeto MediaEventValue

Objeto MediaUrl

Objeto de menção

Objeto MessageReaction

Objeto PagedMembersResult

Colocar objeto

Objeto ReceiptCard

Objeto ReceiptItem

Objeto ResourceResponse

Objeto SemanticAction

Objeto SignInCard

Objeto SuggestedActions

Objeto TextHighlight

Objeto ThumbnailCard

Objeto ThumbnailUrl

Objeto de transcrição

Objeto VideoCard

Recursos adicionais

Propriedade	Tipo	Descrição
entidades	Objeto	Um objeto onde o valor de cada propriedade é um objeto Entity .
id	String	ID desta ação.
state	String	Estado desta ação. Valores permitidos: iniciar, continuar, concluído.

Propriedade	Tipo	Descrição
ações	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	Tipo	Descrição
ocorrência	Número	Ocorrência do campo de texto dentro do texto referenciado, se existirem vários.
text	String	Define o trecho de texto a ser destacado.

Propriedade	Tipo	Descrição
Aspeto	String	Proporção do vídeo. 16 :9 ou 4:3.
Autoloop \|	Boolean	Sinalizador que indica se a lista de vídeos deve ser repetida quando o último terminar. Defina essa propriedade como true para reproduzir automaticamente os vídeos, caso contrário, false. O valor padrão é true.
Início Automático	Boolean	Sinalizador que indica se os vídeos devem ser reproduzidos automaticamente quando o cartão é exibido. Defina essa propriedade como true para reproduzir automaticamente os vídeos, caso contrário, false. O valor padrão é true.
botões	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.
Duração	String	O comprimento do conteúdo multimédia, no formato de duração ISO 8601.
imagem	ThumbnailUrl	Um objeto ThumbnailUrl que especifica a imagem a ser exibida no cartão.
MÍDIA	MediaUrl[]	Matriz de MediaUrl. Quando este campo contém mais do que um URL, cada URL é um formato alternativo do mesmo conteúdo.
partilhável	Boolean	Sinalizador que indica se os vídeos podem ser compartilhados com outras pessoas. Defina essa propriedade como true se os vídeos puderem ser compartilhados, caso contrário, false. O valor padrão é true.
subtítulo	String	Subtítulo para exibir sob o título do cartão.
text	String	Descrição ou prompt para exibir sob o título ou subtítulo do cartão.
title	String	Título do cartão.
valor	Objeto	Parâmetro suplementar para este cartão