Referência API - Direct Line API 3.0

Pode permitir que a sua aplicação cliente comunique com o seu bot usando a API Direct Line 3.0. A Direct Line API 3.0 utiliza REST e JSON padrão da indústria sobre HTTPS.

Base URI

Para aceder à Direct Line API 3.0, utilize um destes URIs base para todos os pedidos de API:

• Para bots globais, use https://directline.botframework.com

• Para um bot regional, introduza o seguinte uri de acordo com a região selecionada:

  Região	Base URI
  Europa	https://europe.directline.botframework.com
  Índia	https://india.directline.botframework.com

Cabeçalhos

Para além dos cabeçalhos padrão de pedido HTTP, um pedido API Direct Line deve incluir um Authorization cabeçalho que especifique um segredo ou token para autenticar o cliente que está a emitir o pedido. Especifique o Authorization cabeçalho usando este formato:

Authorization: Bearer SECRET_OR_TOKEN

Para detalhes sobre como obter um segredo ou token que o seu cliente possa usar para autenticar os seus pedidos da API Direct Line, consulte Autenticação.

Códigos de estado HTTP

O código de estado HTTP que é devolvido com cada resposta indica o resultado do pedido correspondente.

Errors

Qualquer resposta que especifique um código de estado HTTP no intervalo 4xx ou 5xx incluirá um objeto ErrorResponse no corpo da resposta que forneça informação sobre o erro. Se receber uma resposta de erro no intervalo 4xx, inspecione o objeto ErrorResponse para identificar a causa do erro e resolver o problema antes de submeter novamente o pedido.

Os excertos seguintes mostram um pedido de exemplo e a resposta de erro resultante.

Pedido

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

Resposta

HTTP/1.1 502 Bad Gateway
[other headers]

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

Operações com tokens

Use estas operações para criar ou atualizar um token que um cliente possa usar para aceder a uma única conversa.

Gerar Token

Gera um token válido para uma conversa.

POST /v3/directline/tokens/generate

Token de atualização

Atualiza o token.

POST /v3/directline/tokens/refresh

Operações de conversação

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

Iniciar Conversa

Abre uma nova conversa com o bot.

POST /v3/directline/conversations

Obtenha Informações sobre Conversas

Obtém informações sobre uma conversa existente e também gera um novo URL de fluxo WebSocket que um cliente pode usar para se reconectar a uma conversa. Pode, opcionalmente, fornecer o watermark parâmetro no URI do pedido para indicar a mensagem mais recente vista pelo cliente.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}

Receba Atividades

Recupera atividades do bot para a conversa especificada. Pode, opcionalmente, fornecer o watermark parâmetro no URI do pedido para indicar a mensagem mais recente vista pelo cliente.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

Enviar uma Atividade

Envia uma atividade para o bot.

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

Carregar e Enviar Ficheiro(s)

Carrega e envia ficheiro(s) como anexo(s). Defina o userId parâmetro no URI do pedido para especificar o ID do utilizador que está a enviar o(s) anexo(s).

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}

Schema

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

Objeto ActivitySet

Define um conjunto de atividades.

Objeto de conversa

Define uma conversa Direct Line.

Objeto TokenParameters

Parâmetros para criar um token.

Activities

Para cada atividade que um cliente recebe de um bot via Direct Line:

• Os cartões de anexo são preservados.
• Os URLs dos anexos carregados estão ocultos com um link privado.
• A channelData propriedade está preservada sem modificações.

Os clientes podem receber múltiplas atividades do bot como parte de um ActivitySet.

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

• A type propriedade especifica a atividade de tipo que está a enviar (normalmente mensagem).
• A from propriedade deve ser preenchida com um ID de utilizador, escolhido pelo cliente.
• Os anexos podem conter URLs para recursos existentes ou URLs carregados através do endpoint do anexo Direct Line.
• A channelData propriedade está preservada sem modificações.
• O tamanho total da atividade, quando serializada para JSON e encriptada, não pode exceder 256K caracteres. Recomendamos que mantenha as atividades abaixo dos 150 mil. Se forem necessários mais dados, considere dividir a atividade ou usar anexos.

Os clientes podem enviar uma única atividade por pedido.

Recursos adicionais

• Especificação do protocolo de atividade