Direct Messages

Los direct messages son mensajes que se envían directamente al participante final (cliente, proveedor, ciudadano, etc.) a través del canal de comunicación (WhatsApp, Instagram, etc.).

A diferencia de los hint messages que solo son visibles para el agente, los direct messages llegan al participante de la conversación.

¿Cómo se ven en la interfaz?

Ver Elementos en la interfaz del agente para una referencia visual de cómo se ven los direct messages (burbujas verdes) dentro de la conversación.

Mismo endpoint, diferente comportamiento

Los direct messages usan el mismo endpoint que los hint messages (/messages/reply), pero con el parámetro send_as_direct_message: true.

---

Configuración requerida

Para que tu aplicación pueda enviar direct messages, el administrador de la cuenta debe habilitar el permiso:

"Permitir el envío de respuestas automáticas a tus clientes por parte de esta aplicación"

Este permiso se configura en los ajustes de la aplicación dentro de Socialdesk.

Comportamiento según configuración

send_as_direct_message	Permiso activado	Resultado
false o no enviado	-	Se envía como hint message
true	Si	Se envía como direct message al participante
true	No	Se envía como hint message (fallback seguro), incluyendo las quick_replies como sugerencias para el agente

---

Endpoint

POST /web-api/messages/reply

Headers

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

Body

{
  "text": "¡Hola! El Plan Básico incluye 8 usuarios y 2 líneas de WhatsApp por $79/mes + IVA.",
  "message_id": "msg_001",
  "conversation_id": "conv_456",
  "send_as_direct_message": true,
  "application_context": {
    "last_intent": "pricing_inquiry",
    "auto_replied": true
  }
}

Parámetros

Campo	Tipo	Requerido	Descripción
text	string	Si*	Texto del mensaje que recibirá el participante
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
send_as_direct_message	boolean	Si	Debe ser true para enviar como direct message
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 attachments

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

Para la estructura de interactions (botones y listas de WhatsApp), consulta la documentación de interactions en Hint Messages.

Callbacks y quick_replies

Cuando se envía como direct message, los callbacks y quick_replies no aplican, ya que el mensaje va directo al participante y no al agente. Si el permiso de respuestas automáticas no está activado, el mensaje se convierte en un hint y las quick_replies se mostrarán como sugerencias al agente.

---

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": "¡Hola! Gracias por contactarnos. Un asesor te atenderá en breve.",
    "message_id": "msg_abc123",
    "conversation_id": "conv_xyz789",
    "send_as_direct_message": true
  }'

Ejemplo: con adjunto

curl -X POST https://api.socialdesk.cr/web-api/messages/reply \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Aquí está la cotización que solicitaste:",
    "attachments": [
      {
        "type": "IMAGE",
        "url": "https://example.com/cotizacion.pdf",
        "fileName": "cotizacion.pdf"
      }
    ],
    "message_id": "msg_abc123",
    "conversation_id": "conv_xyz789",
    "send_as_direct_message": true
  }'

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