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

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.

Voltar à tabela Esquema

Objeto AnimationCard

Define um cartão que pode reproduzir GIFs animados ou vídeos curtos.

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.

Voltar à tabela Esquema

Objeto de anexo

Define informações adicionais a serem incluídas na mensagem. Um anexo pode ser um arquivo (como uma imagem, áudio ou vídeo) ou um cartão rico.

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.

Voltar à tabela Esquema

Objeto AttachmentData

Descreve os dados de um anexo.

Propriedade Tipo Descrição
Designação Cadeia (de carateres) Nome do anexo.
originalBase64 String Conteúdo do anexo.
thumbnailBase64 String Conteúdo da miniatura do anexo.
tipo String Tipo de conteúdo do anexo.

Voltar à tabela Esquema

Objeto AttachmentInfo

Metadados para um anexo.

Propriedade Tipo Descrição
Designação Cadeia (de carateres) Nome do anexo.
tipo String Tipo de conteúdo do anexo.
Modos de exibição AttachmentView[] Matriz de objetos AttachmentView que representam os modos de exibição disponíveis para o anexo.

Voltar à tabela Esquema

Objeto AttachmentView

Define um objeto que representa um modo de exibição disponível para um anexo.

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

Voltar à tabela Esquema

Objeto AudioCard

Define uma placa que pode reproduzir um arquivo de áudio.

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.

Voltar à tabela Esquema

Objeto CardAction

Define uma ação clicável com um botã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.

Voltar à tabela Esquema

Objeto CardImage

Define uma imagem a ser exibida em um cartão.

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...).

Voltar à tabela Esquema

Objeto ChannelAccount

Define um bot ou conta de usuário no canal.

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.

Voltar à tabela Esquema

Objeto ConversationAccount

Define uma conversa em um canal.

Propriedade Tipo Descrição
aadObjectId String ID de objeto desta conta no Microsoft Entra ID.
Tipo de conversação String Indica o tipo de conversa em canais que distinguem entre tipos de conversa (por exemplo, grupo ou pessoal).
id String O ID que identifica a conversa. O ID é exclusivo por canal. Se o canal iniciar a conversa, ele define esse ID; caso contrário, o bot define essa propriedade como a ID que ele recebe de volta na resposta quando inicia a conversa (consulte Criar conversa).
isGroup Boolean Sinalizar para indicar se a conversa contém mais de dois participantes no momento em que a atividade foi gerada. Defina como true se esta for uma conversa de grupo, caso contrário, false. O padrão é false.
Designação Cadeia (de carateres) Um nome de exibição que pode ser usado para identificar a conversa.
Função String Papel da entidade por trás da conta. Usuário ou bot.
tenantId String ID do locatário desta conversa.

Voltar à tabela Esquema

Objeto ConversationMembers

Define os membros de uma conversa.

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

Voltar à tabela Esquema

Objeto ConversationParameters

Define parâmetros para criar uma nova 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.

Voltar à tabela Esquema

Objeto ConversationReference

Define um ponto específico em uma conversa.

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.

Voltar à tabela Esquema

Objeto ConversationResourceResponse

Define uma resposta para Criar conversa.

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.

Voltar à tabela Esquema

Objeto ConversationsResult

Define o resultado de Obter conversas.

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.

Voltar à tabela Esquema

Objeto da entidade

Objeto de metadados pertencente a uma atividade.

Propriedade Tipo Descrição
tipo String Tipo desta entidade (RFC 3987 IRI).

Voltar à tabela Esquema

Objeto de erro

Objeto que representa informações de erro.

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.

Voltar à tabela Esquema

Objeto ErrorResponse

Define uma resposta de API HTTP.

Propriedade Tipo Descrição
erro Erro Um objeto Error que contém informações sobre o erro.

Voltar à tabela Esquema

Objeto do facto

Define um par chave-valor que contém um fato.

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.

Voltar à tabela Esquema

Objeto GeoCoordinates

Define uma localização geográfica usando as coordenadas do World Geodetic System (WSG84).

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.

Voltar à tabela Esquema

Objeto HeroCard

Define um cartão com uma imagem grande, título, texto e botões de ação.

Propriedade Tipo Descrição
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.
imagens CardImage[] Matriz de objetos CardImage que especifica a imagem a ser exibida no cartão. Um cartão de herói contém apenas uma imagem.
subtítulo String Subtítulo para exibir sob o título do cartão.
toque em CardAction Um objeto CardAction que especifica a ação a ser executada se o usuário tocar ou clicar no cartão. Esta pode ser a mesma ação que um dos botões ou uma ação diferente.
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.

Voltar à tabela Esquema

InnerHttpError objeto

Objeto que representa um erro HTTP interno.

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

Voltar à tabela Esquema

