Cómo utilizar webhooks en WhatChat

Los webhooks son callbacks HTTP que se configuran para cada cuenta. Estos se activan cuando ocurren ciertas acciones, como la creación de un mensaje en WhatChat. Se pueden crear múltiples webhooks para una sola cuenta.

¿Cómo añadir un webhook? #

Paso 1. Dirígete a Ajustes → Integraciones → Webhooks. Haz clic en el botón «Configurar».

Paso 2. Haz clic en el botón «Agregar nuevo webhook». Se abrirá un modal. Aquí, ingresa la URL a la que se debe enviar la solicitud POST. A continuación, selecciona los eventos a los que deseas suscribirte. Esta opción te permitirá escuchar solo los eventos relevantes en WhatChat.

WhatChat enviará una solicitud POST con el siguiente payload a las URLs configuradas para varias actualizaciones en tu cuenta.

Ejemplo de payload de webhook #

{
  "event": "message_created", // El nombre del evento
  "id": "1", // ID del mensaje
  "content": "Hola", // Contenido del mensaje
  "created_at": "2020-03-03 13:05:57 UTC", // Hora en que se envió el mensaje
  "message_type": "incoming", // Puede ser entrante, saliente o plantilla.
  "content_type": "enum", // Enum que puede ser input_select, cards, form o text.
  "content_attributes": {}, // Objeto con distintos valores definidos
  "source_id": "", // ID externo si la bandeja de entrada es una integración de Twitter o Facebook.
  "sender": { // Detalles del agente que envió el mensaje
    "id": "1",
    "name": "Agente",
    "email": "agente@ejemplo.com"
  },
  "contact": { // Detalles del usuario que envió el mensaje
    "id": "1",
    "name": "nombre-contacto"
  },
  "conversation": { // Detalles de la conversación
    "display_id": "1", // ID de la conversación visible en el dashboard.
    "additional_attributes": {
      "browser": {
        "device_name": "Macbook",
        "browser_name": "Chrome",
        "platform_name": "Macintosh",
        "browser_version": "80.0.3987.122",
        "platform_version": "10.15.2"
      },
      "referer": "",
      "initiated_at": "Tue Mar 03 2020 18:37:38 GMT-0700 (Mountain Standard Time)"
    }
  },
  "account": { // Detalles de la cuenta
    "id": "1",
    "name": "WhatChat"
  }
}

Eventos de webhook soportados en WhatChat #

WhatChat publica varios eventos a los endpoints de webhook configurados. Si deseas configurar un webhook, consulta la guía aquí.

Cada evento tiene una estructura de payload basada en el tipo de modelo sobre el que actúan. La siguiente sección describe los principales objetos que utilizamos en WhatChat y sus atributos.

Objetos #

Un payload de evento puede incluir cualquiera de los siguientes objetos. Los diversos tipos de objetos soportados por WhatChat se enumeran a continuación.

Cuenta

{
  "id": "entero",
  "name": "cadena"
}

Bandeja de entrada

{
  "id": "entero",
  "name": "cadena"
}

Contacto

{
  "id": "entero",
  "name": "cadena",
  "avatar": "cadena",
  "type": "contacto",
  "account": {
    // <...Objeto Cuenta>
  }
}

Usuario

{
  "id": "entero",
  "name": "cadena",
  "email": "cadena",
  "type": "usuario"
}

Conversación

{
  "additional_attributes": {
    "browser": {
      "device_name": "cadena",
      "browser_name": "cadena",
      "platform_name": "cadena",
      "browser_version": "cadena",
      "platform_version": "cadena"
    },
    "referer": "cadena",
    "initiated_at": {
      "timestamp": "fecha-hora-iso"
    }
  },
  "can_reply": "booleano",
  "channel": "cadena",
  "id": "entero",
  "inbox_id": "entero",
  "contact_inbox": {
    "id": "entero",
    "contact_id": "entero",
    "inbox_id": "entero",
    "source_id": "cadena",
    "created_at": "fecha-hora",
    "updated_at": "fecha-hora",
    "hmac_verified": "booleano"
  },
  "messages": ["Array de objetos de mensajes"],
  "meta": {
    "sender": {
      // Objeto Contacto
    },
    "assignee": {
      // Objeto Usuario
    }
  },
  "status": "cadena",
  "unread_count": "entero",
  "agent_last_seen_at": "timestamp-unix",
  "contact_last_seen_at": "timestamp-unix",
  "timestamp": "timestamp-unix",
  "account_id": "entero"
}

Mensaje

{
  "id": "entero",
  "content": "cadena",
  "message_type": "entero",
  "created_at": "timestamp-unix",
  "private": "booleano",
  "source_id": "cadena / nulo",
  "content_type": "cadena",
  "content_attributes": "objeto",
  "sender": {
    "type": "cadena - contacto/usuario"
    // Objeto Usuario o Contacto
  },
  "account": {
    // Objeto Cuenta
  },
  "conversation": {
    // Objeto Conversación
  },
  "inbox": {
    // Objeto Bandeja de entrada
  }
}

Eventos de Webhook #

WhatChat soporta los siguientes eventos de webhook. Puedes suscribirte a ellos al configurar un webhook en el panel de control o utilizando la API.

conversation_created #

Este evento se activará cuando se cree una nueva conversación en la cuenta. El payload para el evento es el siguiente.

{
  "event": "conversation_created"
  // <...Atributos de Conversación>
}

conversation_updated #

Este evento se activará cuando haya un cambio en cualquiera de los atributos de la conversación.

{
  "event": "conversation_updated",
  "changed_attributes": [
    {
      "<nombre_atributo>": {
        "current_value": "",
        "previous_value": ""
      }
    }
  ]
  // <...Atributos de Conversación>
}

conversation_status_changed #

Este evento se activará cuando se cambie el estado de la conversación.

Nota: Si utilizas las APIs de bot de agente en lugar de webhooks, este evento aún no está soportado.

{
  "event": "conversation_status_changed"
  // <...Atributos de Conversación>
}

message_created #

Este evento se activará cuando se cree un mensaje en una conversación. El payload para el evento es el siguiente.

{
  "event": "message_created"
  // <...Atributos de Mensaje>
}

message_updated #

Este evento se activará cuando se actualice un mensaje en una conversación. El payload para el evento es el siguiente.

{
  "event": "message_updated"
  // <...Atributos de Mensaje>
}

webwidget_triggered #

Este evento se activará cuando el usuario final abra el widget de chat en vivo.

{
  "id": , 
  "contact": {
    // <...Objeto Contacto>
  },
  "inbox": {
    // <...Objeto Bandeja de Entrada>
  },
  "account": {
    // <...Objeto Cuenta>
  },
  "current_conversation": {
    // <...Objeto Conversación>
  },
  "source_id": "cadena",
  "event": "webwidget_triggered",
  "event_info": {
    "initiated_at": {
      "timestamp": "cadena-fecha"
    },
    "referer": "cadena",
    "widget_language": "cadena",
    "browser_language": "cadena",
    "browser": {
      "browser_name": "cadena",
      "browser_version": "cadena",
      "device_name": "cadena",
      "platform_name": "cadena",
      "platform_version": "cadena"
    }
  }
}