Documentación API pública

Resumen Autenticación Endpoints Respuesta Ejemplos

Qué puedes hacer hoy

La API pública actual está pensada para integraciones controladas. Hoy solo expone datos de agentes y siempre opera aislada por workspace.

Lectura estable

La API pública actual expone endpoints read-only para agentes, llamadas y grabaciones. No hay operaciones de escritura ni mutaciones públicas.

Aislada por workspace

Cada API key queda vinculada al workspace que la creó y solo devuelve sus agentes.

Gestión desde Integraciones

La credencial se genera, copia y rota desde el dashboard, en la sección Integraciones.

Autenticación con x-api-key

Todas las peticiones requieren una API key de workspace en la cabecera x-api-key. La documentación es pública, pero la clave se gestiona desde el área autenticada.

1. Genera tu credencial

Crea o regenera la API key desde el dashboard de Integraciones cuando tu workspace ya está operativo.

2. Envíala en cada request

Incluye la cabecera x-api-key con el valor completo de la clave en cada petición a la public API.

3. Guárdala en backend

Usa la clave solo en procesos server-to-server, variables de entorno o servicios protegidos. No la expongas en frontend público.

Cabecera requerida

La autenticación se resuelve leyendo la cabecera x-api-key. Sin esa cabecera, la petición no entra.

HTTP

x-api-key: <YOUR_API_KEY>

Formato actual de clave

cs_live_<keyId>.<secret>

Buenas prácticas

El backend responde 401 Unauthorized cuando falta la cabecera o la clave no pasa validación.

401 Si falta la cabecera

La API responde 401 Unauthorized indicando que falta la cabecera x-api-key en la petición.

401 Si la clave no es válida

La API responde 401 Unauthorized con el mensaje API key inválida.

Guarda la API key en variables de entorno o secretos de infraestructura, no en código cliente.
Si sospechas que se ha expuesto, regénérala desde Integraciones para invalidar la anterior.
Trata esta integración como acceso server-to-server y evita usar la clave en navegadores o apps públicas.

Referencia de endpoints

La public API actual expone endpoints read-only para consultar agentes, historial de llamadas y reproducción autenticada de grabaciones.

Scope actual

Todos los endpoints quedan aislados por el workspace dueño de la API key. No exponen datos de otros tenants ni acciones de escritura.

Más endpoints públicos

Aquí tienes cada ruta con sus parámetros, tipos, valores admitidos y ejemplos listos para copiar.

Agentes del workspace

/public-api/agents

Historial de llamadas

/public-api/calls

Audio de grabación

/public-api/calls/:callSid/recording

Envío de plantilla WhatsApp

/public-api/messaging/whatsapp-template

Estadísticas de mensajería

/public-api/messaging/stats

Agentes del workspace

Lista read-only de agentes del workspace autenticado. Es el endpoint más simple para validar conectividad y credenciales.

endpoint

GEThttps://api.callspace.io/public-api/agents

Autenticación

x-api-key

Respuesta exitosa

200 OK

Devuelve

Lista de agentes del workspace

Parámetros

Este endpoint no acepta parámetros de path ni query adicionales.

Ejemplo de request

bash

curl -X GET "https://api.callspace.io/public-api/agents" \
  -H "x-api-key: <YOUR_API_KEY>"

Orden de salida

Los agentes se devuelven por createdAt DESC, mostrando primero los más recientes.

Historial de llamadas

Devuelve una respuesta paginada con llamadas agregadas, estado, duración, agente y metadatos de grabación.

endpoint

GEThttps://api.callspace.io/public-api/calls

Autenticación

x-api-key

Respuesta exitosa

200 OK

Devuelve

Página de llamadas del workspace

Parámetros