Objeto MediaEventValue

Parâmetro suplementar para eventos de mídia.

Propriedade Tipo Descrição
cardValue Objeto Parâmetro de retorno de chamada especificado no campo de valor do cartão de mídia que originou esse evento.

Voltar à tabela Esquema

Objeto MediaUrl

Define a URL para a origem de um arquivo de mídia.

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.

Voltar à tabela Esquema

Objeto de menção

Define um usuário ou bot que foi mencionado na conversa.

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.

Voltar à tabela Esquema

Objeto MessageReaction

Define uma reação a uma mensagem.

Propriedade Tipo Descrição
tipo String Tipo de reação. Ou like ou plusOne.

Voltar à tabela Esquema

Objeto PagedMembersResult

Página de membros retornada por Obter Membros Paged de Conversa.

Propriedade Tipo Descrição
continuationToken String O token de continuação que pode ser usado em chamadas subsequentes para Obter Membros Paged de Conversa.
Membros ChannelAccount[] Uma variedade de membros da conversa.

Voltar à tabela Esquema

Colocar objeto

Define um lugar que foi mencionado na conversa.

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.

Voltar à tabela Esquema

Objeto ReceiptCard

Define um cartão que contém um recibo de uma compra.

Propriedade Tipo Descrição
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.
Factos Fato[] Matriz de objetos Fact que especificam informações sobre a compra. Por exemplo, a lista de fatos para um recibo de estadia em hotel pode incluir a data de check-in e a data de check-out. O canal determina o número de fatos que você pode especificar.
itens ReceiptItem[] Matriz de objetos ReceiptItem que especificam os itens comprados
toque em CardAction Um objeto CardAction que especifica a ação a ser executada se o usuário tocar ou clicar no cartão. Esta pode ser a mesma ação que um dos botões ou uma ação diferente.
imposto String Uma cadeia de caracteres formatada em moeda que especifica o valor do imposto aplicado à compra.
title String Título exibido na parte superior do recibo.
total String Uma cadeia de caracteres formatada em moeda que especifica o preço total de compra, incluindo todos os impostos aplicáveis.
IVA String Uma cadeia de caracteres formatada em moeda que especifica o valor do imposto sobre valor agregado (IVA) aplicado ao preço de compra.

Voltar à tabela Esquema

Objeto ReceiptItem

Define um item de linha dentro de um recibo.

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.

Voltar à tabela Esquema

Objeto ResourceResponse

Define uma resposta que contém uma ID de recurso.

Propriedade Tipo Descrição
id String ID que identifica exclusivamente o recurso.

Voltar à tabela Esquema

Objeto SemanticAction

Define uma referência a uma ação programática.

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.

Voltar à tabela Esquema

Objeto SignInCard

Define um cartão que permite que um usuário entre em um serviço.

Propriedade Tipo Descrição
botões CardAction[] Matriz de objetos CardAction que permitem que o usuário entre em um serviço. O canal determina o número de botões que você pode especificar.
text String Descrição ou solicitação para incluir no cartão de entrada.

Voltar à tabela Esquema

Objeto SuggestedActions

Define as opções entre as quais um usuário pode escolher.

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.

Voltar à tabela Esquema

Objeto TextHighlight

Refere-se a uma substring de conteúdo dentro de outro campo.

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.

Voltar à tabela Esquema

Objeto ThumbnailCard

Define um cartão com uma imagem em miniatura, título, texto e botões de ação.

Propriedade Tipo Descrição
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.
imagens CardImage[] Matriz de objetos CardImage que especificam imagens em miniatura para exibição no cartão. O canal determina o número de imagens em miniatura que você pode especificar.
subtítulo String Subtítulo para exibir sob o título do cartão.
toque em CardAction Um objeto CardAction que especifica a ação a ser executada se o usuário tocar ou clicar no cartão. Esta pode ser a mesma ação que um dos botões ou uma ação diferente.
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.

Voltar à tabela Esquema

Objeto ThumbnailUrl

Define o URL para a origem de uma imagem.

Propriedade Tipo Descrição
Alt String Descrição da imagem. Você deve incluir a descrição para oferecer suporte à acessibilidade.
URL String URL para a fonte da imagem ou o binário base64 da imagem (por exemplo, data:image/png;base64,iVBORw0KGgo...).

Voltar à tabela Esquema

Objeto de transcrição

Uma coleção de atividades a serem carregadas usando o Enviar Histórico de Conversas.

Propriedade Tipo Descrição
Atividades matriz Uma matriz de objetos Activity . Cada um deles deve ter um ID e um carimbo de data/hora exclusivos.

Voltar à tabela Esquema

Objeto VideoCard

Define um cartão que pode reproduzir vídeos.

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

Voltar à tabela Esquema