CallChat IA

API para tu web o tu programa

Consulta las horas libres, haz y anula reservas y habla con la asistente desde tu propio sistema: tu web, tu app, tu programa de gestión o una automatización (Zapier, Make, n8n…).

1. La clave

Créala en el panel, en API y claves, eligiendo qué puede hacer: leer (negocio, servicios y horas libres), reservas (ver las reservas con el nombre y el teléfono de cada cliente), reservar (hacer y anular reservas) y mensajes (hablar con la asistente). Da a cada clave solo lo que necesita. La clave se enseña una sola vez: guárdala en un sitio seguro. Si se pierde o se filtra, revócala y crea otra.

Mándala en cada petición, en la cabecera Authorization:

Authorization: Bearer cc_tu_clave

Úsala desde tu servidor, nunca en una página web: cualquiera que abra la página la vería. Para poner la asistente en tu web sin programar nada, usa el botón para tu web (panel → App del cliente y QR → «En tu página web»).

2. Cómo funciona

3. Peticiones

PeticiónPermisoPara qué
GET /negocioleerNombre, dirección, horario de la semana y cierres próximos.
GET /serviciosleerLo que se puede reservar, con su id, duración y precio.
GET /huecosleerHoras libres de un día: ?servicio=3&fecha=2026-11-27&personas=4.
POST /reservasreservarHacer una reserva.
GET /reservasreservasReservas de un periodo (?desde=&hasta=, como mucho 92 días y 500 reservas: si hay más, hay_mas es true; &telefono= para las de un cliente).
GET /reservas/{id}reservasUna reserva.
POST /reservas/{id}/anularreservarAnular una reserva. Con el teléfono de la reserva en el cuerpo: { "telefono": "+34 600 123 456" }.
POST /mensajesmensajesHablar con la asistente por escrito: contesta igual que por WhatsApp y puede reservar ella misma.
GET /mensajesmensajesLo nuevo de la conversación de un cliente (?telefono=&desde= el último id que tengas): así recoges lo que conteste una persona del equipo.

Ver las horas libres

curl "https://chat.callchatia.com/api/v1/huecos?servicio=3&fecha=2026-11-27&personas=4" \
  -H "Authorization: Bearer cc_tu_clave"

{ "fecha": "2026-11-27", "dia": "viernes 27 de noviembre", "personas": 4,
  "huecos": [ { "hora": "21:00", "inicio": "2026-11-27 21:00" }, { "hora": "21:30", "inicio": "2026-11-27 21:30" } ] }

Hacer una reserva

curl -X POST "https://chat.callchatia.com/api/v1/reservas" \
  -H "Authorization: Bearer cc_tu_clave" -H "Content-Type: application/json" \
  -d '{ "servicio": 3, "inicio": "2026-11-27 21:30", "personas": 4,
        "nombre": "Ana García", "telefono": "+34 600 123 456", "notas": "Una trona" }'

{ "id": 812, "servicio": "Cena", "inicio": "2026-11-27 21:30", "fin": "2026-11-27 23:30", "personas": 4,
  "estado": "confirmada", "nombre": "Ana García", "telefono": "+34600123456", "origen": "api", "notas": "Una trona" }

Si la hora ya no está libre, la respuesta es 400 con el código ocupado: vuelve a pedir los huecos.

Hablar con la asistente

curl -X POST "https://chat.callchatia.com/api/v1/mensajes" \
  -H "Authorization: Bearer cc_tu_clave" -H "Content-Type: application/json" \
  -d '{ "telefono": "+34 600 123 456", "nombre": "Ana", "texto": "¿Tenéis mesa para 4 el viernes a las nueve y media?" }'

{ "conversacion_id": 57,
  "respuestas": [ { "texto": "¡Hola, Ana! Sí, el viernes 27 tengo mesa para 4 a las 21:30. ¿A nombre de quién la pongo?", "botones": [] } ],
  "documentos": [], "reservas": [], "con_persona": false }

El teléfono identifica la conversación: manda siempre el mismo para el mismo cliente y la asistente recordará lo hablado. Si reserva, cambia o anula algo, lo verás en reservas. Si manda la carta, va en documentos con su dirección. Si la conversación la lleva una persona del equipo, con_persona es true y la asistente no contesta: lo que escriba el equipo desde el panel lo recoges con GET /mensajes?telefono=…&desde=… (cada pocos segundos mientras el cliente espera).

El teléfono lo pones tú y nadie lo comprueba: por eso, por la API la asistente solo ve y toca las reservas hechas por la API. Si quieres que tus clientes vean también las que hicieron por WhatsApp o por teléfono, comprueba antes en tu web que el móvil es suyo (un código por SMS, por ejemplo).

En JavaScript (Node, desde tu servidor)

const r = await fetch("https://chat.callchatia.com/api/v1/reservas", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CALLCHAT_CLAVE}`, "Content-Type": "application/json" },
  body: JSON.stringify({ servicio: 3, inicio: "2026-11-27 21:30", personas: 4, nombre: "Ana García", telefono: "+34600123456" }),
});
const datos = await r.json();
if (!r.ok) console.error(datos.error.codigo, datos.error.mensaje);

En PHP

$ch = curl_init("https://chat.callchatia.com/api/v1/huecos?servicio=3&fecha=2026-11-27&personas=4");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CALLCHAT_CLAVE")]]);
$huecos = json_decode(curl_exec($ch), true);

4. Errores

Siempre con el mismo formato: { "error": { "codigo": "ocupado", "mensaje": "Esa hora ya no está libre" } }.

EstadoCuándo
400Faltan datos o no son válidos (datos, nombre, telefono, json), o la agenda no lo permite (ocupado, tarde, tope_citas…).
401Falta la clave, no es válida o está revocada.
403La clave no tiene ese permiso, el negocio no está activo o el cliente está bloqueado.
404Esa reserva, ese servicio o esa dirección no existen en tu negocio.
429Te has pasado de los topes (por minuto o del día).
500Ha fallado algo de nuestro lado: vuelve a intentarlo.

5. Especificación OpenAPI

Para generar un cliente o importarla en Postman, Insomnia o tu herramienta favorita: https://chat.callchatia.com/api/v1/openapi.json.