Referência de API – API de Linha Direta 3.0

  • Artigo

Você pode habilitar seu aplicativo cliente para se comunicar com seu bot usando a API de Linha Direta 3.0. A API de Linha Direta 3.0 usa o padrão do setor REST e JSON sobre HTTPS.

URI base

Para acessar a API de Linha Direta 3.0, use um destes URIs base para todas as solicitações de API:

Dica

Uma solicitação pode falhar se você usar o URI de base global para um bot regional, pois algumas solicitações podem ir além dos limites geográficos.

Cabeçalhos

Além dos cabeçalhos de solicitação HTTP padrão, uma solicitação de API de Linha Direta deve incluir um cabeçalho Authorization, que especifica um segredo ou token para autenticação do cliente que está emitindo a solicitação. Especifique o cabeçalho Authorization usando este formato:

Authorization: Bearer SECRET_OR_TOKEN

Saiba mais sobre como obter um segredo ou token que pode ser usado por seu cliente para autenticar suas solicitações de API de Linha Direta em Autenticação.

Códigos de status HTTP

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

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 cliente não está autorizado a fazer a solicitação. Geralmente, esse código de status ocorre porque o cabeçalho Authorization está ausente ou malformado.
403 O cliente não tem permissão para executar a operação solicitada. A operação pode falhar pelos seguintes motivos.
  • Um token inválido: quando a solicitação usa um token que era válido anteriormente, mas expirou, a codepropriedade do Error retornado no objeto ErrorResponse é definida como TokenExpired.
  • Uma violação de limite de dados: se o bot for um bot regional, mas o URI Base não for regional, algumas solicitações poderão ultrapassar os limites geográficos.
  • Um recurso de destino inválido: o bot ou site de destino é inválido ou foi excluído.
404 O recurso solicitado não foi encontrado. Normalmente, esse código de status indica um URI de solicitação inválido.
500 Ocorreu um erro de servidor interno no serviço de Linha Direta.
502 O bot está indisponível ou retornou um erro. Esse é um código de erro comum.

Observação

O código de status HTTP 101 é usado no caminho de conexão de WebSocket, embora isso provavelmente seja tratado pelo seu cliente de WebSocket.

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.

Observação

Códigos de status HTTP e os valores especificados na propriedade code dentro do objeto ErrorResponse estão estáveis. Os valores especificados na propriedade message dentro do objeto ErrorResponse podem mudar ao longo do tempo.

Os snippets de código a seguir mostram um exemplo de solicitação e a resposta de erro resultante.

Solicitar

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

Response

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

Operações de token

Use essas operações para criar ou atualizar um token que um cliente pode usar para acessar uma conversa individual.

Operação Descrição
Gerar Token Gere um token para uma nova conversa.
Atualizar Token Atualize um token.

Gerar Token

Gera um token válido para uma conversa.

POST /v3/directline/tokens/generate
Conteúdo Descrição
Corpo da solicitação Um objeto TokenParameters
Retorna Um objeto Conversation

Atualizar Token

Atualiza o token.

POST /v3/directline/tokens/refresh
Conteúdo Descrição
Corpo da solicitação N/D
Retorna Um objeto Conversation

Operações de conversa

Use essas operações para abrir uma conversa com seu bot e trocar atividades entre o cliente e o bot.

Operação Descrição
Iniciar Conversa Abre uma nova conversa com o bot.
Obter Informações da Conversa Obtém informações sobre uma conversa existente. Essa operação gera uma nova URL de fluxo de WebSocket que um cliente pode usar para se reconectar a uma conversa.
Obter Atividades Recupera atividades do bot.
Enviar uma Atividade Envia uma atividade para o bot.
Carregar e enviar arquivo(s) Carrega e envia arquivo(s) como anexo(s).

Iniciar Conversa

Abre uma nova conversa com o bot.

POST /v3/directline/conversations
Conteúdo Descrição
Corpo da solicitação Um objeto TokenParameters
Retorna Um objeto Conversation

Obter Informações da Conversa

