Referência de API – API de Linha Direta 1.1

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 seu aplicativo cliente e o bot, use a API de Linha Direta 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 tem autorização para 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 autorizaçã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 localizado. 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 Arquivo(s)

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 Tipo 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 nesta matriz não começar com “http” ou “https”, acrescente https://directline.botframework.com no início da 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 valor de propriedade https://directline.botframework.com que não comece com “http” ou “https”, acrescente url no início da 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 propriedade from e pelo menos uma propriedade de conteúdo (por exemplo, text, images, attachments ou 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 Tipo 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 Tipo 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 Tipo 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 Tipo 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 Tipo Descrição
error Erro Um objeto Erro que contém informações sobre o erro.