Integración con sistemas externos

Documentación para integrar Optiwe con sistemas externos

Para las integraciones con sistemas externos, Optiwe utiliza un webhook. Un webhook es simplemente un end-point que el sistema externo disponibiliza en un servidor para que Optiwe pueda enviar los datos del cliente y la información de la conversación una vez finalizada.

El momento donde Optiwe ejecuta el webhook puede configurarse y las opciones aceptadas son:

  • Al iniciarse una conversación

  • Al finalizar una conversación

  • En cierto momento especificado en el flujo conversacional

Para realizar la integración, Optiwe simplemente necesita conocer la URL pública del end-point REST del sistema externo y el end-point necesita aceptar los parámetros json en el body de la request según la definición escrita en este documento.

Webhook del tipo API REST POST

El sistema externo debe disponibilizar una API en un servidor con el formato definido a continuación. La URL es solo a modo de ejemplo. Optiwe va a requerir la información de la URL final para configurarla en su sistema.

  • URL de ejemplo: https://sistema-externo.com/customer/

  • Verbo HTTP: POST

  • Encabezados de solicitud:

    • Content-Type: application/json

    • Accept: application/json

  • Encabezados de respuesta:

    • Content-Type: application/json

  • HTTP status esperado: 2xx

  • Cuerpo de solicitud

{
    "id": int,
    "customer": {
        "id": int,
        "fullName": str,
        "phone": str,
        "email": str,
        "extraData": object
    },
    "customerChannel": {
        "type": ChatChannel
    },
    "ownedByAgentType": Optional[AgentType],
    "ownedBy": Optional[User],   
    "agents": [
        {
            "type": AgentType,
            "assistantUser": Optional[User]       
        },
        {
            "type": AgentType   
        }  
    ],
    "createdOn": datetime("yyyy-mm-ddThh:mm:ss.ffffffZ"),
    "updatedOn": datetime("yyyy-mm-ddThh:mm:ss.ffffffZ"),
    "status": ConversationState,
    "messages": List[Message],
    "labelers": List[Labeler]
}

Detalle de campos:

  • customerChannel: Indica el canal en donde la conversación fue creada. El campo type es del tipo ChatChannel y los posibles valores son:

    • WHATSAPP

    • FACEBOOK

    • OPTIWE_CHAT

    • INSTAGRAM

    • FACEBOOK_COMMENT

    • INSTAGRAM_COMMENT.

  • ownedByAgentType : Campo del tipo Optional[AgentType]. Las conversaciones pueden tener un agente asignado, en dicho caso este campo esta presente. Los posibles valores que toma son:

    • ASSISTANT: Indica que un agente humano tiene asignada la conversación.

    • FACEBOOk_CHAT_BOT: Indica que un chatbot de Facebook tiene asignada la conversación.

    • INSTAGRAM_CHAT_BOT: Indica que un chatbot de Instagram tiene asignada la conversación.

    • OPTIWE_CHAT_BOT: Indica que un chatbot de Chat Web tiene asignada la conversación.

    • WHATSAPP_CHAT_BOT: Indica que un chatbot de Whatsapp tiene asignada la conversación.

  • ownedBy: Campo del tipo Optional[User]. Cuando la conversación está asignada a un agente humano, este campo esta presente y toma el siguiente valor.

{
       "firstName": str, 
       "lastName": str,
       "email": str
}

  • agents: Una lista con todos los agentes que participaron de la conversación. En el caso de que un agente humano haya participado de la conversación , se especifica el campo assistantUser cuyo tipo es Optional[User].

  • status: Campo del tipo ConversationState. Indica el estado de la conversación. Los posibles valores son ACTIVE, ENDED, INIT_BY_AGENT.

  • messages: Campo del tipo List[Message]. Especifica todos los mensajes ocurridos en la conversación. A continuación podemos ver un detalle de los valores que puede tomar.

Generacion deep link

En base al id de la conversación es posible generar un link para abrir la misma directamente en el agente. Este link tiene el formato:

https://agent.optiwe.com/chat/<chatId>/

Ejemplo: para la conversación con id=123 el link seria https://agent.optiwe.com/chat/123/

