Utiliser le webhook pour recevoir des messages et des événements

Lorsqu’une conversation est active, les événements et les messages du représentant du service client sont envoyés à votre point de terminaison webhook configuré. Le webhook est requis pour recevoir des mises à jour en temps réel dans votre canal de messagerie personnalisé.

Le service est retenté trois fois, avec un délai d’expiration de 10 secondes sur chaque tentative.

Endpoint

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

Where

  • {webhook_url} est l’URL de base que vous avez configurée dans votre canal personnalisé.
  • {conversationId} avec le GUID de la conversation active.

Méthode

POST

En-têtes de demande

En-tête de page Description
Autorisation Jeton d’autorisation du porteur obtenu auprès de l’application Microsoft Entra enregistrée.

Note

Veillez à configurer les informations d’identification d’identité fédérée pour que cet en-tête soit activé.

Stratégie de nouvelle tentative

  • Le service webhook retente jusqu’à trois fois.
  • Chaque nouvelle tentative autorise un délai d’expiration de 10 secondes.
  • Après trois tentatives ayant échoué, aucune nouvelle tentative n’est effectuée.

Charge utile de la demande

Les charges utiles suivent le schéma d’activité Bot Framework. La structure inclut le contenu du message, le type d’activité, les détails de l’expéditeur et les pièces jointes facultatives.

Champs du corps de la requête

Clé de niveau 1 Clé de niveau 2 Clé de niveau 3 Description Type
type Type d’activité (message, événement, saisie) string (max 256)
channelId Identificateur du canal (par exemple, « MessagingApi ») string (max 256)
de Objet Expéditeur Objet
ID ID de l’expéditeur string (max 256)
nom Nom d'affichage de l’expéditeur string (max 256)
conversation ID ID de conversation string (max 256)
textFormat Format du texte du message (markdown) string (max 256)
attachments [ ] Liste des pièces jointes (le cas échéant) tableau
type de contenu Type MIME de la pièce jointe string (max 256)
contentUrl URL du fichier ficelle
contenu Généralement null —
nom Nom du fichier string (max 256)
URL de la vignette Généralement null —

Types d’activités pris en charge

Type Description
message Texte standard ou message enrichi
saisie Indique que l’agent ou le représentant du service à la clientèle (représentant du service ou représentant) tape
événement Événements de niveau système tels que connexion/déconnexion

Noms des activités d’événement

Les valeurs suivantes sont envoyées dans le champ nom des activités d’événement :

  • AgentAccepté
  • AgentEndSession
  • PrimaryAgentEndConversation
  • AgentDéconnecté
  • AgentStartSecondaryChannel
  • AgentRaiseSecondaryChannel
  • AgentEndSecondaryChannel
  • Fin de Conversation
  • SupervisorForceClosedConversation
  • ConsultAgentInitiated
  • ConsultAgentFailed
  • ConsultAgentAcceptSession
  • ConsultAgentEndSession
  • ConsultAgentRejectSession
  • ConsultAgentSessionTimedOut
  • ConsultAgentRemoved
  • TransferToAgentInitiated
  • TransferToAgentFailed
  • TransferAgentAcceptSession
  • TransferAgentRejectSession
  • TransferAgentTimedOutSession
  • AgentEndedConsult
  • L'agent a rejoint la conversation avec le client
  • ConsultAgentLeftPublicConversation
  • TransferToQueueInitiated
  • TransferToQueueFailed
  • ClientDéconnecté
  • CustomerDisconnectedAgentWaiting
  • AgentAffecté
  • Hors des heures de fonctionnement en raison des heures non travaillées
  • En dehors des heures de service à cause d'un jour férié

Exemples de charges utiles

Les exemples de charges utiles représentent différents types d’activités en temps réel, tels que les messages, les indicateurs de saisie, les événements d’agent et les pièces jointes que l’application envoie à votre webhook pendant une conversation active.

Agent/représentant accepté

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

L’assistant/le représentant est en train d’écrire


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

Message agent/représentant


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

Agent/Représentant envoyer une pièce jointe


{
  "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/Représentant fermé


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

Conversation fermée


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

Réponse

Code HTTP 200. Toutes les données publiées dans le corps de la requête sont ignorées.

Vue d’ensemble des API de messagerie

  • Last updated on