Todo lo que hace la app, también por API.

Necesitas dos cosas: una cuenta de Kontesta y una API key. La llave se crea desde la app, en Ajustes → Llaves de API, y hace falta permiso de administrador. No se puede crear una llave usando otra llave — es a propósito: evita que una llave filtrada se multiplique sola.

Al crearla eliges qué permisos lleva (ver Permisos y scopes). El secreto completo se muestra una sola vez: en nuestra base solo queda su hash, así que si lo pierdes no hay forma de recuperarlo, solo de rotarlo.

Manda la llave en la cabecera X-Api-Key. Si tu cliente HTTP te complica las cabeceras personalizadas, también se acepta como Authorization: Bearer — el prefijo ktk_ nos deja distinguirla de un token de sesión.

X-Api-Key: ktk_a1b2c3d4.tu-secreto-aqui

# o bien
Authorization: Bearer ktk_a1b2c3d4.tu-secreto-aqui

Para cambiar una llave sin cortar el servicio existe la rotación: te devuelve una llave nueva y deja la vieja funcionando durante una ventana de gracia (24 horas por omisión, hasta 7 días, o 0 para cortar de inmediato). Despliegas la nueva, verificas y la vieja muere sola.

Lista las conversaciones abiertas. Si esto responde 200, ya estás integrado: todo lo demás es cambiar la ruta y el cuerpo.

curl -s "https://api.kontesta.app/v1/conversations?status=open&limit=30" \
  -H "X-Api-Key: $KONTESTA_API_KEY"

Un 401 significa que la llave no llegó o no es válida. Un 403 significa que llegó bien pero le falta el permiso — no es lo mismo, y la diferencia te ahorra media hora de depuración.

Cada llave lleva una lista de permisos con la forma recurso:verbo — conversations:read, messages:send, leads:write. Cada endpoint exige el suyo, y la llave debe traerlo o la respuesta es 403.

La consecuencia práctica: dale a cada llave el mínimo que necesita. Una integración que solo publica leads desde tu sitio no necesita conversations:read, y si algún día se filtra, no leerá las conversaciones de nadie. Es más trabajo el primer día y menos daño el peor día.

Paginación

Todo listado responde con la misma forma: items (el arreglo) y nextCursor. Se pagina por cursor, no por número de página: pides limit (1 a 100, 30 por omisión) y devuelves el nextCursor en el parámetro cursor para la siguiente página; cuando viene nulo se acabó. Es un poco más incómodo que page=2, pero no se salta ni repite registros cuando entran datos nuevos mientras paginas — que en un inbox pasa todo el tiempo.

<?php
$cursor = null;

do {
    $params = ['status' => 'open', 'limit' => 100];
    if ($cursor !== null) {
        $params['cursor'] = $cursor;
    }

    $url = 'https://api.kontesta.app/v1/conversations?' . http_build_query($params);
    $pagina = json_decode(pedir($url), true);

    foreach ($pagina['items'] as $conversacion) {
        procesar($conversacion);
    }

    $cursor = $pagina['nextCursor'] ?? null;
} while ($cursor !== null);

Errores

Todos los errores traen la misma forma. El campo requestId es el que nos sirve para rastrear qué pasó: si nos escribes por un error, mándalo.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Scope insuficiente: la llave no concede [messages:send]",
  "requestId": "a4898ca6-b9ba-496b-a0bf-814ee17ad7f1",
  "timestamp": "2026-08-05T19:56:10.378Z",
  "path": "/v1/conversations/cmrh3l84d001yxqdd992h7uwa/messages"
}

Límites de peticiones

Ventana de un minuto, contada por cuenta, y con cubetas separadas para lectura (GET) y escritura (el resto). Al pasarte recibes 429.

El caso más común. Se envía dentro de una conversación existente: el número de destino y la línea de salida se derivan de ella, así que no los mandas tú y no hay forma de equivocar el mapeo.

