Hint Callbacks

Los hint callbacks permiten a tu aplicación recibir notificaciones cuando un agente hace clic en un botón (callback) de un hint message.

Cuando tu aplicación envía un hint message con callbacks, cada callback se muestra como un botón en la interfaz del agente. Al hacer clic, Socialdesk:

1. Emite un evento REPLY_MESSAGE_CALLBACK a tu webhook
2. Te permite responder ejecutando una acción (por ejemplo, enviar un correo, agendar una cita, etc.)

¿Cómo se ven en la interfaz?

Ver Elementos en la interfaz del agente para una referencia visual de cómo se ven los callbacks (botones de acción) dentro del hint message.

---

Flujo completo

1. Tu app envía un hint message con callbacks:
   POST /web-api/messages/reply
   → callbacks: [{ id: "cb_1", label: "Agendar demo", value: "schedule_demo" }]

2. El agente ve el botón "Agendar demo" en la interfaz

3. El agente hace clic en el botón

4. Socialdesk emite evento REPLY_MESSAGE_CALLBACK a tu webhook:
   → { id: "cb_1", value: "schedule_demo", message: { id: "msg_001", ... }, ... }

5. Tu app procesa el callback y responde con /web-api/messages/reply:
   - Enviar otro hint message con el resultado
   - Enviar un mensaje directo al participante (send_as_direct_message: true)
   - Ejecutar lógica de negocio

Ejemplo

// Cuando llega un REPLY_MESSAGE_CALLBACK
if (eventType === 'REPLY_MESSAGE_CALLBACK') {
  const callbackValue = payload.value;

  if (callbackValue === 'send_quote') {
    // Responder con un direct message al participante
    await client.sendDirectMessage({
      text: 'Aquí tienes nuestra cotización...',
      message_id: payload.message.id,
      conversation_id: payload.conversation.id,
    });
  }

  if (callbackValue === 'reset_counter') {
    // Responder con un hint message al agente
    await client.sendHintMessage({
      text: 'Contador reiniciado.',
      message_id: payload.message.id,
      conversation_id: payload.conversation.id,
      application_context: { messageCount: 0 },
    });
  }
}

Errores comunes

Código	Error	Descripción
401	Unauthorized	Token inválido o expirado