Para el caso donde no existe un chat con el id seleccionado, la interfaz mostrara un mensaje indicando que no existe la conversación.

Mensajes

A continuación podemos ver un detalles de los tipo de mensajes.

{
    "messageFrom": UserChatType,
    "messagePayload": object,     
    "createdOn": datetime("yyyy-mm-ddThh:mm:ss.ffffffZ"),
    "updatedOn": datetime("yyyy-mm-ddThh:mm:ss.ffffffZ"),
    "assistantUser": Optional[User]
}

  • messageFrom: Campo del tipo UserChatType. Los posibles valores que toma son:

    • END_USER: Especifica que el mensaje es del usuario en el canal OPTIWE_CHAT.

    • FACEBOOK_MESSENGER_END_USER: Especifica que el mensaje es del usuario en el canal FACEBOOK.

    • INSTAGRAM_END_USER: Especifica que el mensaje es del usuario en el canal INSTAGRAM.

    • WHATSAPP_END_USER: Especifica que el mensaje es del usuario en el canal WHATSAPP.

    • FACEBOOK_COMMENT_END_USER: Especifica que el mensaje es del usuario en el canal FACEBOOK_COMMENT.

    • INSTAGRAM_COMMENT_END_USER: Especifica que el mensaje es del usuario en el canal INSTAGRAM_COMMENT.

    • ASSISTANT: Especifica que el mensaje es de un agente humano.

    • DEFAULT_ASSISTANT: Especifica que el mensaje es del agente default. Por ejemplo cuando se envía una plantilla de Whatsapp, el owner del mensaje es el DEFAULT_ASSISTANT.

    • FACEBOOK_CHAT_BOT: Especifica que el mensaje es de un chatbot para el canal FACEBOOK.

    • INSTAGRAM_CHAT_BOT: Especifica que el mensaje es de un chatbot para el canal INSTAGRAM.

    • OPTIWE_CHAT_BOT: Especifica que el mensaje es de un chatbot para el canal OPTIWE_CHAT.

    • WHATSAPP_CHAT_BOT: Especifica que el mensaje es de un chatbot para el canal WHATSAPP.

  • messagePayload: Especifica el contenido del mensaje. Para mensajes del tipo texto el contenido es el siguiente:

{
    "text": str
}

  • assistantUser: Objeto del tipo Optional[User]. Cuando el mensaje es de un agente humano este campo especifica los datos del agente que envió el mensaje.

Etiquetas

Las conversaciones pueden ser etiquetadas ya sea automáticamente por un chatbot o manualmente por un agente. En este caso, la conversación tendrá la información de las etiquetas asignadas a la conversación en el campo `labelers`.

El campo `labelers` es una lista de objetos del tipo `Labeler` el cual se detalla a continuación:

{
    "conversationLabel": {
        "id": Int,
        "value": str,
    },
    "labeledBy": "ASSISTANT" | "*_CHAT_BOT"
}

Campos adicionales de clientes

El atributo extraData de customer contiene propiedades dinámicas. Estas propiedades se cargan dinámicamente a partir del diseño de conversación con el cual está configurado el chatbot.

Por ejemplo es posible configurar al chatbot para que pida una ubicación, en tal caso, los datos a recibir son:

{
   ...,
   "customer": {
       "fullName": "Nombre completo del cliente",
       "phone": "Numero de teléfono del cliente",
       "email": "Email del cliente",
       "extraData": {
           "location": {
               "lat": float,
               "lng": float,
               "city": str,
               "state": str,
               "country": str
           }
       }
   }
}

El chatbot puede estar configurado para solicitar multiple datos. Por ejemplo si además de la ubicación se solicita un producto de interés, los datos a recibir pueden ser:

{
   ...,
   "customer": {
       "fullName": "Nombre completo del cliente",
       "phone": "Numero de teléfono del cliente",
       "email": "Email del cliente",
       "extraData": {
           "location": {
               "lat": float,
               "lng": float,
               "city": str,
               "state": str,
               "country": str
           },
          "producto": str
       }
   }
}
AnteriorAutenticaciónSiguienteNotificaciones por webhook

Última actualización