Integraciones

#Configuración

Cada chatbot puede tener un Endpoint de Datos de Clientes. Configúralo desde Configuración del chatbot → Integraciones:

• Método HTTP — GET o POST
• URL del endpoint — La URL que llamará CustomerHero
• Cabeceras personalizadas — Añade tokens de autorización u otras cabeceras
• Activar/Desactivar — Activa o desactiva el endpoint sin eliminar la configuración

#Formato de la solicitud

Cuando un agente abre una conversación, CustomerHero envía los identificadores conocidos del cliente a tu endpoint. El formato depende del método HTTP.

Solicitudes POST

Los datos del cliente se envían como cuerpo JSON:

1
2
3
4
5
6
7
8
9
10
{
  "customer": {
    "externalId": "user_12345",
    "email": "jane@acme.com",
    "name": "Jane Smith",
    "phone": "+1234567890"
  },
  "chatbotId": "bot_xxx",
  "conversationId": "conv_xxx"
}

Solicitudes GET

Los datos del cliente se añaden como parámetros de consulta:

1
2
3
4
5
6
7
GET https://api.acme.com/customer-data
  ?externalId=user_12345
  &email=jane%40acme.com
  &name=Jane+Smith
  &phone=%2B1234567890
  &chatbotId=bot_xxx
  &conversationId=conv_xxx

#Formato de la respuesta

Tu endpoint debe devolver un objeto JSON con un array sections. Cada sección tiene un título y una lista de propiedades:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "sections": [
    {
      "title": "Cuenta",
      "properties": [
        { "label": "Plan", "value": "Pro ($99/mes)" },
        { "label": "Estado", "value": "Activa", "color": "green" },
        { "label": "MRR", "value": "$99.00" },
        { "label": "Miembro desde", "value": "2024-01-15" }
      ]
    },
    {
      "title": "Pedidos recientes",
      "properties": [
        {
          "label": "Último pedido",
          "value": "#4521 - $149.99",
          "url": "https://admin.acme.com/orders/4521"
        },
        { "label": "Estado del pedido", "value": "Entregado" },
        { "label": "Total de pedidos", "value": "12" }
      ]
    }
  ]
}

Campos de las propiedades

• label (string, obligatorio) — Nombre de la propiedad
• value (string, obligatorio) — Valor a mostrar
• url (string, opcional) — Convierte el valor en un enlace clicable
• color (string, opcional) — green, red, yellow, o blue — se muestra como una insignia de color

Los títulos se truncan a 200 caracteres, las etiquetas a 200 y los valores a 1.000. Los campos adicionales se eliminan por seguridad.

#Firma de solicitudes

Si tu chatbot tiene configurado un Secreto de identidad, cada solicitud incluye una cabecera X-CustomerHero-Signature con un resumen hexadecimal HMAC-SHA256. Esto te permite verificar que la solicitud proviene de CustomerHero.

• Solicitudes POST — La firma se calcula sobre el cuerpo JSON
• Solicitudes GET — La firma se calcula sobre la cadena de consulta (la parte ?clave=valor&... de la URL)

Para verificar, calcula HMAC-SHA256(secreto, payload) y compara el resumen hexadecimal con el valor de la cabecera.

#Pruebas

La página de integraciones incluye un botón de Probar endpoint que llama a tu endpoint con datos de cliente simulados. Puedes personalizar los valores de prueba (ID externo, correo electrónico, nombre, teléfono) antes de enviar.

Tras la prueba, CustomerHero valida la respuesta con el formato esperado y muestra:

• Código de estado HTTP y tiempo de respuesta
• La respuesta JSON sin procesar
• Validación de formato: si la respuesta tiene la estructura correcta de sections, con mensajes de error específicos para cualquier problema

Puedes probar antes de guardar: la prueba usa los valores del formulario actual, no la configuración guardada.

#Caché

Las respuestas se almacenan en caché en el servidor durante 5 minutos por cliente para evitar llamadas excesivas a tu endpoint. Los agentes pueden hacer clic en el botón Actualizar en la barra lateral de la bandeja de entrada para omitir la caché y obtener datos actualizados.