Hint Messages

Los hint messages son mensajes que se muestran al agente de servicio dentro de la conversación. A diferencia de los direct messages, los hint messages son visibles solo para el agente.

Este es el principal diferenciador de Socialdesk: tu aplicación puede guiar al agente con información relevante, sugerencias de respuesta y acciones ejecutables directamente desde el chat.

¿Cómo se ven en la interfaz?

Ver Elementos en la interfaz del agente para una referencia visual de hint messages, callbacks, quick replies y más.

¿Qué pueden contener los hint messages?

Texto informativo: información procesada por tu bot o aplicación
Callbacks: botones que el agente puede presionar para ejecutar una acción en tu webhook
Respuestas rápidas (quick replies): textos predefinidos que se cargan automáticamente en el campo de respuesta del agente

¿Hint o Direct?

Este endpoint (/messages/reply) también permite enviar direct messages al participante final usando send_as_direct_message: true. Cuando no se envía ese parámetro, el mensaje se comporta como un hint message.

Endpoint

POST /web-api/messages/reply

Headers

Authorization: Bearer {access_token}
Content-Type: application/json

Body

{
  "text": "El cliente preguntó por precios del plan básico",
  "message_id": "msg_001",
  "conversation_id": "conv_456",
  "callbacks": [
    {
      "id": "cb_send_quote",
      "label": "Enviar cotización",
      "value": "send_quote_basic"
    }
  ],
  "quick_replies": [
    {
      "text": "Socialdesk tiene dos planes: Básico por $79 al mes y Avanzado por $249 al mes.",
      "attachments": []
    }
  ],
  "application_context": {
    "last_intent": "pricing_inquiry",
    "confidence": 0.95
  }
}

Parámetros

Campo	Tipo	Requerido	Descripción
`text`	string	Si*	Texto del hint message visible para el agente
`attachments`	array	Si*	Archivos adjuntos
`interactions`	array	No	Interacciones asociadas al mensaje (botones, listas, etc.)
`message_id`	string	Si	ID del mensaje al que se responde. Viene en el webhook: `payload.id`
`conversation_id`	string	Si	ID de la conversación. Viene en el webhook: `payload.conversation.id`
`callbacks`	array	No	Botones de acción para el agente
`quick_replies`	array	No	Respuestas predefinidas
`application_context`	object	No	JSON para persistir el contexto conversacional de tu aplicación. Ver application_context

*Se requiere al menos text o attachments.

Estructura de `callbacks`

Campo	Tipo	Descripción
`id`	string	Identificador único del callback
`label`	string	Texto visible en el botón
`value`	string	Valor que se envía cuando el agente hace clic

Estructura de `quick_replies`

Campo	Tipo	Descripción
`text`	string	Texto predefinido que se carga en el campo de respuesta
`attachments`	array	Archivos adjuntos opcionales

Estructura de `attachments`

Campo	Tipo	Descripción
`type`	string	Tipo: `IMAGE`, `VIDEO`, `AUDIO`, `TEXT`, `CONTACTS`
`url`	string	URL del archivo
`fileName`	string	Nombre del archivo

Estructura de `interactions`

Las interactions permiten enviar botones o listas interactivas al participante a través de WhatsApp. El campo config sigue la estructura de mensajes interactivos de la Meta Cloud API. Por el momento, el único valor soportado para label es "whatsapp".

Campo	Tipo	Descripción
`label`	string	Canal de la interacción. Actualmente solo `"whatsapp"`
`config`	object	Objeto interactivo de WhatsApp. Soporta `type: "button"` y `type: "list"`

Botones (`type: "button"`)

{
  "label": "whatsapp",
  "config": {
    "type": "button",
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "opcion_1", "title": "Opción 1" } },
        { "type": "reply", "reply": { "id": "opcion_2", "title": "Opción 2" } }
      ]
    }
  }
}

Listas (`type: "list"`)

{
  "label": "whatsapp",
  "config": {
    "type": "list",
    "action": {
      "button": "Ver opciones",
      "sections": [
        {
          "title": "Sección 1",
          "rows": [
            { "id": "1", "title": "Opción A" },
            { "id": "2", "title": "Opción B" }
          ]
        }
      ]
    }
  }
}

Para la referencia completa de campos, límites y validaciones, consulta la documentación oficial de Meta:

application_context

El application_context permite a tu aplicación persistir contexto conversacional dentro de la conversación. Cada vez que envías un mensaje con application_context, Socialdesk almacena ese JSON y lo devuelve en los siguientes eventos webhook de esa conversación (dentro de payload.conversation.context).

Esto es útil para que tu aplicación "recuerde" lo que ha procesado a lo largo de la conversación sin necesidad de mantener estado en tu propio servidor.

Scope por aplicación

Socialdesk permite que múltiples aplicaciones o bots operen en una misma conversación. El application_context tiene scope por aplicación, por lo que tu contexto no sobrescribe el de otras aplicaciones.

Ejemplo de uso

// Primer mensaje: guardas el intent detectado
{
  "text": "El cliente pregunta por precios",
  "message_id": "msg_001",
  "conversation_id": "conv_456",
  "application_context": {
    "intent": "pricing_inquiry",
    "step": 1
  }
}

// Siguiente evento webhook, recibes el contexto de vuelta en:
// payload.conversation.context.assistants.{app_instance_id}
// → { "intent": "pricing_inquiry", "step": 1 }

// Segundo mensaje: actualizas el contexto
{
  "text": "El cliente eligió el Plan Básico",
  "message_id": "msg_002",
  "conversation_id": "conv_456",
  "application_context": {
    "intent": "pricing_inquiry",
    "step": 2,
    "selected_plan": "basic"
  }
}

Respuesta

{
  "success": true
}

Ejemplo con cURL

curl -X POST https://api.socialdesk.cr/web-api/messages/reply \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "El cliente está interesado en el Plan Básico ($79/mes)",
    "message_id": "msg_abc123",
    "conversation_id": "conv_xyz789",
    "callbacks": [
      {
        "id": "cb_1",
        "label": "Agendar demo",
        "value": "schedule_demo"
      },
      {
        "id": "cb_2",
        "label": "Enviar brochure",
        "value": "send_brochure"
      }
    ],
    "quick_replies": [
      {
        "text": "¡Con gusto! El Plan Básico incluye 8 usuarios, 2 líneas de WhatsApp, Instagram y Facebook Messenger por $79 + IVA al mes.",
        "attachments": []
      }
    ]
  }'

Errores comunes

Código	Error	Descripción
400	`You must send text or attachment`	No se envió ni texto ni attachments
400	`Message is required`	Falta el `message_id`
400	`Conversation is required`	Falta el `conversation_id`
400	`Cannot send both context and application_context`	Se enviaron ambos campos; son mutuamente excluyentes
401	`Unauthorized`	Token inválido o expirado
403	`Only app extensions can use application_context`	Solo las aplicaciones (tipo `APP`) pueden usar `application_context`

¿Qué pueden contener los hint messages?​

Endpoint​

Headers​

Body​

Parámetros​

Estructura de callbacks​

Estructura de quick_replies​

Estructura de attachments​

Estructura de interactions​

Botones (type: "button")​

Listas (type: "list")​

application_context​

Ejemplo de uso​

Respuesta​

Ejemplo con cURL​

Errores comunes​