Referência de API – API de Linha Direta 1.1

Artigo
03/08/2023

Importante

Este artigo contém informações de referência para a API de Linha Direta 1.1. Se você estiver criando uma nova conexão entre o aplicativo cliente e o bot, use Direct Line API 3.0.

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

URI de base

Para acessar a API de Linha Direta 1.1, use esta URI de base para todas as solicitações de API:

https://directline.botframework.com

headers

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. Você pode especificar o cabeçalho Authorization usando o esquema de “Bearer” ou o esquema “BotConnector”.

Esquema Bearer:

Authorization: Bearer SECRET_OR_TOKEN

Esquema de BotConnector:

Authorization: BotConnector 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 HTTP	Significado
200	Solicitação com êxito.
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. Geralmente esse código de status ocorre porque o cabeçalho `Authorization` especifica um token inválido ou secreto.
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 interno de servidor no serviço Linha Direta
502	Ocorreu uma falha no bot; o bot está indisponível ou retornou um erro. Esse é um código de erro comum.

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 /api/tokens/conversation

Conteúdo	Descrição
Corpo da solicitação	n/d
Retorna	Uma cadeia de caracteres que representa o token

Atualizar Token

Atualiza o token.

GET /api/tokens/{conversationId}/renew

Conteúdo	Descrição
Corpo da solicitação	n/d
Retorna	Uma cadeia de caracteres que representa o novo token

Operações de conversa

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

Operação	Descrição
Iniciar Conversa	Abre uma nova conversa com o bot.
Receber mensagens	Recuperar mensagens do bot.
Enviar uma mensagem	Envia uma mensagem 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 /api/conversations

Conteúdo	Descrição
Corpo da solicitação	n/d
Retorna	Um objeto Conversation

Receber mensagens

Recupera mensagens do bot da conversa especificada. Defina o parâmetro watermark no URI da solicitação para indicar a mensagem mais recente vista pelo cliente.

GET /api/conversations/{conversationId}/messages?watermark={watermark_value}

Conteúdo	Descrição
Corpo da solicitação	n/d
Retorna	Um objeto MessageSet. A resposta contém `watermark` como uma propriedade do objeto `MessageSet`. Os clientes devem percorrer as mensagens disponíveis aprimorando o valor `watermark`, até que nenhuma mensagem retorne.

Enviar uma mensagem

Envia uma mensagem para o bot.

POST /api/conversations/{conversationId}/messages

Conteúdo	Descrição
Corpo da solicitação	Um objeto Message
Retorna	Nenhum dado é retornado no corpo da resposta. O serviço responde com um código de status HTTP 204, se a mensagem foi enviada com êxito. O cliente pode obter sua mensagem enviada (juntamente com quaisquer mensagens que o bot enviou ao cliente) usando a operação Obter mensagens.

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 /api/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 Message que deve servir como contêiner para os anexos especificados. Para saber mais, veja Enviar uma mensagem para o bot.
Retorna	Nenhum dado é retornado no corpo da resposta. O serviço responde com um código de status HTTP 204, se a mensagem foi enviada com êxito. O cliente pode obter sua mensagem enviada (juntamente com quaisquer mensagens que o bot enviou ao cliente) usando a operação Obter mensagens.

Observação

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

Esquema

O esquema de Linha Direta 1.1 é uma cópia simplificada do esquema do Bot Framework v1 que inclui os seguintes objetos.

Objeto Message

Define uma mensagem que um cliente envia para um bot ou recebe de um bot.

Propriedade	Type	Descrição
id	string	ID que identifica exclusivamente a mensagem (atribuída por Linha Direta).
conversationId	string	ID que identifica a conversa.
created	string	Data e hora em que a mensagem foi criada, expressa no formato ISO-8601).
from	string	ID que identifica o usuário que é o remetente da mensagem. Ao criar uma mensagem, os clientes devem definir essa propriedade como uma ID de usuário estável. Embora a Linha Direta atribua uma ID de usuário, se esta não for fornecida, isso normalmente resulta em um comportamento inesperado.
text	string	Texto da mensagem que é enviada do usuário para o bot ou do bot para o usuário.
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. Esses dados são enviados sem modificações entre o cliente e o bot. Esta propriedade deve ser definida como um objeto complexo ou deixada em branco. Não defina-a como uma cadeia de caracteres, número ou outro tipo simples.
images	string[]	Matriz de cadeias de caracteres que contém a(s) URL(s) da(s) imagen(s) contida(s) na mensagem. Em alguns casos, as cadeias de caracteres nesta matriz podem ser URLs relativas. Se qualquer cadeia de caracteres nessa matriz não começar com "http" ou "https", preencha `https://directline.botframework.com` a cadeia de caracteres para formar a URL completa.
attachments	Attachment[]	Matriz de objetos Attachment que representam os anexos sem imagem contidos na mensagem. Cada objeto na matriz contém uma propriedade `url` e uma propriedade `contentType`. Nas mensagens que um cliente recebe de um bot, a propriedade `url`, às vezes, pode especificar uma URL relativa. Para qualquer `url` valor de propriedade que não comece com "http" ou "https", preencha `https://directline.botframework.com` a cadeia de caracteres para formar a URL completa.

O exemplo a seguir mostra um objeto Message que contém todas as propriedades possíveis. Na maioria dos casos, ao criar uma mensagem, o cliente só precisa fornecer a from propriedade e pelo menos uma propriedade de conteúdo (como text, images, attachmentsou channelData).

{
    "id": "CuvLPID4kDb|000000000000000004",
    "conversationId": "CuvLPID4kDb",
    "created": "2016-10-28T21:19:51.0357965Z",
    "from": "examplebot",
    "text": "Hello!",
    "channelData": {
        "examplefield": "abc123"
    },
    "images": [
        "/attachments/CuvLPID4kDb/0.jpg?..."
    ],
    "attachments": [
        {
            "url": "https://example.com/example.docx",
            "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        }, 
        {
            "url": "https://example.com/example.doc",
            "contentType": "application/msword"
        }
    ]
}

Um objeto MessageSet

Define um conjunto de mensagens.

Propriedade	Type	Descrição
messages	Message[]	Matriz de objetos Message.
watermark	string	Marca d'água máxima das mensagens dentro do conjunto. Um cliente pode usar o valor `watermark` para indicar a mensagem mais recente visualizada ao recuperar mensagens do bot.

Objeto Anexo

Define um anexo sem imagem.

Propriedade	Type	Descrição
contentType	string	O tipo de mídia do conteúdo no anexo.
url	string	URL para o conteúdo do anexo.

Objeto Conversa

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.
token	string	Token válido para a conversa especificada.
expires_in	número	Número de segundos até a expiração do token.

Objeto de erro

Define um erro.

Propriedade	Type	Descrição
code	string	Código do erro. Um destes valores: MissingProperty, MalformedData, NotFound, ServiceError, Internal, InvalidRange, NotSupported, NotAllowed ou BadCertificate.
message	string	Uma descrição do erro.
statusCode	número	Código de status.

Objeto ErrorMessage

Um conteúdo de erro de mensagem padronizada.

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