Chat por API

Usa el mismo agente que ya tienes configurado (prompt, herramientas y perfil de canal) desde tu aplicación, sin el widget de SignalCore y sin enviar el mensaje por WhatsApp o SMS.

Ideal para un chat web personalizado: el widget habla con tu backend, y tu backend llama a SignalCore con la API key.

Cómo funciona

Visitante → tu widget / app → tu backend → SignalCore POST /agents/{id}/chat → respuesta del agente

1. El usuario escribe en tu interfaz
2. Tu servidor envía el mensaje a SignalCore con X-API-Key
3. El agente responde con el mismo perfil de canal que indiques (whatsapp, sms, etc.)
4. Guardas el session_id y lo reutilizas en los siguientes turnos

Autenticación

Cabecera X-API-Key con la clave de tu negocio (panel → Ajustes → API).

Base URL de producción:

https://api.signalcore.ai/api/v1

Endpoint

POST /agents/{agent_id}/chat

Cuerpo de la solicitud

Respuesta

Referencia completa del esquema en la referencia API (POST /agents/{agent_id}/chat).

Ejemplo: primera respuesta

curl -X POST "https://api.signalcore.ai/api/v1/agents/agt_TU_AGENTE/chat" \
  -H "X-API-Key: sk_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hola, quiero agendar una cita",
    "channel": "whatsapp"
  }'

Respuesta típica:

{
  "response": "¡Claro! ¿Qué día te vendría bien?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "conversation_history": [
    { "role": "user", "content": "Hola, quiero agendar una cita" },
    { "role": "assistant", "content": "¡Claro! ¿Qué día te vendría bien?" }
  ],
  "tool_calls": []
}

Ejemplo: continuar la conversación

Reutiliza el mismo session_id y el mismo channel:

curl -X POST "https://api.signalcore.ai/api/v1/agents/agt_TU_AGENTE/chat" \
  -H "X-API-Key: sk_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Mañana por la tarde me va bien",
    "channel": "whatsapp",
    "session_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

TypeScript (desde tu backend)

const BASE = 'https://api.signalcore.ai/api/v1';
const apiKey = process.env.SIGNALCORE_API_KEY!;
async function chatWithAgent(params: {
  agentId: string;
  message: string;
  channel: string;
  sessionId?: string;
}) {
  const res = await fetch(`${BASE}/agents/${params.agentId}/chat`, {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({
      message: params.message,
      channel: params.channel,
      ...(params.sessionId ? { session_id: params.sessionId } : {}),
    }),
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json() as Promise<{
    response: string;
    session_id: string;
    conversation_history: Array<{ role: string; content?: string }>;
    tool_calls: unknown[];
  }>;
}
// Primer turno
const first = await chatWithAgent({
  agentId: 'agt_xxx',
  message: 'Hola',
  channel: 'whatsapp',
});
// Siguientes turnos
const next = await chatWithAgent({
  agentId: 'agt_xxx',
  message: 'Quiero una cita',
  channel: 'whatsapp',
  sessionId: first.session_id,
});

Python (desde tu backend)

import os
import httpx
BASE = "https://api.signalcore.ai/api/v1"
headers = {
    "X-API-Key": os.environ["SIGNALCORE_API_KEY"],
    "Accept": "application/json",
}
def chat(agent_id: str, message: str, channel: str, session_id: str | None = None):
    body = {"message": message, "channel": channel}
    if session_id:
        body["session_id"] = session_id
    with httpx.Client(base_url=BASE, headers=headers, timeout=120.0) as client:
        r = client.post(f"/agents/{agent_id}/chat", json=body)
        r.raise_for_status()
        return r.json()
first = chat("agt_xxx", "Hola", "whatsapp")
follow_up = chat("agt_xxx", "Quiero una cita", "whatsapp", first["session_id"])
print(follow_up["response"])

Diferencias con /execute y /test

Límites y notas

• Las sesiones de chat tienen TTL (historial en caché); si la sesión caduca, omite session_id y empieza una nueva.
• El consumo de tokens se factura como uso de LLM (no como mensaje de canal).
• Este endpoint no crea un lead en la bandeja ni envía WhatsApp; solo genera la respuesta del agente.

¿Necesitas enviar un mensaje real al teléfono del lead? Usa POST /execute en la referencia API.