Referência de API – Direct Line API 3.0

Você pode habilitar seu aplicativo cliente para se comunicar com o bot usando Direct Line API 3.0. Direct Line API 3.0 usa REST e JSON padrão do setor por HTTPS.

URI Base

Para acessar Direct Line API 3.0, use uma destas URIs base para todas as solicitações de API:

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

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

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

Cabeçalhos

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

Authorization: Bearer SECRET_OR_TOKEN

Para obter detalhes sobre como obter um segredo ou token que seu cliente pode usar para autenticar suas solicitações de API Direct Line, consulte Autenticação.

Códigos de status HTTP

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

Errors

Qualquer resposta que especifica 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 resolva o problema antes de reenviar a solicitação.

Os snippets a seguir mostram uma solicitação de exemplo e a resposta de erro resultante.

Solicitação

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 de token

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

Gerar token

Gera um token válido para uma conversa.

POST /v3/directline/tokens/generate

Atualizar token

Atualiza o token.

POST /v3/directline/tokens/refresh

Operações de conversa

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

Iniciar a Conversa

Abre uma nova conversa com o bot.

POST /v3/directline/conversations

Obter informações de conversa

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

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

Obter atividades

Recupera atividades do bot para a conversa especificada. Opcionalmente, você pode fornecer o watermark parâmetro no URI de solicitação 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 arquivos

Carrega e envia arquivos como anexos. Defina o userId parâmetro 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}

Schema

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

Objeto ActivitySet

Define um conjunto de atividades.

Objeto Conversation

Define uma conversa Direct Line.

Objeto TokenParameters

Parâmetros para criar um token.

Activities

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

• Cartões de anexo são preservados.
• As URLs para anexos carregados estão ocultas com um link privado.
• A channelData propriedade é preservada sem modificação.

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

Quando um cliente envia um Activity bot por meio de Direct Line:

• A type propriedade especifica a atividade de tipo que está enviando (normalmente mensagem).
• A from propriedade deve ser preenchida com uma ID de usuário, escolhida pelo cliente.
• Anexos podem conter URLs para recursos ou URLs existentes carregados por meio do ponto de extremidade de anexo Direct Line.
• A channelData propriedade é preservada sem modificação.
• O tamanho total da atividade, quando serializada para JSON e criptografada, não deve exceder 256 mil caracteres. Recomendamos que você mantenha atividades abaixo de 150 mil. 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

• Especificação do protocolo de atividade