Socialdesk API v1
Socialdesk es una plataforma de comunicación como servicio (CPaaS) que permite a las empresas centralizar sus conversaciones (WhatsApp, Instagram, Facebook Messenger, entre otros) en un mismo inbox.
Esto facilita la segmentación, distribución, análisis y trazabilidad de las conversaciones con agentes externos como proveedores, clientes, ciudadanos y candidatos.
¿Para qué sirve esta API?
Esta API está diseñada para integradores y partners que desean construir soluciones sobre Socialdesk. Por ejemplo:
- Chatbots: enfócate en la lógica conversacional y deja que Socialdesk se encargue de la distribución, segmentación y análisis.
- CRMs: conecta tu CRM para enriquecer la información de las conversaciones.
- Automatizaciones: responde, segmenta y distribuye conversaciones de forma programática.
Empieza rápido
Clona nuestro proyecto de ejemplo con Node.js y Express para tener un bot funcional en minutos:
git clone https://github.com/godel-git/socialdesk-demo-app.git
cd socialdesk-demo-app
npm install
npm run dev
También puedes instalar el SDK de Node.js directamente en tu proyecto:
npm install socialdesk-node
Flujo general
Elementos en la interfaz del agente
Esta imagen muestra cómo se ven los distintos elementos que tu aplicación puede enviar dentro de la conversación:
- Direct Message (gris para incoming, azul para outgoing): mensaje enviado al participante a través del canal (WhatsApp, Instagram, etc.)
- Hint Message (celeste): mensaje visible solo para el agente con información contextual
- Callbacks: botones de acción dentro del hint message (ej: "Enviar cotización", "Reiniciar contador")
- Quick Replies: respuestas sugeridas que se cargan en el campo de escritura del agente
- Shortcuts: botones en el panel de Accesos Directos del agente, configurados en los extension settings. Incluyen los prompt callbacks que abren un formulario modal antes de ejecutar la acción
- Etiquetas: tags asignados a la conversación, visibles en el panel derecho
¿Qué tipo de mensaje necesitas enviar?
| Quiero... | Tipo de mensaje | Documentación |
|---|---|---|
| Enviar un mensaje directamente al cliente (WhatsApp, Instagram, etc.) | Direct Message | El mensaje llega al participante final a través del canal |
| Mostrar información o sugerencias solo al agente | Hint Message | El mensaje es visible únicamente dentro de la interfaz del agente |
| Enviar un mensaje con plantilla pre-aprobada (HSM) | HSM Message | Para iniciar conversaciones o enviar notificaciones programadas |
Si estás construyendo un chatbot que responde automáticamente al cliente, tu caso de uso principal son los Direct Messages. Si estás construyendo un asistente para agentes que sugiere respuestas o muestra información contextual, tu caso de uso principal son los Hint Messages.
Base URL
https://api.socialdesk.cr/web-api
Endpoints disponibles
| Endpoint | Método | Descripción |
|---|---|---|
/messages/reply | POST | Enviar direct messages al participante o hint messages al agente |
/messages/HSM | POST | Enviar mensajes con plantilla (HSM) |
/conversations/assign | POST | Distribuir conversaciones a agentes o equipos |
/conversations/labels/add | POST | Segmentar conversaciones con etiquetas |
Formato de errores
Todos los endpoints devuelven errores con la siguiente estructura:
{
"status": 400,
"error": "Descripción del error"
}
Códigos de error comunes
| Código | Descripción |
|---|---|
400 | Request inválido (faltan campos requeridos o valores incorrectos) |
401 | Token inválido o expirado |
403 | No tienes permisos para acceder al recurso solicitado |
404 | Recurso no encontrado |