Obtém informações sobre uma conversa existente e também gera uma nova URL de fluxo de WebSocket que um cliente pode usar para se reconectar a uma conversa. Como opção, você pode fornecer o parâmetro watermark no URI da solicitação para indicar a mensagem mais recente vista pelo cliente.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Conteúdo Descrição
Corpo da solicitação N/D
Retorna Um objeto Conversation

Obter Atividades

Recupera atividades do bot da conversa especificada. Como opção, você pode fornecer o parâmetro watermark no URI da solicitação para indicar a mensagem mais recente vista pelo cliente.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Conteúdo Descrição
Corpo da solicitação N/D
Retorna Um objeto ActivitySet. A resposta contém watermark como uma propriedade do objeto ActivitySet. Os clientes devem percorrer as atividades disponíveis aprimorando o valor watermark até que nenhuma atividade retorne.

Enviar uma Atividade

Envia uma atividade para o bot.

POST /v3/directline/conversations/{conversationId}/activities
Conteúdo Descrição
Corpo da solicitação Um objeto Atividade
Retorna Um ResourceResponse que contém uma propriedade id que especifica a ID da Atividade que foi enviada ao bot.

Carregar e enviar arquivos

Carrega e envia arquivo(s) como anexo(s). Defina o parâmetro userId no URI da solicitação para especificar a ID do usuário que está enviando os anexos.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Conteúdo Descrição
Corpo da solicitação Para um único anexo, preencha o corpo da solicitação com o conteúdo do arquivo. Para vários anexos, crie um corpo de solicitação com várias partes, com uma parte para cada anexo, e também (opcionalmente) uma parte para o objeto Atividade que deve servir como contêiner para os anexos especificados. Saiba mais em Enviar uma atividade para o bot.
Retorna Um ResourceResponse que contém uma propriedade id que especifica a ID da Atividade que foi enviada ao bot.

Observação

Os arquivos carregados são excluídos após 24 horas.

Esquema

O esquema do Direct Line 3.0 inclui todos os objetos definidos pelo esquema do Bot Framework, assim como alguns objetos específicos do Direct Line.

Objeto ActivitySet

Define um conjunto de atividades.

Propriedade Type Descrição
activities Activity[] Matriz de objetos Atividade.
watermark string Marca-d'água máxima das atividades dentro do conjunto. Um cliente pode usar o valor watermark para indicar a mensagem mais recente vista, ao recuperar as atividades do bot ou ao gerar uma nova URL de fluxo de WebSocket.

Objeto Conversation

Define uma conversa de Linha Direta.

Propriedade Type Descrição
conversationId string ID que identifica exclusivamente a conversa para o qual o token especificado é válido.
eTag string Um ETag HTTP (marca de entidade).
expires_in número Número de segundos até a expiração do token.
referenceGrammarId string ID da gramática de referência desse bot.
streamUrl string URL para o fluxo de mensagens da conversa.
token string Token válido para a conversa especificada.

Objeto TokenParameters

Parâmetros para criar um token.

Propriedade Type Descrição
eTag string Um ETag HTTP (marca de entidade).
trustedOrigins string[] Origens confiáveis a serem inseridas no token.
usuário ChannelAccount Conta de usuário a ser inserida no token.

Atividades

Para cada Atividade que um cliente recebe de um bot via Linha Direta:

  • Cartões de anexo são preservados.
  • URLs para anexos carregados ficam ocultos com um link privado.
  • A propriedade channelData será preservada sem modificações.

Os clientes podem receber várias atividades do bot como parte de um ActivitySet.

Quando um cliente envia uma Activity para um bot via Direct Line:

  • A type propriedade especifica o tipo de atividade que está enviando (normalmente mensagem).
  • A propriedade from deve ser preenchida com uma ID de usuário escolhida pelo cliente.
  • Os anexos podem conter URLs para recursos existentes ou URLs carregado por meio do ponto de extremidade de anexo da Linha Direta.
  • A propriedade channelData será preservada sem modificações.
  • O tamanho total da atividade, quando serializada para o JSON e criptografada, não deve exceder 256 mil caracteres. Recomendamos que você mantenha as atividades abaixo de 150K. Se mais dados forem necessários, considere dividir a atividade ou usar anexos.

Os clientes podem enviar uma única atividade por solicitação.

Recursos adicionais