Compartir a través de

Uso de webhook para recibir mensajes y eventos

Cuando una conversación está activa, los eventos y los mensajes del representante del servicio de atención al cliente se envían al punto de conexión de webhook configurado. El webhook es necesario para recibir actualizaciones en tiempo real en el canal de mensajería personalizado.

El servicio se reintenta tres veces, con un tiempo de espera de 10 segundos en cada intento.

Punto final

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

Where

  • es la dirección URL base que configuró en el canal personalizado.
  • con el GUID de la conversación activa.

Método

POST

Encabezados de solicitud

Header Description
Authorization Token de portador de autorización obtenido de la aplicación Microsoft Entra registrada.

Nota:

Asegúrese de configurar las credenciales de identidad federada para que este encabezado esté habilitado.

Directiva de reintentos

  • El servicio de webhook reintenta hasta tres veces.
  • Cada reintento permite un tiempo de espera de 10 segundos.
  • Después de tres intentos fallidos, no se realizan más reintentos.

Solicitar carga útil

Las cargas siguen el esquema de actividad de Bot Framework. La estructura incluye contenido del mensaje, tipo de actividad, detalles del remitente y datos adjuntos opcionales.

Campos del cuerpo de la solicitud

Clave de nivel 1 Clave de nivel 2 Clave de nivel 3 Description Tipo
type Tipo de actividad (mensaje, evento, escritura) string (máximo 256)
channelId Identificador del canal (por ejemplo, "MessagingApi") string (máximo 256)
desde Objeto emisor objeto
id Id. de remitente string (máximo 256)
nombre Nombre para mostrar de emisor string (máximo 256)
conversación id Id. de la conversación string (máximo 256)
textFormat Formato del texto del mensaje (Markdown) string (máximo 256)
datos adjuntos [ ] Lista de datos adjuntos (si los hay) array
tipo de contenido Tipo MIME de los datos adjuntos string (máximo 256)
URL de contenido Dirección URL del archivo cuerda / cadena
contenido Normalmente null —
nombre Nombre del archivo string (máximo 256)
URL de miniatura Normalmente null —

Tipos de actividad admitidos

Tipo Description
Mensaje Texto estándar o mensaje enriquecido
escritura Indica que el agente o representante del servicio al cliente (representante de servicio o representante) está escribiendo
evento Eventos de nivel de sistema como join/close

Nombres de actividad de eventos

Los siguientes valores se envían en el campo nombre de las actividades de eventos:

  • AgentAccepted
  • AgenteFinalizarSesión
  • PrimaryAgentEndConversation
  • AgenteDesconectado
  • AgentStartSecondaryChannel
  • AgentRaiseSecondaryChannel
  • AgentEndSecondaryChannel
  • Cerrar conversación
  • SupervisorForceClosedConversation
  • ConsultAgentInitiated
  • ConsultAgentFailed
  • ConsultAgentAcceptSession
  • ConsultAgentEndSession
  • ConsultAgentRejectSession
  • ConsultAgentSessionTimedOut
  • AgenteDeConsultaEliminado
  • TransferToAgentInitiated
  • TransferToAgentFailed
  • TransferAgentAcceptSession
  • TransferAgentRejectSession
  • TransferAgentTimedOutSession
  • AgentEndedConsult
  • ElAgenteSeUnióALaConversaciónConElCliente
  • ConsultAgentLeftPublicConversation
  • TransferToQueueInitiated
  • TransferToQueueFailed
  • CustomerDisconnected
  • CustomerDisconnectedAgentWaiting
  • AgenteAsignado
  • OutOfOperatingHoursDueToNonWorkingHours
  • FueraDeHorarioDeOperaciónPorVacaciones

Cargas de ejemplo

Las cargas de ejemplo representan diferentes tipos de actividades en tiempo real, como mensajes, indicadores de escritura, eventos del agente y datos adjuntos que la aplicación envía al webhook durante una conversación activa.

Agente/Representante aceptado

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

Escritura de agente o representante


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

Mensaje de agente o representante


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

Agente/Representante envía adjunto


{
  "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
    }
  ]
}

Agente o representante cerrado


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

Conversación cerrada


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

Respuesta

Código HTTP 200. Se omiten los datos publicados en el cuerpo de la solicitud.

Introducción a las API de mensajería

  • Last updated on