Parámetro	Ubicación	Tipo	Obligatorio	Admite	Ejemplo	Descripción
page	query	integer	No	>= 1	1	Número de página para navegar la respuesta paginada.
limit	query	integer	No	1-1000	25	Cantidad máxima de resultados por página.
direction	query	string	No	inbound \| outbound \| missed	inbound	Filtra por llamadas entrantes, salientes o perdidas.
dateFrom	query	date string	No	YYYY-MM-DD \| ISO 8601	2026-05-01	Fecha inicial del rango. Se interpreta desde el inicio del día.
dateTo	query	date string	No	YYYY-MM-DD \| ISO 8601	2026-05-31	Fecha final del rango. Se interpreta hasta el final del día.
agentIds	query	csv string	No	uuid,uuid,...	a1b2,a3b4	Lista separada por comas con IDs de agentes para filtrar solo sus llamadas.
teamId	query	string	No	UUID	team_123	ID de equipo para limitar el historial a los agentes de ese equipo.
q	query	string	No	texto libre	600	Búsqueda parcial sobre fromNumber y toNumber.

Ejemplo de request

bash

curl -G "https://api.callspace.io/public-api/calls" \
  -H "x-api-key: <YOUR_API_KEY>" \
  --data-urlencode "direction=inbound" \
  --data-urlencode "dateFrom=2026-05-01" \
  --data-urlencode "limit=25" \
  --data-urlencode "q=600"

Filtros disponibles

Combina filtros libres para paneles, búsquedas o sincronizaciones. direction solo admite inbound, outbound o missed.

Audio de grabación

Sirve el audio inline de una llamada concreta cuando la grabación existe y pertenece al workspace autenticado.

endpoint

GEThttps://api.callspace.io/public-api/calls/:callSid/recording

Autenticación

x-api-key

Respuesta exitosa

200 OK

Devuelve

Audio MP3 inline

Parámetros

Parámetro	Ubicación	Tipo	Obligatorio	Admite	Ejemplo	Descripción
callSid	path	string	Sí	CA...	CA1234567890abcdef1234567890abcd	Identificador único de la llamada devuelto por /public-api/calls.

Ejemplo de request

bash

curl -L "https://api.callspace.io/public-api/calls/CA1234567890abcdef1234567890abcd/recording" \
  -H "x-api-key: <YOUR_API_KEY>" \
  --output call-recording.mp3

Parámetro requerido

Usa el callSid devuelto por /public-api/calls. Si la llamada no tiene grabación, la API responde 404.

Envío de plantilla WhatsApp

Envía un mensaje de WhatsApp usando una plantilla aprobada. Soporta variables y adjunto de header (imagen o PDF según el tipo de plantilla).

endpoint

POSThttps://api.callspace.io/public-api/messaging/whatsapp-template

Autenticación

x-api-key

Respuesta exitosa

201 Created

Devuelve

ID de conversación y mensaje

Parámetros

Parámetro	Ubicación	Tipo	Obligatorio	Admite	Ejemplo	Descripción
fromPhoneNumberId	body	string	Sí	UUID \| E.164	+34600000000	UUID del número remitente o su número en formato E.164. Si se pasa E.164, se resuelve internamente.
toE164	body	string	Sí	E.164	+34611222333	Número destino en formato E.164 (ej. +34611222333).
templateId	body	string	Sí	UUID \| nombre	bienvenida	UUID o nombre de la plantilla aprobada. Máximo 100 caracteres.
variables	body	object	Sí	{ "1": "valor" }	{"1":"Hola"}	Mapa de variables de la plantilla. Las claves son los índices de los placeholders (ej. {"1":"Valor"}).
headerAttachment	body	object	No	fileName, mimeType, contentBase64	{ ... }	Adjunto para el header de la plantilla. Debe incluir fileName, mimeType y contentBase64. Máximo 16 MB.

Ejemplo de request

bash

curl -X POST "https://api.callspace.io/public-api/messaging/whatsapp-template" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"fromPhoneNumberId":"+34600000000","toE164":"+34611222333","templateId":"bienvenida","variables":{"1":"Hola"}}'

templateId acepta UUID o nombre