curl -s -X POST \
  "https://api.kontesta.app/v1/conversations/cvs_abc123/messages" \
  -H "X-Api-Key: $KONTESTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"text","text":"Tu pedido va en camino."}'

En vez de preguntar cada minuto si hay algo nuevo, das de alta una URL tuya y te avisamos. Cada entrega es un POST con el evento en el cuerpo.

curl -s -X POST "https://api.kontesta.app/v1/webhooks" \
  -H "X-Api-Key: $KONTESTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-sistema.example.com/hooks/kontesta",
    "events": ["message.received", "lead.created"]
  }'

# La respuesta trae el secreto de firma. Se muestra una sola vez:
# { "id": "whk_...", "secret": "whsec_...", ... }

Al crear la suscripción te devolvemos un secreto que empieza con whsec_. Con él firmamos cada entrega, y ese es el único modo de saber que la petición viene de nosotros: la URL es pública, cualquiera puede llamarla.

Cabeceras de cada entrega

Verificar la firma

La firma es HMAC-SHA256 del texto {timestamp}.{cuerpo crudo} con tu secreto. Tres reglas que importan: usa el cuerpo tal como llegó (si lo parseas a objeto y lo vuelves a serializar, la firma ya no coincide), compara en tiempo constante, y rechaza lo que tenga más de 5 minutos para que nadie pueda reenviar una petición vieja.

<?php
function verificarFirma(
    string $cuerpoCrudo,
    ?string $cabecera,
    string $secreto,
    int $toleranciaSeg = 300
): bool {
    if ($cabecera === null) {
        return false;
    }

    // La cabecera viene como "t=1754413462,v1=9f86d0..."
    $t = null;
    $v1 = null;
    foreach (explode(',', $cabecera) as $parte) {
        $pos = strpos($parte, '=');
        if ($pos === false) {
            continue;
        }
        $clave = trim(substr($parte, 0, $pos));
        $valor = trim(substr($parte, $pos + 1));
        if ($clave === 't') {
            $t = $valor;
        } elseif ($clave === 'v1') {
            $v1 = $valor;
        }
    }

    if ($t === null || $v1 === null) {
        return false;
    }

    // Anti-reenvio: nada mas viejo que la tolerancia.
    if (abs(time() - (int) $t) > $toleranciaSeg) {
        return false;
    }

    $esperado = hash_hmac('sha256', $t . '.' . $cuerpoCrudo, $secreto);

    // hash_equals compara en tiempo constante. NUNCA usar ===.
    return hash_equals($esperado, $v1);
}

// El cuerpo CRUDO, sin parsear: si lo decodificas y lo vuelves a
// codificar, cambia un espacio y la firma ya no coincide.
$cuerpoCrudo = file_get_contents('php://input');
$cabecera    = $_SERVER['HTTP_X_KONTESTA_SIGNATURE'] ?? null;

