HSM Messages (Plantillas)

Los HSM Messages (Highly Structured Messages) son mensajes con plantilla pre-aprobada que se envían directamente al participante a través del canal de comunicación (WhatsApp, etc.).

Estos mensajes pueden ser:

Enviados inmediatamente
Programados para una fecha y hora futura

Endpoint

POST /web-api/messages/HSM

Headers

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

Body

Puedes identificar al destinatario de dos formas: usando account_contact_id si el contacto ya existe en Socialdesk, o contact para crear uno nuevo automáticamente.

Opción A: con contacto existente (`account_contact_id`)

{
  "channel_id": "ch_001",
  "account_contact_id": "ac_123",
  "raw_text": "Hola {{1}}, tu cita es el {{2}} a las {{3}}",
  "parameters": ["María", "25 de marzo", "3:00 PM"],
  "external_template_id": "appointment_reminder_v1"
}

Opción B: con contacto nuevo (`contact`)

{
  "channel_id": "ch_001",
  "contact": {
    "account_id": "acc_001",
    "first_name": "María",
    "last_name": "López",
    "phone": "+50688881234",
    "email": "maria@ejemplo.com"
  },
  "raw_text": "Hola {{1}}, tu cita es el {{2}} a las {{3}}",
  "parameters": ["María", "25 de marzo", "3:00 PM"],
  "external_template_id": "appointment_reminder_v1"
}

Contacto requerido

Debes enviar account_contact_id o contact, pero no ambos. Si no se envía ninguno de los dos, la API retornará un error 400.

Parámetros

Campo	Tipo	Requerido	Descripción
`channel_id`	string	Si	ID del canal por donde se enviará el mensaje. Viene en el webhook: `channel_instance`
`account_contact_id`	string	No*	ID del contacto existente en Socialdesk
`contact`	object	No*	Datos para crear un contacto nuevo. Ver estructura abajo
`raw_text`	string	Si	Texto de la plantilla con placeholders `{{n}}`
`parameters`	array	No	Valores para reemplazar los placeholders
`external_template_id`	string	No	ID de la plantilla externa (WhatsApp Business)
`assign_entity`	string	No	Entidad a asignar: `USER` o `TEAM`
`assign_entity_id`	string	No	ID de la entidad a asignar
`conversation_id`	string	No	ID de la conversación (si ya existe). Viene en el webhook: `payload.conversation.id`
`send_at`	string	No	Fecha para programar el envío (ISO 8601). Si se omite, se envía inmediatamente

*Se requiere account_contact_id o contact, pero no ambos. Si el contacto ya existe usa account_contact_id; si necesitas crear uno nuevo usa contact.

Estructura de `contact` (cuando no se usa `account_contact_id`)

Campo	Tipo	Requerido	Descripción
`account_id`	string	Si	ID de la cuenta
`first_name`	string	No	Nombre
`last_name`	string	No	Apellido
`phone`	string	Si	Número de teléfono
`email`	string	No	Correo electrónico
`image_url`	string	No	URL de la imagen de perfil

Respuesta

{
  "success": true
}

Ejemplo: envío inmediato

curl -X POST https://api.socialdesk.cr/web-api/messages/HSM \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "ch_001",
    "account_contact_id": "ac_123",
    "raw_text": "Hola {{1}}, gracias por tu compra. Tu número de orden es {{2}}.",
    "parameters": ["Carlos", "ORD-2026-001"],
    "external_template_id": "order_confirmation_v1"
  }'

Ejemplo: envío con contacto nuevo

curl -X POST https://api.socialdesk.cr/web-api/messages/HSM \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "ch_001",
    "contact": {
      "account_id": "acc_001",
      "first_name": "María",
      "last_name": "López",
      "phone": "+50688881234"
    },
    "raw_text": "Hola {{1}}, gracias por registrarte en nuestro servicio.",
    "parameters": ["María"],
    "external_template_id": "welcome_v1"
  }'

Ejemplo: envío programado

curl -X POST https://api.socialdesk.cr/web-api/messages/HSM \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "ch_001",
    "account_contact_id": "ac_123",
    "raw_text": "Hola {{1}}, te recordamos tu cita mañana a las {{2}}.",
    "parameters": ["María", "3:00 PM"],
    "external_template_id": "appointment_reminder_v1",
    "send_at": "2026-03-24T08:00:00Z"
  }'

Programar envíos

Cuando usas send_at, el mensaje queda programado y puede ser cancelado antes de la fecha de envío usando el endpoint de cancelación.

Errores comunes

Código	Error	Descripción
400	`You must send text`	Falta el `raw_text`
400	`You must include a channel_id`	Falta el `channel_id`
400	`You must include an existing account_contact_id or new contact info`	Falta contacto
400	`Invalid entity parameter`	`assign_entity` no es `USER` ni `TEAM`
400	`Sent at can not be a past date`	`send_at` es una fecha pasada
403	`Forbidden`	No tienes permisos para enviar al canal o contacto indicado
401	`Unauthorized`	Token inválido o expirado

Endpoint​

Headers​

Body​

Opción A: con contacto existente (account_contact_id)​

Opción B: con contacto nuevo (contact)​

Parámetros​

Estructura de contact (cuando no se usa account_contact_id)​

Respuesta​

Ejemplo: envío inmediato​

Ejemplo: envío con contacto nuevo​

Ejemplo: envío programado​

Errores comunes​