Webhook de asignación de agente

¿Cómo funciona?

Cuando una conversación llega a un bloque de Métodos de transferencia configurado con el destino API, Treble envía una petición POST al endpoint que configuraste, con la información del contacto y de la conversación. Tu servicio decide qué agente debe atenderla y lo devuelve en la respuesta. Treble asigna la conversación a ese agente. Si tu servicio no responde a tiempo, o el agente que devuelves no puede recibir la conversación, Treble aplica el método de respaldo de tu empresa para que la conversación nunca quede sin asignar.

Este webhook no se configura en el centro de webhooks, sino dentro del propio bloque en el editor de conversaciones. Así, cada bloque puede llamar a un endpoint distinto.

Configurar el bloque

Aprende a configurar la URL y la autenticación desde el editor de conversaciones.

Autenticación

En el bloque puedes elegir entre dos opciones:

Sin autenticación — Treble llama a tu endpoint sin credenciales.
Token / API Key — Treble envía el token que configuraste en el header Authorization:

Authorization: Bearer TU_TOKEN

Usa siempre https:// y configura un token. Así tu endpoint puede verificar que la llamada viene efectivamente de Treble.

La petición que Treble envía

Treble hace un POST con un cuerpo JSON que contiene el contexto del contacto y de la conversación.

{
  "company_id": 1234,
  "survey_user_id": 567890,
  "contact": {
    "treble_id": "5215512345678",
    "name": "Andrea Soto",
    "country_code": "52",
    "cellphone": "5512345678",
    "business_scope_id": "1029384756",
    "username": null
  },
  "crm_type": "salesforce",
  "crm_objects": [
    { "entity": "Contact", "id": "0035f00000ABCDEqAO" },
    { "entity": "Account", "id": "0015f00000FGHIJqAO" }
  ],
  "channel": {
    "phone_number_id": "1234567890"
  },
  "metadata": {
    "poll_id": 4321,
    "node_id": "a1b2c3",
    "tag": "Comercial",
    "language": "es"
  }
}

Campo	Descripción
`company_id`	Identificador de tu empresa en Treble.
`survey_user_id`	Identificador de la sesión del contacto en la conversación.
`contact`	Información del contacto que está en la conversación.
`crm_type`	CRM con el que tu cuenta está integrada, por ejemplo `salesforce` o `hubspot`. Es `null` si no hay integración.
`crm_objects`	Registros del CRM asociados al contacto.
`channel.phone_number_id`	Identificador de la línea de WhatsApp que recibió la conversación.
`metadata`	Contexto del flujo y del bloque que originó la llamada: `poll_id`, `node_id`, `tag` e `language`.

cellphone y country_code pueden llegar en null para contactos que solo existen como usuario de Meta. En ese caso, usa business_scope_id o username para identificar al usuario.

Identificadores del CRM

Cuando tu cuenta tiene una integración de CRM, la petición incluye los identificadores del contacto en tu CRM para que puedas decidir con base en el registro; por ejemplo, consultar el propietario del registro y devolver a ese agente.

crm_type — el CRM con el que tu cuenta está integrada. Es null si la cuenta no tiene integración.
crm_objects — los registros del CRM asociados al contacto. Cada uno trae su entity (el tipo de objeto en el CRM, por ejemplo Contact, Account o Lead) y su id (el identificador del registro en tu CRM). Un contacto asociado a varios objetos de Salesforce trae una entrada por objeto; en otros CRMs hay una sola entrada. Un arreglo vacío significa que el contacto aún no está asociado a ningún registro.

La respuesta que debes devolver

Responde con 200 y un cuerpo JSON que identifique al agente. Puedes hacerlo por email (recomendado) o por id:

{
  "agent_email": "andrea.soto@tuempresa.com"
}

{
  "agent_id": 4567
}

agent_email — el email del agente tal como está registrado en Treble. Es la opción recomendada porque no depende de los identificadores internos de Treble.
agent_id — el identificador del agente en Treble.

El agente que devuelvas debe estar activo. Para conocer los agentes disponibles en tu cuenta —y los valores exactos de email e id que debes devolver— usa el endpoint de obtener los agentes de tu empresa.

Tu endpoint debe responder en menos de 10 segundos. Si se excede, devuelve un código distinto de 200, o devuelve un agente que no puede recibir la conversación, Treble aplica el método de respaldo configurado en la plataforma principal.

Ejemplo de implementación

Un endpoint mínimo en Node.js que devuelve un agente según el contacto:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/on-agent-assignation', (req, res) => {
  // Verifica que la llamada venga de Treble
  if (req.header('Authorization') !== `Bearer ${process.env.TREBLE_TOKEN}`) {
    return res.sendStatus(401);
  }

  const { contact, crm_type, crm_objects, metadata } = req.body;

  // Tu lógica para elegir el agente: round robin, idioma,
  // propietario en el CRM, segmento, etc.
  const agentEmail = elegirAgente(contact, crm_objects, metadata);

  // Devuelve el agente por email (recomendado) o por id
  res.json({ agent_email: agentEmail });
});

app.listen(3000, () => {
  console.log('Servidor escuchando en el puerto 3000');
});

Introducción a la API

API

Webhooks

Editor

Guías y Tutoriales

Webhook de asignación de agente

¿Cómo funciona?

Configurar el bloque

Autenticación

La petición que Treble envía

Identificadores del CRM

La respuesta que debes devolver

Ejemplo de implementación

Siguientes pasos

Referencia del endpoint

Obtener los agentes

​¿Cómo funciona?

Configurar el bloque

​Autenticación

​La petición que Treble envía

​Identificadores del CRM

​La respuesta que debes devolver

​Ejemplo de implementación

​Siguientes pasos

Referencia del endpoint

Obtener los agentes

¿Cómo funciona?

Autenticación

La petición que Treble envía

Identificadores del CRM

La respuesta que debes devolver

Ejemplo de implementación

Siguientes pasos