Berichten verzenden en ontvangen met de Bot Connector-API
Met de Bot Connector-service kan een bot communiceren via meerdere kanalen, zoals Email, Slack en meer. Het vergemakkelijkt de communicatie tussen bot en gebruiker, door activiteiten van bot naar kanaal en van kanaal naar bot door te geven. Elke activiteit bevat informatie die wordt gebruikt voor het routeren van het bericht naar de juiste bestemming, samen met informatie over wie het bericht heeft gemaakt, de context van het bericht en de ontvanger van het bericht. In dit artikel wordt beschreven hoe u de Bot Connector-service gebruikt om berichtactiviteiten uit te wisselen tussen bot en gebruiker op een kanaal.
Een bericht beantwoorden
Een antwoord maken
Wanneer de gebruiker een bericht naar uw bot verzendt, ontvangt uw bot het bericht als een activiteitsobject van het type bericht. Als u een antwoord op een bericht van een gebruiker wilt maken, maakt u een nieuw Activity object en stelt u eerst deze eigenschappen in:
| Eigenschap | Waarde |
|---|---|
| conversatie | Stel deze eigenschap in op de inhoud van de conversation eigenschap in het bericht van de gebruiker. |
| from | Stel deze eigenschap in op de inhoud van de recipient eigenschap in het bericht van de gebruiker. |
| landinstelling | Stel deze eigenschap in op de inhoud van de locale eigenschap in het bericht van de gebruiker, indien opgegeven. |
| geadresseerde | Stel deze eigenschap in op de inhoud van de from eigenschap in het bericht van de gebruiker. |
| replyToId | Stel deze eigenschap in op de inhoud van de id eigenschap in het bericht van de gebruiker. |
| type | Stel deze eigenschap in op bericht. |
Stel vervolgens de eigenschappen in waarmee de informatie wordt opgegeven die u aan de gebruiker wilt doorgeven. U kunt bijvoorbeeld de text eigenschap instellen om de tekst op te geven die in het bericht moet worden weergegeven, de speak eigenschap instellen om tekst op te geven die moet worden gesproken door uw bot en de attachments eigenschap instellen om mediabijlagen of rtf-kaarten op te nemen in het bericht. Zie Berichten maken voor gedetailleerde informatie over veelgebruikte berichteigenschappen.
Het antwoord verzenden
Gebruik de serviceUrl eigenschap in de binnenkomende activiteit om de basis-URI te identificeren die uw bot moet gebruiken om het antwoord te geven.
Als u het antwoord wilt verzenden, verzendt u deze aanvraag:
POST /v3/conversations/{conversationId}/activities/{activityId}
Vervang in deze aanvraag-URI {conversationId} door de waarde van de eigenschap van het conversation object id binnen uw (antwoord)activiteit en vervang {activityId} door de waarde van de replyToId eigenschap binnen uw (antwoord)activiteit. Stel de hoofdtekst van de aanvraag in op het activiteitsobject dat u hebt gemaakt om uw antwoord weer te geven.
In het volgende voorbeeld ziet u een aanvraag waarmee een eenvoudig antwoord met alleen tekst wordt verzonden naar een bericht van een gebruiker. In dit voorbeeld vertegenwoordigt de aanvraag https://smba.trafficmanager.net/teams de basis-URI; de basis-URI voor aanvragen die mogelijk verschillen van uw botproblemen. Zie API-verwijzing voor meer informatie over het instellen van de basis-URI.
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"
}
Een (niet-beantwoorden) bericht verzenden
Het merendeel van de berichten die uw bot verzendt, wordt beantwoord aan berichten die van de gebruiker worden ontvangen. Het kan echter voorkomen dat uw bot een bericht naar het gesprek moet verzenden dat geen direct antwoord is op een bericht van de gebruiker. Uw bot moet bijvoorbeeld aan het einde van het gesprek een nieuw gespreksonderwerp starten of een afscheidsbericht verzenden.
Als u een bericht wilt verzenden naar een gesprek dat geen direct antwoord is op een bericht van de gebruiker, doet u dit verzoek:
POST /v3/conversations/{conversationId}/activities
Vervang in deze aanvraag-URI {conversationId} door de id van het gesprek.
Stel de hoofdtekst van de aanvraag in op een activiteitsobject dat u maakt om uw antwoord weer te geven.
Notitie
Het Bot Framework legt geen beperkingen op voor het aantal berichten dat een bot kan verzenden. De meeste kanalen dwingen echter beperkingslimieten af om te voorkomen dat bots in korte tijd een groot aantal berichten verzenden. Bovendien, als de bot meerdere berichten snel achter elkaar verzendt, kan het kanaal de berichten niet altijd in de juiste volgorde weergeven.
Een gesprek starten
Het kan gebeuren dat uw bot een gesprek moet starten met een of meer gebruikers. Als u een gesprek wilt starten met een gebruiker op een kanaal, moet uw bot de accountgegevens en de accountgegevens van de gebruiker op dat kanaal kennen.
Tip
Als uw bot in de toekomst mogelijk gesprekken met de gebruikers moet starten, slaat u gebruikersaccountgegevens, andere relevante informatie, zoals gebruikersvoorkeuren en landinstelling, en de service-URL (te gebruiken als de basis-URI in de aanvraag Gesprek starten) in de cache.
Als u een gesprek wilt starten, doet u dit verzoek:
POST /v3/conversations
Stel de hoofdtekst van de aanvraag in op een ConversationParameters-object dat de accountgegevens van uw bot opgeeft en de accountgegevens van de gebruiker(s) die u in het gesprek wilt opnemen.
Notitie
Niet alle kanalen ondersteunen groepsgesprekken. Raadpleeg de documentatie van het kanaal om te bepalen of een kanaal groepsgesprekken ondersteunt en om het maximum aantal deelnemers te bepalen dat een kanaal toestaat in een gesprek.
In het volgende voorbeeld ziet u een aanvraag waarmee een gesprek wordt gestart. In dit voorbeeld vertegenwoordigt de aanvraag https://smba.trafficmanager.net/teams de basis-URI; de basis-URI voor aanvragen die mogelijk verschillen van uw botproblemen. Zie API-verwijzing voor meer informatie over het instellen van de basis-URI.
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"
}
Als het gesprek tot stand is gebracht met de opgegeven gebruikers, bevat het antwoord een id die het gesprek identificeert.
{
"id": "abcd1234"
}
Uw bot kan deze gespreks-id vervolgens gebruiken om een bericht te verzenden naar de gebruiker(s) in het gesprek.