Documentación

Quickstart

En menos de 5 minutos puedes enviar tu primer mensaje a un agente de Conectachat. Necesitas:

1. Una cuenta en app.conectaachat.com
2. Un agente creado en el dashboard
3. Una API key generada en Agentes → Canales → API REST → Generar API Key

Tu primer request

curl -X POST https://api.conectaachat.com/api/messages/chat \
  -H "x-api-key: cc_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hola, ¿cuáles son sus horarios de atención?",
    "visitorId": "usuario-123"
  }'

Respuesta

{
  "message": "¡Hola! Atendemos de lunes a viernes de 9am a 6pm. ¿En qué más puedo ayudarte?",
  "conversationId": "conv_abc123def456",
  "handoffRequested": false,
  "creditsUsed": 3
}

Autenticación

API Key — para chat e integraciones

Incluye tu API key en el header de cada request. Las keys tienen prefijo cc_ y se crean desde el dashboard.

x-api-key: cc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Bearer JWT — para endpoints de gestión

Los endpoints de gestión (agentes, conversaciones, etc.) requieren el token JWT de tu sesión de Supabase:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-organization-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

POST /api/messages/chat

Envía un mensaje al agente y recibe su respuesta generada por IA. Es el endpoint principal para todas las integraciones externas.

Headers

Body

Respuesta 200 OK

{
  "message": "string",           // Respuesta generada por el agente
  "conversationId": "string",    // UUID de la conversación
  "handoffRequested": false,     // true si el agente solicita transferir a humano
  "creditsUsed": 3               // Créditos descontados por este mensaje
}

Ejemplo con metadata

curl -X POST https://api.conectaachat.com/api/messages/chat \
  -H "x-api-key: cc_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quiero información sobre el plan Pro",
    "visitorId": "user-456",
    "metadata": {
      "name": "María González",
      "email": "maria@empresa.com",
      "source": "landing_page"
    }
  }'

GET /api/conversations

Lista las conversaciones de tu organización. Requiere autenticación JWT.

Query params

[
  {
    "id": "conv_abc123",
    "visitor_id": "user-456",
    "status": "active",
    "messages_count": 8,
    "last_message_at": "2026-04-25T14:30:00Z",
    "metadata": { "name": "María González", "email": "maria@empresa.com" }
  }
]

GET /api/agents

Lista los agentes de tu organización. Requiere autenticación JWT.

[
  {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Soporte Técnico",
    "language": "es",
    "tone": "professional",
    "is_active": true,
    "created_at": "2026-04-01T00:00:00Z"
  }
]

Widget — Instalación

El widget de Conectachat es un chat embebible de ~5 KB gzipped, sin dependencias, compatible con cualquier sitio web o plataforma.

Instalación básica

Pega estas dos líneas antes del cierre de </body> en tu HTML:

<script src="https://cdn.conectaachat.com/widget.min.js"></script>
<script>
  ConectachatWidget.init({
    apiKey: 'cc_TU_API_KEY',
    agentName: 'Asistente'
  });
</script>

El widget aparecerá como un botón flotante en la esquina inferior derecha.

Widget — Opciones

Ejemplo completo

ConectachatWidget.init({
  apiKey:         'cc_TU_API_KEY',
  agentName:      'Soporte Técnico',
  primaryColor:   '#7c5cfc',
  position:       'bottom-right',
  welcomeMessage: '¡Hola! ¿En qué puedo ayudarte hoy?',
  placeholder:    'Escribe tu consulta...'
});

Widget — Métodos JS

Puedes controlar el widget programáticamente desde tu propio JavaScript:

ConectachatWidget.open();    // Abre el panel de chat
ConectachatWidget.close();   // Cierra el panel de chat
ConectachatWidget.destroy(); // Elimina el widget del DOM por completo

Instagram / Facebook

La forma más rápida es usar el flujo OAuth desde el dashboard: Agentes → [Tu Agente] → Canales → Instagram → Conectar con Meta. Se abrirá una ventana de autorización de Meta y podrás seleccionar tu página en segundos.

Configuración manual del webhook

Si prefieres configurar tu propia Meta App, registra esta URL en la sección Webhooks de tu app:

https://api.conectaachat.com/api/webhooks/meta

El Verify Token se genera automáticamente en el dashboard al conectar el canal. Suscríbete a los campos: messages y messaging_postbacks.

Slack

Conecta tu workspace desde el dashboard: Agentes → [Tu Agente] → Canales → Slack → Conectar.

URL de Event Subscriptions

En tu Slack App activa Event Subscriptions y pega esta URL:

https://api.conectaachat.com/api/webhooks/slack

Eventos requeridos

message.im      # Mensajes directos al bot
app_mention     # Menciones del bot en canales

OAuth scopes requeridos

chat:write        # Enviar mensajes
channels:history  # Leer mensajes de canales
app_mentions:read # Leer menciones
im:history        # Leer DMs

WhatsApp Business

WhatsApp Business API requiere acceso aprobado por Meta. Puedes obtenerlo directamente o a través de proveedores como 360Dialog o Twilio.

URL del webhook

https://api.conectaachat.com/api/webhooks/whatsapp

Configura el canal desde el dashboard en Agentes → Canales → WhatsApp Business → Conectar, pegando tu Phone Number ID y Access Token.

Webhooks — Seguridad

Todos los webhooks entrantes están protegidos con verificación HMAC. Conectachat valida la firma de cada request antes de procesarlo.

Verificación de Meta

Meta verifica la URL del webhook con un GET que incluye hub.challenge. Conectachat responde automáticamente con el challenge si el hub.verify_token coincide con el configurado en el dashboard.

Códigos de error

Todos los errores devuelven JSON con el formato:

{ "error": "Descripción del error" }

Soporte

¿Necesitas ayuda con la integración? Escríbenos a hola@conectaachat.com con el asunto "Soporte API" y el error que estás recibiendo.