Inicie uma conversa em Direct Line API 3.0

Artigo
03/08/2023

Direct Line conversas são abertas explicitamente pelos clientes e podem decorrer enquanto o bot e o cliente participarem e tiverem credenciais válidas. Enquanto a conversa estiver aberta, tanto o bot como o cliente podem enviar mensagens. Mais de um cliente pode ligar-se a uma determinada conversa e cada cliente pode participar em nome de vários utilizadores.

Abrir uma nova conversa

Para abrir uma nova conversa do seu cliente, emita POST para o ponto final /v3/directline/conversas.

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

Os seguintes snippets fornecem um exemplo do pedido de conversação inicial e resposta.

Pedir

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

Resposta

Se o pedido for bem sucedido, a resposta conterá um ID para a conversação, um token, um valor que indica o número de segundos até que o token expire, e um URL de fluxo que o cliente pode usar para receber atividades através do stream 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, um pedido de conversação inicial é usado para abrir uma nova conversação e um código de estado HTTP 201 é devolvido se a nova conversa for iniciada com sucesso. No entanto, se um cliente apresentar um pedido de conversação inicial com um token Direct Line no Authorization cabeçalho que já foi usado para iniciar uma conversa ção utilizando a operação de conversação inicial, um código de estado HTTP 200 será devolvido para indicar que o pedido era aceitável, mas não foi criada nenhuma conversa (como já existia).

Dica

Tem 60 segundos para ligar ao URL de fluxo WebSocket. Se a ligação não puder ser estabelecida durante este tempo, pode voltar a ligar-se à conversação para gerar um novo URL de fluxo.

Iniciar conversa versus gerar token

A operação de conversação inicial (POST /v3/directline/conversations) é semelhante à operação de token gerar (POST /v3/directline/tokens/generate) na medida em que ambas as operações devolvem uma token que pode ser usada para aceder a uma única conversa. No entanto, a operação de conversação inicial também inicia a conversação, contacta o bot e cria um URL de stream WebSocket, enquanto a operação de token geração não faz nenhuma destas coisas.

Se pretender iniciar a conversa imediatamente com o seu cliente, utilize a operação de conversação inicial. Se planeia distribuir o token aos clientes e quer que inicie a conversação, utilize a operação de token de geração .

Partilhar via