Een activiteit verzenden naar de bot in Direct Line API 3.0
Met behulp van het Direct Line 3.0-protocol kunnen clients en bots verschillende soorten activiteiten uitwisselen, waaronder berichtactiviteiten, typactiviteiten en aangepaste activiteiten die door de bot worden ondersteund. Een client kan één activiteit per aanvraag verzenden.
Een activiteit verzenden
Als u een activiteit naar de bot wilt verzenden, moet de client een activiteitsobject maken om de activiteit te definiëren en vervolgens een POST aanvraag indienen bij https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities, waarbij het object Activity in de hoofdtekst van de aanvraag wordt opgegeven.
De volgende codefragmenten bieden een voorbeeld van de aanvraag en het antwoord activiteit verzenden.
Aanvraag
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: application/json
[other headers]
{
"locale": "en-EN",
"type": "message",
"from": {
"id": "user1"
},
"text": "hello"
}
Antwoord
Wanneer de activiteit aan de bot wordt geleverd, reageert de service met een HTTP-statuscode die de statuscode van de bot weergeeft. Als de bot een fout genereert, wordt een HTTP 502-antwoord ('Ongeldige gateway') geretourneerd naar de client als reactie op de aanvraag voor activiteit verzenden.
Notitie
Dit kan worden veroorzaakt door het feit dat er geen correct token is gebruikt. Alleen het token dat is ontvangen tegen het starten van een gesprek kan worden gebruikt om een activiteit te verzenden.
Als de POST is geslaagd, bevat het antwoord een JSON-nettolading die de id aangeeft van de activiteit die naar de bot is verzonden.
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
Totale tijd voor de aanvraag/reactie voor de verzendactiviteit
De totale tijd die nodig is om een bericht te posten in een Direct Line gesprek is de som van het volgende:
- Transittijd voor de HTTP-aanvraag om van de client naar de Direct Line service te reizen
- Interne verwerkingstijd binnen Direct Line (meestal minder dan 120 ms)
- Transittijd van de Direct Line-service naar de bot
- Verwerkingstijd binnen de bot
- Transittijd voor het HTTP-antwoord om terug te gaan naar de client
Bijlage(s) naar de bot verzenden
In sommige situaties moet een client mogelijk bijlagen naar de bot verzenden, zoals afbeeldingen of documenten. Een client kan bijlagen naar de bot verzenden door de URL('s) op te geven van de bijlage('s) binnen het activiteitsobject dat wordt verzonden met behulp POST /v3/directline/conversations/{conversationId}/activities van of door bijlage(s) te uploaden met behulp van POST /v3/directline/conversations/{conversationId}/upload.
Bijlage(s) verzenden per URL
Als u een of meer bijlagen wilt verzenden als onderdeel van het activiteitsobject met behulp POST /v3/directline/conversations/{conversationId}/activitiesvan , neemt u een of meer bijlageobjecten op in het object Activiteit en stelt u de contentUrl eigenschap van elk bijlageobject in om de HTTP-, HTTPS- of data URI van de bijlage op te geven.
Bijlage(s) verzenden door te uploaden
Vaak heeft een client mogelijk installatiekopieën of documenten op een apparaat dat naar de bot wil verzenden, maar geen URL's die overeenkomen met die bestanden. In dit geval kan een client een POST /v3/directline/conversations/{conversationId}/upload aanvraag indienen om bijlagen naar de bot te verzenden door te uploaden. De indeling en inhoud van de aanvraag zijn afhankelijk van het feit of de client één bijlage of meerdere bijlagen verzendt.
Eén bijlage verzenden door te uploaden
Als u één bijlage wilt verzenden via uploaden, doet u deze aanvraag:
POST https://directline.botframework.com/v3/directline/conversations/{conversationId}/upload?userId={userId}
Authorization: Bearer SECRET_OR_TOKEN
Content-Type: TYPE_OF_ATTACHMENT
Content-Disposition: ATTACHMENT_INFO
[other headers]
[file content]
Vervang in deze aanvraag-URI {conversationId} door de id van het gesprek en {userId} door de id van de gebruiker die het bericht verzendt. De userId-parameter is vereist. Stel in de aanvraagheaders in Content-Type om het type bijlage op te geven en stel in Content-Disposition om de bestandsnaam van de bijlage op te geven.
De volgende codefragmenten bieden een voorbeeld van de aanvraag en het antwoord Voor het verzenden van (enkele) bijlage.
Aanvraag
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: image/jpeg
Content-Disposition: name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
Antwoord
Als de aanvraag is geslaagd, wordt er een bericht Activiteit naar de bot verzonden wanneer het uploaden is voltooid en bevat het antwoord dat de client ontvangt de id van de activiteit die is verzonden.
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
Meerdere bijlagen verzenden door te uploaden
Als u meerdere bijlagen wilt verzenden door te uploaden, POST moet u een aanvraag met meerdere delen naar het /v3/directline/conversations/{conversationId}/upload eindpunt verzenden. Stel de Content-Type header van de aanvraag in op multipart/form-data en neem de Content-Type header en Content-Disposition header voor elk onderdeel op om het type en de bestandsnaam van elke bijlage op te geven. Stel in de aanvraag-URI de userId parameter in op de id van de gebruiker die het bericht verzendt.
U kunt een Activity -object in de aanvraag opnemen door een onderdeel toe te voegen dat de Content-Type headerwaarde application/vnd.microsoft.activityopgeeft. Als de aanvraag een activiteit bevat, worden de bijlagen die zijn opgegeven door andere onderdelen van de nettolading toegevoegd als bijlagen bij die activiteit voordat deze wordt verzonden. Als de aanvraag geen activiteit bevat, wordt er een lege activiteit gemaakt om te fungeren als de container waarin de opgegeven bijlagen worden verzonden.
De volgende fragmenten bieden een voorbeeld van de aanvraag en het antwoord Voor het verzenden van (meerdere) bijlagen. In dit voorbeeld verzendt de aanvraag een bericht met tekst en één afbeeldingsbijlage. Er kunnen extra onderdelen worden toegevoegd aan de aanvraag om meerdere bijlagen in dit bericht op te nemen.
Aanvraag
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89
[other headers]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: image/jpeg
Content-Disposition: form-data; name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: application/vnd.microsoft.activity
[other headers]
{
"type": "message",
"from": {
"id": "user1"
},
"text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe"
}
----DD4E5147-E865-4652-B662-F223701A8A89
Antwoord
Als de aanvraag is geslaagd, wordt er een bericht Activiteit naar de bot verzonden wanneer het uploaden is voltooid en bevat het antwoord dat de client ontvangt de id van de activiteit die is verzonden.
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}