Compartilhar via


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

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.

Retornar à tabela de esquemas

Objeto AnimationCard

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

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.

Retornar à tabela de esquemas

Objeto Attachment

Define informações adicionais para incluir na mensagem. Um anexo pode ser um arquivo (como uma imagem, áudio ou vídeo) ou um cartão avançado.

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.

Retornar à tabela de esquemas

Objeto AttachmentData

Descreve os dados de um anexo.

Propriedade Type Descrição
name String Nome do anexo.
originalBase64 String Conteúdo do anexo.
thumbnailBase64 String Conteúdo em miniatura do anexo.
tipo String Tipo de conteúdo do anexo.

Retornar à tabela de esquemas

Objeto AttachmentInfo

Metadados de um anexo.

Propriedade Type Descrição
name String Nome do anexo.
tipo String Tipo de conteúdo do anexo.
modos de exibição AttachmentView[] Matriz de objetos AttachmentView que representam as exibições disponíveis para o anexo.

Retornar à tabela de esquemas

Objeto AttachmentView

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

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

Retornar à tabela de esquemas

Objeto AudioCard

Define um cartão que pode reproduzir um arquivo de áudio.

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.

Retornar à tabela de esquemas

Objeto CardAction

Define uma ação que pode ser clicada com um botã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.

Retornar à tabela de esquemas

Objeto CardImage

Define uma imagem para exibir em um cartão.

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

Retornar à tabela de esquemas

Objeto ChannelAccount

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

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.

Retornar à tabela de esquemas

Objeto ConversationAccount

Define uma conversa em um canal.

Propriedade Type Descrição
aadObjectId String A ID de objeto da conta no Microsoft Entra ID.
conversationType String Indica o tipo de conversa nos canais que diferenciam os tipos de conversas (por exemplo, grupo ou pessoal).
id String A ID que identifica a conversa. A ID é exclusiva por canal. Se o canal iniciar a conversa, ele definirá essa ID, caso contrário, o bot definirá essa propriedade como a ID que será retornada na resposta quando iniciar a conversa (confira Criar Conversa).
isGroup Booliano 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 em grupo, caso contrário, como false. O padrão é false.
name String Um nome de exibição que pode ser usado para identificar a conversa.
role String Função da entidade por trás da conta. Usuário ou bot.
tenantId String A ID de locatário da conversa.

Retornar à tabela de esquemas

Objeto ConversationMembers

Define os membros de uma conversa.

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

Retornar à tabela de esquemas

Objeto ConversationParameters

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

Retornar à tabela de esquemas

Objeto ConversationReference

Define um ponto específico em uma conversa.

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.

Retornar à tabela de esquemas

Objeto ConversationResourceResponse

Define uma resposta a Criar conversa.

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.

Retornar à tabela de esquemas

Objeto ConversationsResult

Define o resultado de Obter conversas.

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.

Retornar à tabela de esquemas

Objeto Entity

Objeto de metadados pertencente a uma atividade.

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

Retornar à tabela de esquemas

Objeto Error

Objeto representando informações de erro.

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.

Retornar à tabela de esquemas

Objeto ErrorResponse

Define uma resposta de API HTTP.

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

Retornar à tabela de esquemas

Objeto Fact

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

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.

Retornar à tabela de esquemas

Objeto GeoCoordinates

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

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.

Retornar à tabela de esquemas

Objeto HeroCard

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

Propriedade Type Descrição
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.
images CardImage[] Matriz de objetos CardImage que especifica a imagem a ser exibida no cartão. Um cartão Hero contém apenas uma imagem.
subtitle String Subtítulo a ser exibido sob o título do cartão.
tap CardAction Um objeto CardAction que especifica a ação a ser executada se o usuário tocar ou clicar no cartão. Essa pode ser a mesma ação que um dos botões ou uma ação diferente.
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.

Retornar à tabela de esquemas

Objeto InnerHttpError

Objeto representando um erro HTTP interno.

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.

Retornar à tabela de esquemas

Objeto MediaEventValue

Parâmetro suplementar para eventos de mídia.

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

Retornar à tabela de esquemas

Objeto MediaUrl

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

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.

Retornar à tabela de esquemas

Objeto Mention

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

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.

Retornar à tabela de esquemas

Objeto MessageReaction

Define uma reação a uma mensagem.

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

Retornar à tabela de esquemas

Objeto PagedMembersResult

Página de membros retornada por Obter Membros Paginados da Conversa.

Propriedade Type Descrição
continuationToken String O token de continuação que pode ser usado em chamadas posteriores a Obter Membros Paginados da Conversa.
members ChannelAccount[] Uma matriz de membros de conversa.

Retornar à tabela de esquemas

Objeto Place

Define um local que foi mencionado na conversa.

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.

Retornar à tabela de esquemas

Objeto ReceiptCard

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

Propriedade Type Descrição
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.
facts Fact[] Matriz de objetos Fato que especificam informações sobre a compra. Por exemplo, a lista de fatos para um recibo de hospedagem pode incluir a data de check-in e a data de check-out. O canal determina o número de fatos que podem ser especificados.
items ReceiptItem[] Matriz de objetos ReceiptItem que especificam os itens comprados
tap CardAction Um objeto CardAction que especifica a ação a ser executada se o usuário tocar ou clicar no cartão. Essa pode ser a mesma ação que um dos botões ou uma ação diferente.
tax 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 recebimento.
total String Uma cadeia de caracteres formatada em moeda que especifica o preço total de compra, incluindo todos os impostos aplicáveis.
vat String Uma cadeia de caracteres formatada como moeda que especifica o IVA (imposto sobre valor agregado) aplicado ao preço de compra.

Retornar à tabela de esquemas

Objeto ReceiptItem

Define um item de linha dentro de um recibo.

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.

Retornar à tabela de esquemas

Objeto ResourceResponse

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

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

Retornar à tabela de esquemas

Objeto SemanticAction

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

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.

Retornar à tabela de esquemas

Objeto SignInCard

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

Propriedade Type Descrição
buttons CardAction[] Matriz de objetos CardAction que permitem ao usuário entrar 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.

Retornar à tabela de esquemas

Objeto SuggestedActions

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

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.

Retornar à tabela de esquemas

Objeto TextHighlight

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

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.

Retornar à tabela de esquemas

Objeto ThumbnailCard

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

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

Retornar à tabela de esquemas

Objeto ThumbnailUrl

Define a URL para a fonte de uma imagem.

Propriedade Type Descrição
alt String Descrição da imagem. É necessário incluir a descrição para dar suporte à acessibilidade.
url String URL para a origem da imagem ou o binário base64 da imagem (por exemplo, data:image/png;base64,iVBORw0KGgo...).

Retornar à tabela de esquemas

Objeto Transcript

Uma coleção de atividades a ser carregada usando Enviar histórico da conversa.

Propriedade Type Descrição
activities matriz Uma matriz de objetos Atividade. Eles devem ter uma ID exclusiva e um carimbo de data/hora.

Retornar à tabela de esquemas

Objeto VideoCard

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

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

Retornar à tabela de esquemas