Puedes pasar el UUID interno o el nombre de la plantilla. El adjunto headerAttachment es obligatorio solo si la plantilla tiene header de tipo document o media.

Estadísticas de mensajería

Devuelve estadísticas de mensajería por agente para el workspace. Útil para dashboards externos o reportes de actividad.

endpoint

GEThttps://api.callspace.io/public-api/messaging/stats

Autenticación

x-api-key

Respuesta exitosa

200 OK

Devuelve

Estadísticas por agente

Parámetros

Parámetro	Ubicación	Tipo	Obligatorio	Admite	Ejemplo	Descripción
referenceDate	query	string	No	YYYY-MM-DD	2026-06-26	Fecha de referencia para las estadísticas en formato YYYY-MM-DD.
totalFrom	query	string	No	YYYY-MM-DD	2026-06-01	Inicio del rango para el total acumulado en formato YYYY-MM-DD.

Ejemplo de request

bash

curl -G "https://api.callspace.io/public-api/messaging/stats" \
  -H "x-api-key: <YOUR_API_KEY>" \
  --data-urlencode "referenceDate=2026-06-26"

Formato de respuesta

La respuesta es un array de objetos agente con un contrato estable y orientado a integraciones.

Campos devueltos

Estos son los campos actuales del DTO público devuelto por el endpoint.

Campo	Tipo	Descripción
id	string	Identificador único del agente.
name	string	Nombre del agente.
lastName	string	Apellidos del agente.
email	string	Correo electrónico del agente.
extension	string \| null	Extensión interna del agente o null si no existe.
role	string	Rol actual del agente dentro del workspace.
status	string	Estado operativo actual del agente.
whatsappEnabled	boolean	Indica si el agente tiene WhatsApp habilitado.
createdAt	ISO datetime	Fecha de creación del agente en formato ISO.
updatedAt	ISO datetime	Fecha de última actualización del agente en formato ISO.

Ejemplo JSON

Ejemplo de payload compatible con la implementación actual.

JSON

[
  {
    "id": "3f0a9d20-8ab8-4ee3-9813-8a9f6f0b5cc1",
    "name": "Lucia",
    "lastName": "Martin",
    "email": "lucia@acme.com",
    "extension": "201",
    "role": "AGENT",
    "status": "ACTIVE",
    "whatsappEnabled": true,
    "createdAt": "2026-05-08T10:12:34.000Z",
    "updatedAt": "2026-05-08T10:12:34.000Z"
  }
]

Ejemplos de uso

Snippets listos para consumir el endpoint con tu API key desde entornos backend o scripts internos.

Ejemplo con curl

bash

curl -X GET "https://api.callspace.io/public-api/agents" \
  -H "x-api-key: <YOUR_API_KEY>"

Ejemplo con fetch

TypeScript

const response = await fetch('https://api.callspace.io/public-api/agents', {
  method: 'GET',
  headers: {
    'x-api-key': process.env.CALLSPACE_API_KEY!,
  },
});

if (!response.ok) {
  throw new Error('Request failed');
}

const agents = await response.json();

Resultado esperado

Si la petición es correcta, recibirás un array JSON de agentes del workspace autenticado con status 200 OK.

Gestión de credenciales

La clave se gestiona desde Integraciones

Usa esta documentación como referencia pública y mantén la generación, copia y rotación de la API key dentro del dashboard autenticado.

Abrir Integraciones

Documentación de la API pública de CallSpace

Qué puedes hacer hoy

Lectura estable

Aislada por workspace

Gestión desde Integraciones

Autenticación con x-api-key

1. Genera tu credencial

2. Envíala en cada request

3. Guárdala en backend

Cabecera requerida

Buenas prácticas

Referencia de endpoints

Agentes del workspace

Historial de llamadas

Audio de grabación

Envío de plantilla WhatsApp

Estadísticas de mensajería

Formato de respuesta

Campos devueltos

Ejemplo JSON

Ejemplos de uso

La clave se gestiona desde Integraciones