Campos personalizados: sincronizar la ficha del cliente

Los campos personalizados son la ficha CRM de cada cliente: DNI, RUC, dirección, número de pedido, el segmento… lo que tu empresa haya definido. Se definen una vez en el panel y después se llenan por cliente.

Definir vs. rellenar

Crear o borrar un campo cambia el modelo de datos de toda la empresa, así que eso se hace en el panel. La API rellena y lee valores, que es la operación diaria.

Catálogo de campos

GET/custom-fieldsscope: custom_fields:read

Las definiciones de tu empresa. De acá salen los fieldId que necesitás para escribir.

Parámetros de consulta

Campo	Tipo	Descripción
`fieldCategory`	string	`USER` (datos del cliente) o `BOT` (los que deja la automatización).

curl https://www.flujoschat.foo/api/public/v1/custom-fields \
  -H "Authorization: Bearer fjc_live_..."

Leer la ficha

GET/conversations/{id}/custom-fieldsscope: custom_fields:read

Los valores cargados de ese cliente.

Respuesta · 200

{
  "success": true,
  "data": {
    "customFields": [
      {
        "fieldId": "e335bba2-…",
        "name": "DNI",
        "fieldType": "TEXT",
        "fieldCategory": "USER",
        "value": "45678912",
        "updatedAt": "2026-07-26T14:40:00.000Z"
      }
    ]
  }
}

Si estás recorriendo muchas conversaciones, no pidas la ficha una por una: usá GET /conversations?include=customFields, que las trae todas en la misma página.

Escribir un valor

PUT/conversations/{id}/custom-fields/{fieldId}scope: custom_fields:write

Upsert: si el campo ya tenía valor, lo reemplaza. Repetir el mismo PUT no cambia nada, así que es seguro reintentarlo.

Cuerpo

Campo	Tipo	Descripción
`value`req.	string \| number	El valor a guardar. Se almacena como texto.

curl -X PUT \
  "https://www.flujoschat.foo/api/public/v1/conversations/$CONVERSATION_ID/custom-fields/$FIELD_ID" \
  -H "Authorization: Bearer fjc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"value": "45678912"}'

Un fieldId de otra empresa no funciona

Si el campo no pertenece a la empresa de tu key: 404 CUSTOM_FIELD_NOT_FOUND. Es a propósito, para que un id ajeno no pueda escribir en el modelo de otro cliente.

Sincronización en dos vías

Tu sistema → FlujosChat: escribís con PUT. Eso actualiza el updatedAt de la conversación, así que tu propia sincronización incremental lo ve.
FlujosChat → tu sistema: suscribite al evento conversation.custom_field_updated y te enterás cuando lo llena un agente o un flujo.

Preguntas frecuentes

¿Puedo crear campos personalizados desde la API?

No. Los campos se definen en el panel (Configuración → Automatización → Campos) porque cambian el modelo de datos de toda la empresa. La API lee el catálogo y escribe valores por cliente.

¿Escribir un campo personalizado se nota en la sincronización incremental?

Sí. Escribir un valor actualiza el updatedAt de la conversación, así que aparece en GET /conversations?updatedAfter=… Sin eso, un ERP que acaba de escribir el DNI no vería su propio cambio al reconciliar.

¿Qué diferencia hay entre un campo USER y uno BOT?

Es solo la categoría con la que se organizan: USER para datos del cliente que capturás o cargás, BOT para valores que deja la automatización. La API los trata igual y podés filtrar por fieldCategory.