Użyj webhooka do odbierania komunikatów i zdarzeń

Gdy konwersacja jest aktywna, komunikaty i zdarzenia od przedstawiciela działu obsługi klienta są wysyłane do skonfigurowanego punktu końcowego webhooka. Element webhook jest wymagany do odbierania aktualizacji w czasie rzeczywistym w niestandardowym kanale obsługi wiadomości.

Usługa jest ponawiana trzy razy z 10-sekundowym limitem czasu dla każdej próby.

Endpoint

{webhook_url}/v3/conversations/{conversationId}/activities

Where

  • {webhook_url} jest podstawowym adresem URL skonfigurowanym w kanale użytkownika.
  • {conversationId} z identyfikatorem GUID aktywnej konwersacji.

Metoda

POST

Nagłówki żądań

Nagłówka Description
Authorization Token elementu nośnego autoryzacji uzyskany z zarejestrowanej aplikacji Microsoft Entra.

Note

Upewnij się, że skonfigurowano poświadczenia tożsamości federacyjnej dla tego nagłówka, aby je włączyć.

Zasady ponawiania prób

  • Usługa elementu webhook ponawia próbę do trzech razy.
  • Każda ponowna próba umożliwia 10-sekundowy limit czasu.
  • Po trzech nieudanych próbach nie zostaną wykonane żadne kolejne próby.

Ładunek żądania

Ładunki są zgodne ze schematem działania platformy Bot Framework. Struktura zawiera zawartość wiadomości, typ działania, szczegóły nadawcy i opcjonalne załączniki.

Pola treści żądania

Klucz poziomu 1 Klucz warstwy 2 Klucz poziomu 3 Description Typ
typ Typ działania (komunikat, zdarzenie, wpisywanie) ciąg (maksymalnie 256)
Identyfikator kanału Identyfikator kanału (na przykład "MessagingApi") ciąg (maksymalnie 256)
od Obiekt nadawcy obiekt
identyfikator Identyfikator nadawcy ciąg (maksymalnie 256)
nazwa Wyświetlana nazwa nadawcy ciąg (maksymalnie 256)
konwersacja identyfikator Identyfikator konwersacji ciąg (maksymalnie 256)
textFormat Format tekstu wiadomości (markdown) ciąg (maksymalnie 256)
Załączniki [ ] Lista załączników (jeśli istnieje) macierz
typ treści Typ MIME załącznika ciąg (maksymalnie 256)
contentUrl Adres URL pliku ciąg
zawartość Zazwyczaj ma wartość null —
nazwa Nazwa pliku ciąg (maksymalnie 256)
thumbnailUrl Zazwyczaj ma wartość null —

Obsługiwane typy działań

Typ Description
komunikat Standardowy tekst lub wiadomość multimedialna
Pisanie Określa agenta lub przedstawiciela działu obsługi klienta (przedstawiciela działu obsługi lub przedstawiciela)
wydarzenie Zdarzenia na poziomie systemu, takie jak join/close

Nazwa działania zdarzenia

Następujące wartości są wysyłane do pola nazwy działań zdarzeń:

  • AgentZaakceptowany
  • AgentEndSession
  • ZakończRozmowęGłównegoAgenta
  • Agent rozłączony
  • AgentStartSecondaryChannel
  • AgentRaiseSecondaryChannel
  • AgentEndSecondaryChannel
  • Zamknij konwersację
  • SupervisorForceClosedConversation
  • Zainicjowane przez ConsultAgent
  • ConsultAgentFailed
  • ConsultAgentAcceptSession
  • ConsultAgentEndSession
  • ConsultAgentRejectSession
  • ConsultAgentSessionTimedOut
  • Usunięto Agenta Konsultacyjnego
  • TransferToAgentInitiated
  • TransferDoAgentaNieudany
  • TransferAgentAcceptSession
  • AgentTransferuOdrzućSesję
  • TransferAgentTimedOutSession
  • AgentEndedConsult
  • Agent dołączył do rozmowy z klientem
  • ConsultAgentLeftPublicConversation
  • TransferToQueueInitiated
  • PrzeniesienieDoKolejkiNiepowodzenie
  • CustomerDisconnected
  • CustomerDisconnectedAgentWaiting
  • AgentAssigned
  • PozaGodzinamiPracyZPowoduCzasuWolnegoOdPracy
  • OutOfOperatingHoursDueToHoliday

Przykładowe ładunki

Przykładowe ładunki reprezentują różne typy działań w czasie rzeczywistym, takie jak komunikaty, wskaźniki pisania, zdarzenia agenta i załączniki, które aplikacja wysyła do webhooka podczas aktywnej konwersacji.

Zaakceptowano agenta/przedstawiciela

{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "conversation": {
    "id": "{conversation_id}"
  },
  "text": "EventName: **_AgentAccepted_**",
  "name": "AgentAccepted"
}

Agent/przedstawiciel pisze


{
  "type": "typing",
  "channelId": "MessagingApi",
  "conversation": {
    "id": "{conversation_id}"
  },
  "recipient": {
    "id": "{recipient_id}"
  }
}

Komunikat agenta/przedstawiciela


{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "from": {
    "id": "{sender_id}",
    "name": "{sender_name}"
  },
  "conversation": {
    "id": "{conversation_id}"
  },
  "textFormat": "markdown",
  "text": "hello"
}

Agent/przedstawiciel wysyła załącznik


{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "from": {
    "id": "{sender_id}",
    "name": "{sender_name}"
  },
  "conversation": {
    "id": "{conversation_id}"
  },
  "textFormat": "markdown",
  "attachments": [
    {
      "contentType": "image/jpeg",
      "contentUrl": "{attachment_url}",
      "content": null,
      "name": "issue (1).jpg",
      "thumbnailUrl": null
    }
  ]
}

Agent/Przedstawiciel zakończył działanie


{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "from": {
    "id": "{sender_id}"
  },
  "conversation": {
    "id": "{conversation_id}"
  },
  "text": "EventName: **_AgentClosed_**",
  "name": "AgentClosed"
}

Konwersacja zamknięta


{
  "type": "message",
  "channelId": "<custom channel Id GUID>",
  "from": {
    "id": "{sender_id}"
  },
  "conversation": {
    "id": "{conversation_id}"
  },
  "text": "EventName: **_ConversationClosed_**",
  "name": "ConversationClosed"
}

Odpowiedź

200 kod HTTP. Wszystkie dane opublikowane w treści żądania są ignorowane.

Omówienie interfejsów API obsługi komunikatów

  • Ostatnia aktualizacja o