> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook de conversación finalizada

> Webhook enviado al finalizar una conversación de chat, con la transcripción, las variables extraídas y los datos del cliente

<Warning>
  **API de Famulor 1.0 (legado).** Esta página se aplica únicamente a Famulor 1.0 (`app.famulor.de`) y se conserva por compatibilidad. Para la plataforma actual, usa la [referencia de la API de Famulor 2.0](/es/api-reference/introduction).
</Warning>

> Webhook enviado al finalizar una conversación de chat, con la transcripción, las variables extraídas y los datos del cliente

El webhook de conversación finalizada se envía automáticamente a la URL de webhook que hayas especificado cuando finaliza una conversación de chat (WhatsApp o widget web). Este webhook contiene la transcripción completa, las variables extraídas, la información del cliente y los datos del remitente.

## Configuración del webhook

Para activar los webhooks de conversación finalizada:

1. Usa el endpoint de la API [Activar webhook de conversación finalizada](/es/api-v1/assistants/enable-conversation-ended-webhook)
2. Proporciona la URL de webhook a la que se enviarán las notificaciones
3. Opcionalmente, configura variables posteriores a la llamada en tu asistente para extraer datos estructurados de las conversaciones

## Formato de la solicitud

El webhook se envía como una solicitud POST a tu URL configurada con el siguiente payload JSON:

### Estructura del payload

<ResponseField name="id" type="integer">
  Identificador numérico de la conversación (el mismo `id` que se muestra en la URL de la conversación en el panel). Usa `conversation_id` (UUID) al llamar a la API.
</ResponseField>

<ResponseField name="conversation_id" type="string">
  Identificador único (UUID) de la conversación
</ResponseField>

<ResponseField name="assistant_id" type="string">
  Identificador único (UUID) del asistente que gestionó la conversación
</ResponseField>

<ResponseField name="type" type="string">
  El tipo de conversación. Valores posibles: `widget`, `whatsapp`
</ResponseField>

<ResponseField name="message_count" type="integer">
  Número total de mensajes intercambiados en la conversación
</ResponseField>

<ResponseField name="status" type="string">
  Estado de la conversación. Valor: `ended`
</ResponseField>

<ResponseField name="extracted_variables" type="object">
  Variables extraídas por la IA según la configuración del esquema posterior a la llamada de tu asistente

  <Expandable title="Ejemplo de variables extraídas">
    <ResponseField name="status" type="boolean">
      Si se alcanzó el objetivo de la conversación
    </ResponseField>

    <ResponseField name="summary" type="string">
      Resumen de la conversación
    </ResponseField>

    <ResponseField name="custom_variable" type="string|number|boolean">
      Cualquier variable personalizada que hayas definido en la configuración del asistente
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="input_variables" type="object">
  Variables que se pasaron al asistente al inicio de la conversación (por ejemplo, desde campos de formulario previo al chat o flujos de automatización)
</ResponseField>

<ResponseField name="transcript" type="array">
  Array de objetos de mensaje que representan la conversación completa, ordenados del más antiguo al más reciente

  <Expandable title="Propiedades del mensaje">
    <ResponseField name="role" type="string">
      El rol del remitente: `user`, `assistant` o `system` (los mensajes `system` marcan eventos como que un agente humano toma el control del chat)
    </ResponseField>

    <ResponseField name="content" type="string">
      El texto del mensaje. En los mensajes multimedia, es el pie de foto o un marcador de posición breve (p. ej., `[Image]`); las notas de audio contienen el texto transcrito
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      Marca de tiempo ISO 8601 del mensaje individual, en la zona horaria configurada del usuario. Permite ordenar los mensajes y ver cuánto duró la conversación (útil para chats que se extienden a lo largo de varios días)
    </ResponseField>

    <ResponseField name="timestamp_unix" type="integer">
      Marca de tiempo Unix (segundos desde epoch) del mensaje individual. Cómoda para operaciones aritméticas — p. ej. calcular el intervalo entre dos mensajes sin analizar la cadena ISO
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="formatted_transcript" type="string">
  Transcripción formateada y legible por humanos, con los prefijos `AI:` y `Customer:`
</ResponseField>

<ResponseField name="attachments" type="array">
  Archivos multimedia (imágenes, vídeos, documentos) compartidos durante la conversación. Cada entrada incluye una URL directa que puedes pasar a servicios externos (por ejemplo, análisis de imagen o vídeo). Es un array vacío cuando no se compartió ningún archivo multimedia — suele estar presente en las conversaciones de WhatsApp.

  <Expandable title="Propiedades del archivo adjunto">
    <ResponseField name="type" type="string">
      La categoría del archivo multimedia. Valores posibles: `image`, `video`, `audio`, `document`
    </ResponseField>

    <ResponseField name="url" type="string">
      URL directa para descargar el archivo multimedia
    </ResponseField>

    <ResponseField name="filename" type="string">
      Nombre de archivo original del contenido multimedia
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer_phone" type="string">
  Número de teléfono del cliente (disponible en las conversaciones de WhatsApp, `null` en las del widget)
</ResponseField>

<ResponseField name="customer_name" type="string">
  Nombre del cliente si se proporcionó (por ejemplo, desde el formulario previo al chat), o `null`
</ResponseField>

