Enviar e receber mensagens com a API do Conector do Bot

Artigo
10/07/2023

O serviço Bot Connector permite que um bot comunique em vários canais, como Email, Slack e muito mais. Facilita a comunicação entre o bot e o utilizador, ao reencaminhar atividades do bot para o canal e do canal para o bot. Cada atividade contém informações utilizadas para encaminhar a mensagem para o destino adequado, juntamente com informações sobre quem criou a mensagem, o contexto da mensagem e o destinatário da mensagem. Este artigo descreve como utilizar o serviço Bot Connector para trocar atividades de mensagens entre o bot e o utilizador num canal.

Responder a uma mensagem

Criar uma resposta

Quando o utilizador envia uma mensagem para o bot, o bot receberá a mensagem como um objeto Atividade do tipo mensagem. Para criar uma resposta à mensagem de um utilizador, crie um novo Activity objeto e comece por definir estas propriedades:

Propriedade	Valor
conversação	Defina esta propriedade para o conteúdo da `conversation` propriedade na mensagem do utilizador.
de	Defina esta propriedade para o conteúdo da `recipient` propriedade na mensagem do utilizador.
região	Defina esta propriedade como o conteúdo da `locale` propriedade na mensagem do utilizador, se especificado.
destinatário	Defina esta propriedade para o conteúdo da `from` propriedade na mensagem do utilizador.
replyToId	Defina esta propriedade para o conteúdo da `id` propriedade na mensagem do utilizador.
tipo	Defina esta propriedade como mensagem.

Em seguida, defina as propriedades que especificam as informações que pretende comunicar ao utilizador. Por exemplo, pode definir a text propriedade para especificar o texto a apresentar na mensagem, definir a propriedade para especificar texto speak a ser falado pelo bot e definir a attachments propriedade para especificar anexos multimédia ou cartões avançados a incluir na mensagem. Para obter informações detalhadas sobre as propriedades de mensagens utilizadas frequentemente, consulte Criar mensagens.

Enviar a resposta

Utilize a serviceUrl propriedade na atividade de entrada para identificar o URI base que o bot deve utilizar para emitir a resposta.

Para enviar a resposta, emita este pedido:

POST /v3/conversations/{conversationId}/activities/{activityId}

Neste URI do pedido, substitua {conversationId} pelo valor da conversation propriedade do id objeto na sua Atividade (responder) e substitua {activityId} pelo valor da replyToId propriedade na sua Atividade (responder). Defina o corpo do pedido para o objeto Atividade que criou para representar a sua resposta.

O exemplo seguinte mostra um pedido que envia uma resposta só de texto simples à mensagem de um utilizador. Neste pedido de exemplo, https://smba.trafficmanager.net/teams representa o URI base; o URI base para pedidos de que os problemas do bot podem ser diferentes. Para obter detalhes sobre como definir o URI base, veja Referência da API.

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723 
Authorization: Bearer ACCESS_TOKEN 
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "Pepper's News Feed"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "Convo1"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "SteveW"
    },
    "text": "My bot's reply",
    "replyToId": "5d5cdc723"
}

Enviar uma mensagem (sem resposta)

A maioria das mensagens que o bot envia responderá às mensagens que recebe do utilizador. No entanto, pode haver alturas em que o bot precisa de enviar uma mensagem para a conversação que não seja uma resposta direta a qualquer mensagem do utilizador. Por exemplo, o bot poderá ter de iniciar um novo tópico de conversação ou enviar uma mensagem de despedida no final da conversação.

Para enviar uma mensagem para uma conversação que não seja uma resposta direta a qualquer mensagem do utilizador, emita este pedido:

POST /v3/conversations/{conversationId}/activities

Neste URI do pedido, substitua {conversationId} pelo ID da conversação.

Defina o corpo do pedido para um objeto Atividade que criar para representar a sua resposta.

Nota

O Bot Framework não impõe restrições ao número de mensagens que um bot pode enviar. No entanto, a maioria dos canais impõe limites de limitação para impedir que os bots enviem um grande número de mensagens num curto espaço de tempo. Além disso, se o bot enviar várias mensagens numa sucessão rápida, o canal poderá nem sempre compor as mensagens na sequência adequada.

Iniciar uma conversa

Pode haver alturas em que o bot precisa de iniciar uma conversação com um ou mais utilizadores. Para iniciar uma conversação com um utilizador num canal, o bot tem de saber as respetivas informações de conta e as informações da conta do utilizador nesse canal.

Dica

Se o bot precisar de iniciar conversações com os respetivos utilizadores no futuro, coloque em cache as informações da conta de utilizador, outras informações relevantes, como as preferências do utilizador e a região, e o URL do serviço (para utilizar como URI base no pedido Iniciar Conversação).

Para iniciar uma conversação, emita este pedido:

POST /v3/conversations

Defina o corpo do pedido para um objeto ConversationParameters que especifica as informações da conta do bot e as informações da conta dos utilizadores que pretende incluir na conversação.

Nota

Nem todos os canais suportam conversações de grupo. Consulte a documentação do canal para determinar se um canal suporta conversações de grupo e para identificar o número máximo de participantes que um canal permite numa conversação.

O exemplo seguinte mostra um pedido que inicia uma conversação. Neste pedido de exemplo, https://smba.trafficmanager.net/teams representa o URI base; o URI base para pedidos de que os problemas do bot podem ser diferentes. Para obter detalhes sobre como definir o URI base, veja Referência da API.

POST https://smba.trafficmanager.net/teams/v3/conversations 
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "bot": {
        "id": "12345678",
        "name": "bot's name"
    },
    "isGroup": false,
    "members": [
        {
            "id": "1234abcd",
            "name": "recipient's name"
        }
    ],
    "topicName": "News Alert"
}

Se a conversação for estabelecida com os utilizadores especificados, a resposta conterá um ID que identifica a conversação.

{
    "id": "abcd1234"
}

Em seguida, o bot pode utilizar este ID de conversação para enviar uma mensagem aos utilizadores na conversação.

Partilhar via