API-verwijzing - Direct Line API 3.0

U kunt uw clienttoepassing inschakelen om met uw bot te communiceren met behulp van Direct Line API 3.0. Direct Line API 3.0 maakt gebruik van industriestandaard REST en JSON via HTTPS.

Basis-URI

Voor toegang tot Direct Line API 3.0 gebruikt u een van deze basis-URI's voor alle API-aanvragen:

• Voor globale bots gebruikt u https://directline.botframework.com

• Voer voor een regionale bot de volgende URI in volgens de geselecteerde regio:

  Region	Basis-URI
  Europe	https://europe.directline.botframework.com
  India	https://india.directline.botframework.com

Headers

Naast de standaard HTTP-aanvraagheaders moet een Direct Line API-aanvraag een Authorization header bevatten waarmee een geheim of token wordt opgegeven om de client te verifiëren die de aanvraag uitgeeft. Geef de Authorization header op met behulp van deze indeling:

Authorization: Bearer SECRET_OR_TOKEN

Zie Verificatie voor meer informatie over het verkrijgen van een geheim of token dat uw client kan gebruiken om de Direct Line API-aanvragen te verifiëren.

HTTP-statuscodes

De HTTP-statuscode die met elk antwoord wordt geretourneerd, geeft het resultaat van de bijbehorende aanvraag aan.

Fouten

Elk antwoord dat een HTTP-statuscode in het bereik 4xx of 5xx opgeeft, bevat een ErrorResponse-object in de hoofdtekst van het antwoord dat informatie over de fout bevat. Als u een foutbericht ontvangt in het bereik 4xx, inspecteert u het object ErrorResponse om de oorzaak van de fout te identificeren en het probleem op te lossen voordat u de aanvraag opnieuw indient.

In de volgende codefragmenten ziet u een voorbeeldaanvraag en het resulterende foutbericht.

Verzoek

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

Antwoord

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

Tokenbewerkingen

Gebruik deze bewerkingen om een token te maken of te vernieuwen dat een client kan gebruiken voor toegang tot één gesprek.

Token genereren

Hiermee wordt een token gegenereerd dat geldig is voor één gesprek.

POST /v3/directline/tokens/generate

Token vernieuwen

Hiermee vernieuwt u het token.

POST /v3/directline/tokens/refresh

Gespreksbewerkingen

Gebruik deze bewerkingen om een gesprek met uw bot te openen en activiteiten uit te wisselen tussen client en bot.

Begin een gesprek

Hiermee opent u een nieuw gesprek met de bot.

POST /v3/directline/conversations

Gespreksgegevens ophalen

Haalt informatie op over een bestaand gesprek en genereert ook een nieuwe WebSocket-stream-URL die een client kan gebruiken om opnieuw verbinding te maken met een gesprek. U kunt eventueel de watermark parameter opgeven in de aanvraag-URI om het meest recente bericht aan te geven dat door de client wordt weergegeven.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}

Activiteiten ophalen

Hiermee worden activiteiten opgehaald uit de bot voor het opgegeven gesprek. U kunt eventueel de watermark parameter opgeven in de aanvraag-URI om het meest recente bericht aan te geven dat door de client wordt weergegeven.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

Een activiteit verzenden

Hiermee wordt een activiteit naar de bot verzonden.

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

Bestand(en) uploaden en verzenden

Uploadt en verzendt een of meer bestanden als bijlagen. Stel de userId parameter in de aanvraag-URI in om de id op te geven van de gebruiker die de bijlagen verzendt.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}

Schema

Het Direct Line 3.0-schema bevat alle objecten die zijn gedefinieerd door het Bot Framework-schema, evenals enkele objecten die specifiek zijn voor Direct Line.

ActivitySet-object

Hiermee definieert u een set activiteiten.

Gespreksobject

Hiermee definieert u een Direct Line gesprek.

TokenParameters-object

Parameters voor het maken van een token.

Activities

Voor elke activiteit die een client van een bot ontvangt via Direct Line:

• Bijlagekaarten blijven behouden.
• URL's voor geüploade bijlagen zijn verborgen met een privékoppeling.
• De channelData eigenschap blijft behouden zonder wijziging.

Clients kunnen meerdere activiteiten van de bot ontvangen als onderdeel van een ActivitySet.

Wanneer een client een Activity naar een bot verzendt via Direct Line:

• De type eigenschap geeft de typeactiviteit op die wordt verzonden (meestal bericht).
• De from eigenschap moet worden ingevuld met een gebruikers-id, gekozen door de client.
• Bijlagen kunnen URL's bevatten naar bestaande resources of URL's die zijn geüpload via het eindpunt van de Direct Line bijlage.
• De channelData eigenschap blijft behouden zonder wijziging.
• De totale grootte van de activiteit, wanneer deze wordt geserialiseerd naar JSON en versleuteld, mag niet langer zijn dan 256.000 tekens. We raden u aan activiteiten onder de 150.000 te houden. Als er meer gegevens nodig zijn, kunt u overwegen om de activiteit op te splitsen of bijlagen te gebruiken.

Clients kunnen één activiteit per aanvraag verzenden .

Aanvullende bronnen

• Specificatie van activiteitsprotocol