Notificaciones por webhook

Documentación para recibir webhooks de Optiwe en sistemas externos, relacionados a notificaciones de conversaciones.

Introducción y configuración

Optiwe permite el envío webhooks a sistemas externos para notificaciones de:

Conversaciones nuevas
Conversaciones actualizadas
Mensajes salientes de WhatsApp fallidos

Estos webhooks se pueden configurar en la plataforma Dashboard (https://app.optiwe.com/dashboard/home) del espacio de trabajo, dentro de Configuración >> Webhooks. Allí, se debe especificar la URL a la cual enviarán los webhooks y cuales se desean recibir:

Nueva conversación

El evento NEW_CONVERSATION se dispara una única vez cuando una conversación esta pendiente de ser resuelta por un agente de atención.

Dependiendo la configuración de cada espacio de trabajo, una conversación al ser iniciado por el usuario puede ser manejada por el bot o quedar pendiente a ser resuelta los agentes de atención.

A su vez las conversaciones manejadas por el bot, pueden requerir la intervención de un agente humano, por lo tanto el evento NEW_CONVERSATION se dispara cuando:

Un espacio de trabajo no tiene un chatbot configurado y un usuario inicia una conversación
Un usuario le solicita al chatbot la intervención de un agente humano.

Payload

{
   "timestamp": int,
   "version": int,
   "type":"CONVERSATION_EVENT",
   "payload":{
      "type": "NEW_CONVERSATION"
      "payload": {
         "conversation": {
            "id": int,
            "customer": {
              "id": int,
              "fullName": Optional[str],
              "name": Optional[str],
              "email": Optional[str],
              "phone": Optional[str],
              "createdOn": datetime,
              "updatedOn": datetime,
              "lastActivity": datetime,
              "extraData": {},
              "hasWhatsappOptIn": bool
            },
            "customerChannel": {
              "type": "WHATSAPP|FACEBOOK|OPTIWE_CHAT|INSTAGRAM"
            },
            "createdOn": datetime,
            "updatedOn": datetime,
            "lastEndUserActivity": datetime,
            "status": "ACTIVE|ENDED",
            "amountNew": int,
            "startedWaitingOn": datetime
         },
         "workspace": {
            "id": int  
         }
      }
   }
}

Nuevo mensaje

Se ejecuta ante cada nuevo mensaje del usuario. A diferencia del evento de nueva conversación, en este caso se recibe la información del mensaje enviado por el usuario.

Payload

{
   "timestamp": int,
   "version": int,
   "type":"CONVERSATION_EVENT",
   "payload":{
      "type": "CONVERSATION_UPDATED"
      "payload": {
         "conversation": {
            "id": int,
            "customer": {
              "id": int,
              "fullName": Optional[str],
              "name": Optional[str],
              "email": Optional[str],
              "phone": Optional[str],
              "createdOn": datetime,
              "updatedOn": datetime,
              "lastActivity": datetime,
              "extraData": {},
              "hasWhatsappOptIn": bool
            },
            "customerChannel": {
              "type": "WHATSAPP|FACEBOOK|OPTIWE_CHAT|INSTAGRAM"
            },
            "createdOn": datetime,
            "updatedOn": datetime,
            "lastEndUserActivity": datetime,
            "status": "ACTIVE|ENDED",
            "amountNew": int,
            "startedWaitingOn": datetime
         },
         "workspace": {
            "id": int  
         },
         "message": {
            id: int
            messageFrom: "END_USER|FACEBOOK_MESSENGER_END_USER|
                          INSTAGRAM_END_USER|WHATSAPP_END_USER"
            createdOn: datetime
            updatedOn: datetime
            messagePayload: MessageObject
         }
      }
   }
}

Tipos de mensaje

El objeto MessageObject puede ser cualquiera de los siguientes tipos de mensaje:

Text message

Mensaje de texto plano

{
   "type": "TEXT",
   "text": str 
}

Image message

Mensaje del tipo imagen

{
   "type": "IMAGE",
   "text": Optional[str],
   "fileUrl": str
}

Ejemplo:

{
   "type": "IMAGE",
   "fileUrl": "https://route/to/file/my_image.png"
}

Video message

Mensaje del tipo video

{
   "type": "VIDEO",
   "text": Optional[str],
   "fileUrl": str
}

Ejemplo

{
   "type": "VIDEO",
   "fileUrl": "https://route/to/file/my_video.mp4"
}

Audio message

Mensaje del tipo audio

{
   "type": "AUDIO",
   "fileUrl": str
}

Ejemplo

{
   "type": "AUDIO",
   "fileUrl": "https://route/to/file/my_aduio.mp3"
}

Document message

Mensaje del tipo documento

{
   "type": "DOCUMENT",
   "text": Optional[str],
   "fileUrl": str
}

Ejemplo

{
   "type": "DOCUMENT",
   "fileUrl": "https://route/to/file/my_document.pdf"
}

Mensajes salientes de Whatsapp

Estos webhooks se enviarán a la URL configurada cuando se envíe un mensaje saliente (desde la plataforma Agent o la API de mensajes salientes de Optiwe) a un cliente con número de WhatsApp.

Payload

{
  "timestamp": int,
  "version": str,
  "type": str,
  "payload": {
    "type": str,
    "payload": {
      "statusCode": int, // Solo para eventos "failed"
      "metaErrorDescription": str, // Solo para eventos "failed"
      "conversationId": int,
      "messageId": int,
      "destination": str,
      "customerName": Optional[str]
    }
  }
}

timestamp: Marca de tiempo del evento
version: Version interna de la API de Optiwe
type: Tipo de evento del webhook. Para eventos de mensajes salientes por Whatsapp este evento es de tipo "MESSAGE_EVENT"
payload.type: tipo de evento de Whatsapp. En la versión actual de la API, puede ser "failed", "sent" o "read"
payload.payload.statusCode: Solo para eventos tipo "failed". Código de error de Meta. Para ver todos los códigos posibles de Meta dirigirse a https://developers.facebook.com/docs/whatsapp/on-premises/errors
payload.payload.metaErrorDescription: Solo para eventos tipo "failed". Descripción del error de Meta correspondiente al código "statusCode".
payload.payload.conversationId: Identificador de la conversación de Optiwe que contiene el mensaje correspondiente al webhook.
payload.payload.messageId: Identificador del mensaje de Optiwe.
payload.payload.destination: Número telefónico de destino al que se le envió el mensaje
payload.payload.customerName: Nombre del cliente asociado al número que figura en destination (en caso de que sea un cliente existente

1. Mensajes fallidos

Se enviará un evento de mensaje fallido en caso de que no se logre enviar el saliente. En el caso de que el saliente fallido sea de una campaña enviada a través de la plataforma Dashboard, éste quedará registrado en las estadísticas de la campaña pero no se enviará el webhook.

Ejemplo

{
  "timestamp": 1704219266303,
  "version": "1",
  "type": "MESSAGE_EVENT",
  "payload": {
    "type": "failed",
    "payload": {
      "statusCode": 1013,
      "metaErrorDescription": "User is not valid, Recipient is not a valid WhatsApp user",
      "conversationId": 30,
      "messageId": 170,
      "destination": "54911XX45XX89",
      "customerName": "John Doe"
    }
  }
}

2. Mensajes enviados

Se enviará un evento de mensaje enviado en caso de que se logre enviar el saliente correctamente.

Ejemplo

{
  "timestamp": 1704219769334,
  "version": "1",
  "type": "MESSAGE_EVENT",
  "payload": {
    "type": "sent",
    "payload": {
      "conversationId": 31,
      "messageId": 179,
      "destination": "54911XX45XX89",
      "customerName": "John Doe"
    }
  }
}

3. Mensajes leídos

Se enviará un evento de mensaje leído en caso de que el cliente lea el mensaje saliente. Para que esto suceda, el cliente debe tener habilitado la notificación de lectura de mensajes en Whatsapp, en caso contrario no se enviarán los webhooks de mensajes leídos.

Ejemplo

{
  "timestamp": 1704219289210,
  "version": "1",
  "type": "MESSAGE_EVENT",
  "payload": {
    "type": "read",
    "payload": {
      "conversationId": 29,
      "messageId": 171,
      "destination": "54911XX45XX89",
      "customerName": "John Doe"
    }
  }
}

AnteriorIntegración con sistemas externos SiguienteManejo y envío de plantillas de WhatsApp

Última actualización hace 2 meses