Odesílání a příjem zpráv pomocí rozhraní API konektoru robota
Služba Bot Connector umožňuje robotovi komunikovat napříč několika kanály, jako jsou Email, Slack a další. Usnadňuje komunikaci mezi robotem a uživatelem tím, že přenáší aktivity z robota do kanálu a z kanálu na robota. Každá aktivita obsahuje informace použité ke směrování zprávy do příslušného cíle spolu s informacemi o tom, kdo zprávu vytvořil, kontext zprávy a příjemce zprávy. Tento článek popisuje, jak používat službu Bot Connector k výměně aktivit zpráv mezi robotem a uživatelem v kanálu.
Odpověď na zprávu
Vytvoření odpovědi
Když uživatel odešle zprávu vašemu robotovi, robot tuto zprávu obdrží jako zprávu typuActivity. Pokud chcete vytvořit odpověď na zprávu uživatele, vytvořte nový Activity objekt a začněte nastavením těchto vlastností:
| Vlastnost | Hodnota |
|---|---|
| Konverzace | Nastavte tuto vlastnost na obsah conversation vlastnosti ve zprávě uživatele. |
| Z | Nastavte tuto vlastnost na obsah recipient vlastnosti ve zprávě uživatele. |
| locale | Tuto vlastnost nastavte na obsah locale vlastnosti ve zprávě uživatele, pokud je zadán. |
| Příjemce | Nastavte tuto vlastnost na obsah from vlastnosti ve zprávě uživatele. |
| replyToId | Nastavte tuto vlastnost na obsah id vlastnosti ve zprávě uživatele. |
| typ | Tuto vlastnost nastavte na message. |
Dále nastavte vlastnosti, které určují informace, které chcete uživateli sdělit. Můžete například nastavit text vlastnost tak, aby určila text, který se má zobrazit ve zprávě, nastavit speak vlastnost tak, aby určila text, který má robot vyslovovat, a nastavit attachments vlastnost tak, aby určila multimediální přílohy nebo bohaté karty, které se mají zahrnout do zprávy. Podrobné informace o běžně používaných vlastnostech zpráv najdete v tématu Vytváření zpráv.
Odeslání odpovědi
serviceUrl Pomocí vlastnosti v příchozí aktivitě identifikujte základní identifikátor URI, který by měl robot použít k vydání odpovědi.
Pokud chcete odpověď odeslat, odešlete tento požadavek:
POST /v3/conversations/{conversationId}/activities/{activityId}
V tomto identifikátoru URI požadavku nahraďte {conversationId} hodnotou vlastnosti objektu conversationid v rámci vaší aktivity (odpovědět) a {activityId} nahraďte hodnotou replyToId vlastnosti v rámci vaší aktivity (odpovědět). Nastavte text požadavku na objekt Aktivity , který jste vytvořili, aby představoval vaši odpověď.
Následující příklad ukazuje požadavek, který odešle jednoduchou textovou odpověď na zprávu uživatele. V tomto příkladu požadavku představuje základní identifikátor URI; https://smba.trafficmanager.net/teams základní identifikátor URI pro požadavky, které se můžou lišit problémy s robotem. Podrobnosti o nastavení základního identifikátoru URI najdete v referenčních informacích k rozhraní 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"
}
Odeslání zprávy (bez odpovědi)
Většina zpráv odesílaných robotem bude odpovídat na zprávy, které obdrží od uživatele. Může se ale stát, že robot potřebuje do konverzace poslat zprávu, která není přímou odpovědí na žádnou zprávu od uživatele. Robot může například potřebovat zahájit nové téma konverzace nebo odeslat zprávu na rozloučení na konci konverzace.
Pokud chcete do konverzace odeslat zprávu, která není přímou odpovědí na žádnou zprávu od uživatele, odešlete tento požadavek:
POST /v3/conversations/{conversationId}/activities
V tomto identifikátoru URI požadavku nahraďte {conversationId} ID konverzace.
Nastavte text požadavku na objekt Aktivity , který vytvoříte, aby reprezentoval vaši odpověď.
Poznámka
Bot Framework neukládá žádná omezení počtu zpráv, které může robot odesílat. Většina kanálů ale vynucuje omezení omezování, aby roboti za krátkou dobu odesílali velký počet zpráv. Navíc platí, že pokud robot odesílá několik zpráv v rychlém sledu, nemusí kanál vždy vykreslit zprávy ve správném pořadí.
Začněte konverzaci
Může se stát, že robot potřebuje zahájit konverzaci s jedním nebo více uživateli. Aby robot mohl zahájit konverzaci s uživatelem v kanálu, musí znát informace o svém účtu a informace o účtu uživatele v daném kanálu.
Tip
Pokud váš robot možná bude v budoucnu potřebovat zahájit konverzaci se svými uživateli, ukládat do mezipaměti informace o uživatelských účtech, další relevantní informace, jako jsou předvolby a národní prostředí uživatele, a adresu URL služby (která se použije jako základní identifikátor URI v žádosti Zahájit konverzaci).
Pokud chcete zahájit konverzaci, zadejte tento požadavek:
POST /v3/conversations
Nastavte text požadavku na objekt ConversationParameters , který určuje informace o účtu robota a informace o účtu uživatelů, které chcete zahrnout do konverzace.
Poznámka
Skupinové konverzace nepodporují všechny kanály. Projděte si dokumentaci ke kanálu, abyste zjistili, jestli kanál podporuje skupinové konverzace, a zjistěte maximální počet účastníků, který kanál umožňuje v konverzaci.
Následující příklad ukazuje požadavek, který zahájí konverzaci. V tomto příkladu požadavku představuje základní identifikátor URI; https://smba.trafficmanager.net/teams základní identifikátor URI pro požadavky, které se můžou lišit problémy s robotem. Podrobnosti o nastavení základního identifikátoru URI najdete v referenčních informacích k rozhraní 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"
}
Pokud je konverzace navázána s určenými uživateli, bude odpověď obsahovat ID, které identifikuje konverzaci.
{
"id": "abcd1234"
}
Robot pak může toto ID konverzace použít k odeslání zprávy uživatelům v rámci konverzace.