Webhooks

Socialdesk utiliza webhooks para notificar a tu aplicación cuando ocurren eventos relevantes en las conversaciones.

Configuración

Los webhooks se configuran directamente desde la plataforma de Socialdesk al registrar tu aplicación o bot.

Estructura del evento

Todos los eventos webhook siguen esta estructura:

{
  "type": "DIRECT_MESSAGE",
  "payload": { ... },
  "channel_instance": "channel_123",
  "instance": {
    "type": "APP",
    "id": "app_456",
    "settings": "{...}"
  },
  "extension_settings": {
    "webhook": "https://tu-dominio.com/webhook",
    "mycustomsetting": "valor"
  },
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "event_id": "evt_789",
  "event_time": "2026-03-23T10:30:00Z"
}

Campo	Tipo	Descripción
type	string	Tipo de evento
payload	object	Datos del evento (varía según el tipo)
channel_instance	string	ID del canal donde ocurrió el evento
instance	object	Información de tu aplicación (ver abajo)
extension_settings	object	Configuración global de tu aplicación. Ver Extension Settings
access_token	string	Token para llamar la API (válido 2 horas)
event_id	string	Identificador único del evento
event_time	string	Fecha y hora del evento (ISO 8601)

Objeto instance

Campo	Tipo	Descripción
type	string	Tipo de instancia (ej: "APP")
id	string	ID de la instancia de tu aplicación. Úsalo como app_instance en los callbacks
settings	string	JSON string con la configuración personalizada de tu aplicación. Debes parsearlo con JSON.parse() para obtener el objeto

---

Tipos de eventos

DIRECT_MESSAGE

Se emite cuando un participante (cliente, proveedor, etc.) envía un mensaje en la conversación.

{
  "type": "DIRECT_MESSAGE",
  "payload": {
    "id": "msg_001",
    "direction": "INCOMING",
    "sender": {
      "name": "Alejandro García",
      "picture": "https://example.com/avatar.jpg",
      "profile_id": "profile_123",
      "type": "PARTICIPANT"
    },
    "text": "Hola, quisiera información sobre los planes",
    "attachments": [],
    "interactions": [],
    "send_at": "2026-03-23T10:30:00Z",
    "conversation": {
      "id": "conv_456",
      "topic": "Consulta de precios",
      "participants": [...],
      "agents": [...],
      "context": {
        "assistants": {
          "app_456": {
            "intent": "pricing_inquiry",
            "step": 1
          }
        }
      }
    }
  }
}

Campos del payload

Campo	Tipo	Descripción
id	string	ID del mensaje
direction	string	INCOMING (del participante) o OUTGOING (del agente)
sender.name	string	Nombre del remitente
sender.picture	string	URL de la foto de perfil
sender.profile_id	string	ID del perfil del remitente
sender.type	string	Tipo: PARTICIPANT, AGENT, EXTENSION
text	string	Texto del mensaje
attachments	array	Archivos adjuntos
interactions	array	Interacciones (botones, listas, etc.)
send_at	string	Fecha de envío (ISO 8601)
conversation.id	string	ID de la conversación
conversation.topic	string	Tema de la conversación
conversation.context	object	Contexto de la conversación. Si tu app usa application_context, encontrarás tus datos en context.assistants.{app_instance_id}
conversation.participants	array	Participantes de la conversación
conversation.agents	array	Agentes asignados a la conversación

Estructura de participants

Campo	Tipo	Descripción
id	string	ID del participante
name	string	Nombre del participante
picture	string	URL de la foto de perfil

Estructura de agents

Campo	Tipo	Descripción
id	string	ID del agente
name	string	Nombre del agente
picture	string	URL de la foto de perfil

---

REPLY_MESSAGE (Hint Message)

Se emite cuando una aplicación o bot envía un hint message en la conversación. Los hint messages son mensajes visibles solo para el agente de servicio.

{
  "type": "REPLY_MESSAGE",
  "payload": {
    "id": "reply_001",
    "text": "El cliente preguntó por precios. Plan Básico: $79/mes",
    "callbacks": [
      {
        "id": "cb_001",
        "label": "Enviar cotización",
        "value": "send_quote"
      }
    ],
    "quick_replies": [
      {
        "text": "Socialdesk tiene dos planes: Básico por $79 al mes...",
        "attachments": []
      }
    ],
    "send_at": "2026-03-23T10:31:00Z",
    "conversation": {
      "id": "conv_456",
      "context": {}
    },
    "message": {
      "id": "msg_001",
      "direction": "INCOMING",
      "text": "Quiero saber los precios",
      "attachments": [],
      "send_at": "2026-03-23T10:30:00Z"
    },
    "sender": {
      "name": "Asistente de AI",
      "profile_id": "app_789",
      "picture": "https://example.com/bot-avatar.jpg",
      "type": "EXTENSION"
    }
  }
}

---

REPLY_MESSAGE_CALLBACK (Hint Callback)

Se emite cuando un agente hace clic en un callback de un hint message desde la interfaz.

{
  "type": "REPLY_MESSAGE_CALLBACK",
  "payload": {
    "conversation": {
      "id": "conv_456",
      "context": {}
    },
    "id": "cb_001",
    "label": "Enviar cotización",
    "value": "send_quote",
    "message": {
      "id": "msg_001",
      "direction": "INCOMING",
      "text": "Quiero saber los precios",
      "attachments": [],
      "send_at": "2026-03-23T10:30:00Z"
    }
  }
}

---

HSM_MESSAGE

Se emite cuando se envía un mensaje con plantilla (HSM) a un participante.

{
  "type": "HSM_MESSAGE",
  "payload": {
    "id": "msg_hsm_001",
    "direction": "OUTGOING",
    "text": "Hola María, tu cita es el 25 de marzo a las 3:00 PM",
    "rawText": "Hola {{1}}, tu cita es el {{2}} a las {{3}}",
    "to": 50612345678,
    "parameters": ["María", "25 de marzo", "3:00 PM"],
    "externalTemplateId": "appointment_reminder_v1",
    "send_at": "2026-03-23T10:30:00Z",
    "conversation": {
      "id": "conv_456",
      "topic": null,
      "participants": [...],
      "agents": [...],
      "context": {}
    },
    "attachments": null
  }
}

---

CONVERSATION_FINALIZED

Se emite cuando una conversación es finalizada, ya sea manualmente por un agente o automáticamente por inactividad.

{
  "type": "CONVERSATION_FINALIZED",
  "payload": {
    "id": "conv_456",
    "conversation": {
      "closedBySchedule": true,
      "id": "conv_456",
      "context": {}
    },
    "message": {
      "id": "msg_last",
      "direction": "INCOMING",
      "text": "Gracias por la información",
      "send_at": "2026-03-23T09:00:00Z"
    }
  }
}

Campo	Tipo	Descripción
conversation.closedBySchedule	boolean	true si fue cerrada automáticamente por inactividad
conversation.id	string	ID de la conversación
conversation.context	object	Contexto de la conversación
message	object	Último mensaje de la conversación