API de ConvoChat

Autenticación

Crea una API key en /app/api-keys (menú «Desarrollo» → «API keys»), elige sus scopes y envíala en cada petición como cabecera Authorization: Bearer <token>. El token se muestra una sola vez al crearlo; cópialo entonces. Todas las respuestas son JSON.

curl -s https://convo.chat/api/v1/links \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Accept: application/json"

Scopes

Hay 19 scopes, agrupados por recurso. Cada API key concede solo los que elijas; si a un token le falta el scope de la ruta, esta responde 403 missing_ability.

Endpoints

Base: https://convo.chat/api/v1. Son 45 endpoints repartidos en 9 recursos; despliega el que te interese. Todas las listas se paginan con per_page (1–100, por defecto 15) y devuelven data, links y meta. Cada DELETE responde 204 sin cuerpo.

Creación y reutilización

POST /links no siempre crea. Si ya tienes un enlace corto con el mismo destination_url y el mismo domain_id, la API te devuelve ese enlace en lugar de crear otro: responde 200 (no 201) y añade "meta": {"reused": true}. En ese caso se descarta todo lo que mandaste —slug, password, status, fechas, click_limit, UTM, expiration_url— y el enlace conserva su configuración original. No consume cupo de tu plan.

Comprueba siempre meta.reused o el código de estado antes de dar por bueno un slug propio. Si necesitas dos enlaces distintos al mismo destino, usa un domain_id diferente.

HTTP/1.1 200 OK
{
  "data": { "id": "...", "slug": "slug-original", "destination_url": "https://ejemplo.com" },
  "meta": { "reused": true }
}

Enlaces que respaldan un QR

Los enlaces cortos que un código QR dinámico usa por dentro no se exponen en esta API: no aparecen en GET /links y cualquier GET, PATCH, DELETE o GET /links/{id}/stats sobre ellos responde 404 resource_not_found, aunque sean tuyos. Gestiónalos por /qr-codes o desde el panel. Tampoco cuenta con ellos si comparas totales con lo que ves en /app.

Límites

60 peticiones por minuto por cuenta, el mismo número para todos los planes de pago (el límite por plan todavía no está diferenciado). El contador es por usuario, no por API key: todas tus keys comparten el mismo cubo. Cada respuesta trae X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; al excederlo recibes 429 con Retry-After.

Errores

Todo error llega con esta forma. error.code es estable: enrútate por él, no por el mensaje. details solo aparece cuando hay contexto.

{
  "error": {
    "code": "validation_failed",
    "message": "Los datos proporcionados no son válidos.",
    "details": { "destination_url": ["El campo destination url es obligatorio."] }
  }
}

OAuth 2.0 para apps de terceros

Una API key sirve para tu propio código. Si construyes una app que actúa en nombre de otros usuarios de ConvoChat, registra una app OAuth en /app/oauth-apps y usa el flujo authorization_code con PKCE. Las redirect URIs deben ser https (http solo en 127.0.0.1 o localhost).

Con el access token llamas a los mismos 45 endpoints, con los mismos 19 scopes, cambiando la base a https://convo.chat/api/oauth/v1. Si no pides scopes, se conceden links:read y stats:read. Solo se acepta un bearer token real: una sesión de navegador no vale. El plan del usuario que autoriza es el que manda: si no incluye API, la llamada responde 403 api_access_denied.