Iniciar uma conversa no Direct Line API 3.0

Artigo
03/08/2023

As conversas de linha diretas explicitamente são abertas pelos clientes e podem ser executadas desde que o cliente e o bot participarem e tem credenciais válidas. Enquanto a conversa está aberta, o bot e o cliente podem enviar mensagens. Mais de um cliente pode se conectar a uma determinada conversa e cada cliente pode participar em nome de vários usuários.

Abra uma nova conversa

Para abrir uma nova conversa do cliente, emita POST para o ponto de extremidade /v3/directline/conversations.

POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer SECRET_OR_TOKEN

Os snippets a seguir fornecem um exemplo da solicitação e da resposta da conversa inicial.

Solicitação

POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Resposta

Se a solicitação for bem-sucedida, a resposta conterá uma ID para a conversa, um token, um valor que indica o número de segundos até o token expirar e uma URL de fluxo que o cliente pode usar para receber atividades por meio do fluxo de WebSocket.

HTTP/1.1 201 Created
[other headers]

{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800,
  "streamUrl": "https://directline.botframework.com/v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA..."
}

Normalmente, uma solicitação de iniciar conversa é usada para abrir uma nova conversa e um código de status HTTP 201 é retornado se a nova conversa for iniciada com êxito. No entanto, se um cliente enviar uma solicitação de conversa inicial com um token Direct Line no Authorization cabeçalho que foi usado anteriormente para iniciar uma conversa usando a operação iniciar conversa, um código de status HTTP 200 será retornado para indicar que a solicitação foi aceitável, mas nenhuma conversa foi criada (como já existia).

Dica

Você tem 60 segundos para conectar-se à URL de fluxo do WebSocket. Se a conexão não puder ser estabelecida durante esse tempo, você poderá se reconectar à conversa para gerar uma nova URL de fluxo.

Iniciar conversa versus gerar token

A operação de iniciar conversa (POST /v3/directline/conversations) é semelhante à operação de geração de token (POST /v3/directline/tokens/generate) na medida em que ambas as operações retornam uma token que pode ser usada para acessar uma única conversa. No entanto, a operação iniciar conversa também inicia a conversa, entra em contato com o bot e cria uma URL de fluxo do WebSocket, enquanto a operação de geração de token não faz nada disso.

Se você pretende iniciar a conversa imediatamente com seu cliente, use a operação iniciar conversa. Se você planeja distribuir o token para os clientes e deseja que eles iniciem a conversa, use a operação de geração de token .

Compartilhar via