<ResponseField name="sender" type="object">
  Información del remitente de WhatsApp (solo presente en las conversaciones de WhatsApp, `null` en las del widget)

  <Expandable title="Propiedades del remitente">
    <ResponseField name="phone_number" type="string">
      El número de teléfono del remitente de WhatsApp
    </ResponseField>

    <ResponseField name="display_name" type="string">
      El nombre para mostrar del remitente de WhatsApp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  Marca de tiempo ISO 8601 de cuándo comenzó la conversación (en la zona horaria configurada del usuario)
</ResponseField>

<ResponseField name="ended_at" type="string">
  Marca de tiempo ISO 8601 de cuándo finalizó la conversación (en la zona horaria configurada del usuario)
</ResponseField>

<ResponseExample>
  ```json Conversation Ended Webhook Payload theme={null} theme={null}
  {
    "id": 1042,
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "type": "widget",
    "message_count": 8,
    "status": "ended",
    "extracted_variables": {
      "status": true,
      "summary": "Customer asked about pricing plans and was interested in the Pro plan"
    },
    "input_variables": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "transcript": [
      {
        "role": "assistant",
        "content": "Hi! How can I help you today?",
        "timestamp": "2026-02-23T09:30:00+01:00",
        "timestamp_unix": 1740299400
      },
      {
        "role": "user",
        "content": "I have a question about your service.",
        "timestamp": "2026-02-23T09:31:12+01:00",
        "timestamp_unix": 1740299472
      },
      {
        "role": "assistant",
        "content": "Of course! I'd be happy to help. What would you like to know?",
        "timestamp": "2026-02-23T09:31:18+01:00",
        "timestamp_unix": 1740299478
      },
      {
        "role": "user",
        "content": "What are your pricing plans?",
        "timestamp": "2026-02-23T09:32:05+01:00",
        "timestamp_unix": 1740299525
      }
    ],
    "formatted_transcript": "AI: Hi! How can I help you today?\nCustomer: I have a question about your service.\nAI: Of course! I'd be happy to help. What would you like to know?\nCustomer: What are your pricing plans?",
    "attachments": [],
    "customer_phone": null,
    "customer_name": "John Doe",
    "sender": null,
    "created_at": "2026-02-23T09:30:00+01:00",
    "ended_at": "2026-02-23T10:00:00+01:00"
  }
  ```

  ```json WhatsApp Conversation Ended Webhook theme={null} theme={null}
  {
    "id": 1043,
    "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "type": "whatsapp",
    "message_count": 12,
    "status": "ended",
    "extracted_variables": {
      "status": true,
      "summary": "Customer scheduled an appointment for next week"
    },
    "input_variables": {},
    "transcript": [
      {
        "role": "user",
        "content": "Hello, I'd like to book an appointment",
        "timestamp": "2026-02-23T14:00:00+01:00",
        "timestamp_unix": 1740315600
      },
      {
        "role": "assistant",
        "content": "Hi! I'd be happy to help you book an appointment. What date works best for you?",
        "timestamp": "2026-02-23T14:00:08+01:00",
        "timestamp_unix": 1740315608
      },
      {
        "role": "user",
        "content": "[Image]",
        "timestamp": "2026-02-23T14:05:30+01:00",
        "timestamp_unix": 1740315930
      }
    ],
    "formatted_transcript": "Customer: Hello, I'd like to book an appointment\nAI: Hi! I'd be happy to help you book an appointment. What date works best for you?\nCustomer: [Image]",
    "attachments": [
      {
        "type": "image",
        "url": "https://storage.famulor.de/conversations/attachments/abc123.jpg",
        "filename": "appointment-form.jpg"
      }
    ],
    "customer_phone": "+1234567890",
    "customer_name": null,
    "sender": {
      "phone_number": "+19876543210",
      "display_name": "My Business"
    },
    "created_at": "2026-02-23T14:00:00+01:00",
    "ended_at": "2026-02-23T14:25:00+01:00"
  }
  ```
</ResponseExample>

## Comportamiento de reintentos

Si tu endpoint de webhook devuelve un código de estado que no sea 2xx o la solicitud falla, el sistema reintentará el envío:

| Intento        | Retraso      |
| -------------- | ------------ |
| 1.er reintento | 30 segundos  |
| 2.º reintento  | 60 segundos  |
| 3.er reintento | 120 segundos |

Después de 3 intentos fallidos, la entrega del webhook se marca como fallida y no se realizan más reintentos.

## Notas importantes

* `conversation_id` y `assistant_id` son UUID, no ID enteros
* El campo `sender` solo se rellena en las conversaciones de WhatsApp; es `null` en las conversaciones del widget web
* `customer_phone` solo está disponible en las conversaciones de WhatsApp
* `customer_name` proviene de los datos del formulario previo al chat o del contexto de la conversación
* Las marcas de tiempo usan la zona horaria configurada del usuario (formato ISO 8601)
* `extracted_variables` se rellena a partir de la evaluación del esquema posterior a la llamada de tu asistente
* `input_variables` contiene datos de formularios previos al chat (widget web) o de flujos de automatización
* El array `attachments` enumera los archivos multimedia (imágenes, vídeos, documentos) compartidos durante la conversación, cada uno con una `url` descargable — útil para reenviarlos a herramientas externas de análisis. Es un array vacío cuando no se compartió ningún archivo multimedia (lo más habitual en las conversaciones del widget web)