if (!verificarFirma($cuerpoCrudo, $cabecera, getenv('KONTESTA_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}

$evento = json_decode($cuerpoCrudo, true);

// Responde 2xx rapido; el trabajo pesado va en cola.
http_response_code(200);

encolar($evento['id'], $evento['type'], $evento['data']);

Al suscribirte eliges cuáles te interesan. Todos llegan con el mismo sobre: id, type, apiVersion, tenantId, occurredAt y data. Con events: [] recibes todos los eventos, menos call.ended y call.recording_ready: esos hay que pedirlos por nombre.

Ejemplo: handoff.requested (traspaso a una persona)

Es el evento que engancha tu sistema cuando el bot suelta la conversación: el cliente pidió hablar con alguien, la pregunta cayó fuera de su base de conocimiento, quiere pagar o agendar, o una regla lo decidió. Viaja sin datos del contacto — ni nombre ni teléfono, solo identificadores, motivo y fechas; el detalle lo consultas por API con conversationId.

{
  "id": "evt_01J8...",
  "type": "handoff.requested",
  "apiVersion": "v1",
  "tenantId": "ten_...",
  "occurredAt": "2026-09-11T18:02:11.000Z",
  "data": {
    "conversationId": "cm...",
    "handoffId": "cm...",
    "channel": "WHATSAPP",
    "reason": "CUSTOMER_REQUEST",
    "requestedBy": "BOT",
    "requestedAt": "2026-09-11T18:02:11.000Z",
    "outsideHours": false,
    "assignedToId": "usr_...",
    "summaryNoteId": "cm..."
  }
}

// reason:      CUSTOMER_REQUEST | NO_KB_MATCH | MAX_TURNS | NEGATIVE_SENTIMENT |
//              PAYMENT_OR_BOOKING | PROVIDER_ERROR | META_AGENT_REQUEST | RULE | MANUAL | OTHER |
//              AUDIO_UNTRANSCRIBED
// requestedBy: BOT | META_AGENT | AUTOMATION | USER | API
// assignedToId / summaryNoteId pueden venir null (nadie disponible / sin nota todavía).

El mismo mecanismo funciona al revés. Si corres tu propio bot sobre nuestra API y no puede resolver, nos devuelve el hilo con POST /v1/conversations/{id}/handoff: el bot de Kontesta queda en pausa, una persona lo toma desde la bandeja con una nota de contexto y, cuando termina, regresa el hilo con /handoff/return. El historial vive en GET /v1/conversations/{id}/handoffs.

# Tu bot no puede resolver: devuélvenos el hilo para que lo tome una persona.
curl -s -X POST "https://api.kontesta.app/v1/conversations/cm.../handoff" \
  -H "X-Api-Key: $KONTESTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "PAYMENT_OR_BOOKING",
    "note": "Quiere pagar 2 sillas y agendar entrega el viernes",
    "notifyCustomer": true
  }'

# 201 → episodio nuevo · 200 + "alreadyPending": true → ya había uno pendiente (idempotente)
# 409 HANDOFF_CONVERSATION_CLOSED → la conversación no está abierta

# Cuando la persona termine, regresa el hilo al bot:
curl -s -X POST "https://api.kontesta.app/v1/conversations/cm.../handoff/return" \
  -H "X-Api-Key: $KONTESTA_API_KEY"

Los 392 endpoints que puedes llamar con una API key, con el permiso que exige cada uno. Esta lista se genera del código, no se escribe a mano.

El archivo OpenAPI

La misma superficie, con los cuerpos de petición y respuesta, está en /integracion/openapi.json (OpenAPI 3). Trae solo lo que una llave puede llamar. Con él puedes generar un cliente en tu lenguaje, por ejemplo con openapi-generator:

curl -sO https://kontesta.mx/integracion/openapi.json

# Python
openapi-generator-cli generate -i openapi.json -g python -o kontesta-python

# C#
openapi-generator-cli generate -i openapi.json -g csharp -o kontesta-csharp

Para probar a mano en Postman: Import, pega la URL del archivo y elige generar una colección. Los endpoints quedan agrupados por área; tu llave va en la autorización de la colección (tipo API Key, cabecera X-Api-Key).

Si trabajas en Node o TypeScript hay un cliente tipado que te ahorra armar las peticiones a mano y trae la verificación de webhooks ya resuelta. Cubre conversaciones, leads, pipelines, automatizaciones, etiquetas, plantillas, métricas, webhooks e integraciones.

import { Kontesta } from '@kontesta/sdk';

const k = new Kontesta({ apiKey: process.env.KONTESTA_API_KEY! });

// Una página
const { items, nextCursor } = await k.conversations.list({
  status: 'open',
  limit: 30,
});

// …o todas, sin escribir el bucle del cursor
for await (const c of k.conversations.iterate({ status: 'open' })) {
  console.log(c.id);
}

Para cualquier otro lenguaje no hace falta SDK: son peticiones HTTP con una cabecera, como los ejemplos de PHP, C# y Python de esta página. Si prefieres un cliente tipado en tu lenguaje, genéralo con el archivo OpenAPI.