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.

Qué se manda en cada petición

Los POST y PATCH reciben un objeto JSON (Content-Type: application/json). En un PATCH solo cambia lo que mandas. Un campo que no está en estas tablas se ignora: los de solo lectura que devuelve un GET, como id, short_url o clicks, no estorban si los devuelves en un PATCH.

POST https://convo.chat/api/v1/links
{
    "destination_url": "https://ejemplo.com/rebajas",
    "slug": "rebajas-otono",
    "utm": {
        "utm_source": "instagram",
        "utm_campaign": "otono"
    },
    "method": "splash",
    "splash_page_id": 12,
    "pixel_ids": [
        3,
        7
    ],
    "project_id": 5
}

PATCH https://convo.chat/api/v1/links/{id}
{
    "status": "paused",
    "ends_at": "2026-12-31T23:59:00-06:00"
}

POST https://convo.chat/api/v1/qr-codes
{
    "name": "Carta del restaurante",
    "content_type": "url",
    "content": {
        "url": "https://ejemplo.com/carta"
    },
    "design": {
        "foregroundColor": "#1F2937",
        "size": 600
    }
}

PATCH https://convo.chat/api/v1/qr-codes/{id}
{
    "content": {
        "url": "https://ejemplo.com/carta-invierno"
    }
}

POST https://convo.chat/api/v1/bio-pages
{
    "slug": "estudio-norte",
    "meta": {
        "title": "Estudio Norte"
    }
}

PATCH https://convo.chat/api/v1/bio-pages/{id}
{
    "status": "paused"
}

POST https://convo.chat/api/v1/domains
{
    "host": "links.tumarca.com",
    "not_found_url": "https://tumarca.com"
}

PATCH https://convo.chat/api/v1/domains/{id}
{
    "default_link_id": "01JA2B3C4D5E6F7G8H9J0K1M2N"
}

POST https://convo.chat/api/v1/projects
{
    "name": "Campaña de otoño",
    "color": "#FF5A36"
}

PATCH https://convo.chat/api/v1/projects/{id}
{
    "color": "#2563EB"
}

POST https://convo.chat/api/v1/pixels
{
    "name": "Meta de la tienda",
    "provider": "facebook",
    "pixel_id": "123456789012345"
}

PATCH https://convo.chat/api/v1/pixels/{id}
{
    "name": "Meta (tienda nueva)"
}

POST https://convo.chat/api/v1/splash-pages
{
    "name": "Aviso de salida",
    "title": "Vas a salir de nuestra web",
    "unlock_seconds": 5
}

PATCH https://convo.chat/api/v1/splash-pages/{id}
{
    "unlock_seconds": 3
}

POST https://convo.chat/api/v1/overlays
{
    "name": "Cupón de bienvenida",
    "type": "coupon",
    "config": {
        "headline": "10 % de descuento",
        "coupon_code": "HOLA10"
    }
}

PATCH https://convo.chat/api/v1/overlays/{id}
{
    "config": {
        "headline": "15 % de descuento",
        "coupon_code": "HOLA15"
    }
}

Tipos de contenido del QR

content_type dice qué lleva el código y content trae sus campos. Solo url es dinámico: el dibujo lleva una dirección corta y el destino se cambia sin reimprimir. Los que van a una página tuya —bio, evento, archivo, tarjeta— se mandan con link_id, el id de esa página. El resto lleva su contenido dentro del dibujo.

Diseño del QR

Las claves de design. Lo que no mandes al crear toma su valor por defecto. El color del código necesita un contraste de 4,5:1 con el fondo para que la cámara lo lea. El logotipo se sube desde el panel.

Parámetros y apertura de enlaces

POST /links y PATCH /links/{id} aceptan parameters, un objeto de hasta 20 pares de nombre y valor. Los nombres admiten letras ASCII, números y los signos ._~-, hasta 128 caracteres; los valores son texto de hasta 2048 caracteres, sin caracteres de control. Un valor vacío o null produce nombre=. No se aceptan objetos anidados ni los nombres reservados preview, signature, expires, password, gate, confirm. La precedencia es: consulta del destino, parámetros entrantes si forward_query está activo, parameters guardados y, al final, los cinco valores utm configurados. En un PATCH, omitir parameters conserva los valores; enviar null o un objeto vacío los elimina.

block_bots y social_breakout son booleanos y empiezan en false. El primero responde 403 a bots detectados, incluidos los rastreadores de vistas previas sociales, antes de contar una visita. Las vistas previas firmadas del titular siguen disponibles. El segundo añade ayuda para abrir el destino fuera de las redes sociales; con método directo muestra una página manual con los mismos metadatos para humanos y bots permitidos. Android ofrece un intento de apertura en Chrome para destinos HTTPS; copiar el enlace y continuar al destino siguen disponibles. La app y el dispositivo deciden si permiten abrir otro navegador. En un PATCH, omitir estos booleanos conserva su estado; enviar false los desactiva.

Creación y reutilización

POST /links no siempre crea. Si ya tienes un enlace corto igual al que pides y en servicio, la API te devuelve ese en lugar de crear otro: responde 200 (no 201), añade "meta": {"reused": true} y no gasta cupo de tu plan. Así, pedir dos veces el mismo enlace no te llena la lista de copias.

• Igual es que abre lo mismo: el mismo destination_url en el mismo domain_id, con las mismas utm y parameters, el mismo http_status y method, la misma página de espera u overlay y los mismos interruptores. Y sin reglas de destino —por país, dispositivo, idioma o reparto entre destinos, las que se ponen en el panel—: un enlace con reglas no abre lo mismo para todos y nunca se reutiliza. project_id y pixel_ids cuentan si los mandas.
• En servicio es activo, ya empezado, sin fecha de fin, sin tope de clics y sin contraseña. Uno pausado, vencido, agotado o programado no se reutiliza: se crea otro.
• Si tu petición trae password, starts_at, ends_at, click_limit o "status": "paused", pides un enlace propio y siempre se crea.
• Si mandas slug, cuenta: solo se reutiliza el enlace que ya tiene ese alias. Si tienes uno igual con otro alias, se crea uno nuevo con el tuyo; si el alias ya lo usa otro enlace que no se puede reutilizar, responde 422. Sin slug, recibes el que ya tienes, con el suyo. Para tener dos enlaces al mismo destino, pide otro alias o cambia algo que se note al abrirlo, como una utm_source por canal.
• Si el igual que te devolvería lo deshabilitó el equipo de ConvoChat o está en revisión, no se hace una copia: responde 409 duplicate_destination_unavailable, con details.id y details.state. Uno retirado que no es igual —en otro dominio o con otras utm— no impide crear.

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.

Repetir una petición sin duplicar

Si una petición se corta y no sabes si llegó, repítela con la misma cabecera Idempotency-Key: no se hace dos veces. Vale en todos los POST. Usa una clave distinta por operación —un UUID, por ejemplo—, de hasta 255 caracteres visibles.

• La misma clave con la misma petición devuelve la respuesta de la primera vez, con la cabecera Idempotent-Replayed: true, durante 24 horas.
• La misma clave con otra petición —otra ruta u otros datos— responde 422 idempotency_key_reused.
• Si la primera todavía no ha terminado, 409 idempotency_request_in_progress: espera un momento y repítela.
• Solo se guarda una respuesta correcta (2xx). Si la primera falló, repetirla con la misma clave lo vuelve a intentar.
• Cada credencial tiene sus propias claves: la misma clave desde otra API key u otra app es otra petición.

curl -s https://convo.chat/api/v1/links \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-1b7d-4f3a-9c2e-8d5b7a1e4c90" \
  -H "Content-Type: application/json" \
  -d '{"destination_url": "https://ejemplo.com/rebajas"}'

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). Es el techo de todas tus credenciales juntas —tus API keys y las apps que hayas autorizado—, así que crear más claves no da más cupo.

Si solo una credencial está usando la API, tiene el techo entero. Cuando hay varias a la vez, el minuto se reparte a partes iguales: cada una puede gastar como mucho el techo dividido entre las que están activas —con dos, 30 cada una; con tres, 20—. Así una integración que insiste se frena sola y no deja sin servicio a las demás. Cuenta como activa la credencial que hizo alguna petición en los últimos 60 segundos; la que deja de llamar libera su parte al cabo de ese tiempo. Si una credencial estaba sola y gastó el techo entero, la que llega después puede tener que esperar a que empiece el minuto siguiente; desde entonces cada una tiene su parte.

Cada respuesta trae X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset del límite que te frenará antes: el techo de la cuenta o, con varias credenciales activas, la parte de la tuya. Al pasarte recibes 429 rate_limit_exceeded con Retry-After, y details.scope dice cuál te frenó: account si fue el techo de la cuenta, credential si fue la parte de tu credencial, y entonces details.active_credentials dice entre cuántas se reparte.

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 destino 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, [::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.

• PKCE es obligatorio para todas las apps: manda code_challenge (el SHA-256 del code_verifier, en base64url sin relleno) con code_challenge_method=S256; plain no se acepta. Sin eso, la persona vuelve a tu app con error=invalid_request. Manda también state y compruébalo al volver.
• El token de acceso vale una hora (expires_in = 3600) y el de renovación, 60 días; cada renovación devuelve uno nuevo de 60 días y anula el anterior. Un token caducado o retirado responde 401 unauthenticated con WWW-Authenticate: Bearer error="invalid_token": renuévalo. Si la renovación responde invalid_grant, la persona tiene que volver a autorizar tu app.
• Las apps de móvil, escritorio o navegador se registran sin secreto. En el mismo equipo usa http://127.0.0.1:{puerto} o http://[::1]:{puerto}, y el puerto puede cambiar en cada arranque; con localhost el puerto tiene que ser exactamente el registrado.
• El sub del token es interno y opaco: el identificador de la persona es el public_id de /api/oauth/v1/user.
• Un token sin el permiso de la ruta responde 403 missing_ability con details.required_abilities, igual que una API key.
• Quien conectó tu app puede quitarle el acceso cuando quiera en Cuenta → Apps conectadas. Si añades una dirección de vuelta, la siguiente autorización vuelve a pedir consentimiento.

Avisos por webhook

Un aviso con el canal Webhook (en el panel: Cuenta → Notificaciones) hace un POST con un cuerpo JSON a tu dirección cada vez que ocurre uno de los eventos que elegiste. La dirección tiene que ser HTTPS en el puerto 443 y de un servidor público; no seguimos redirecciones. Responde con cualquier 2xx en menos de 8 segundos; si tienes que hacer algo largo, guárdalo y hazlo después.

Cabeceras

El cuerpo

Siempre el mismo sobre. id es el del evento: lo comparten todos los avisos que dispara ese evento. delivery_id es el de esta entrega y se repite si la reintentamos: deduplica por delivery_id. occurred_at va en UTC. data trae los datos del evento y sus claves dependen del tipo: puede ganar claves nuevas, así que ignora las que no conozcas.

{
    "id": "prueba:01K0KSKAN07AW2YNH65B4Y9B2M",
    "delivery_id": "01k0kskan07aw2ynh65b4y9b2m",
    "event": "test",
    "occurred_at": "2026-07-19T20:15:30.000000Z",
    "subject": {
        "type": "user",
        "id": 17
    },
    "data": {
        "title": "Notificación de prueba",
        "message": "Tu aviso de ConvoChat está configurado correctamente."
    }
}

Comprobar la firma

Con el secreto que pusiste en el aviso, calcula el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin tocar (los bytes que llegaron, no el JSON vuelto a escribir), y compáralo en tiempo constante con lo que va detrás de v1=. Rechaza los envíos cuya marca de tiempo tenga más de cinco minutos: así nadie puede repetirte uno viejo.

$marca  = $_SERVER['HTTP_X_CONVOCHAT_TIMESTAMP'];
$firma  = $_SERVER['HTTP_X_CONVOCHAT_SIGNATURE'];
$cuerpo = file_get_contents('php://input');

$esperada = 'v1=' . hash_hmac('sha256', $marca . '.' . $cuerpo, $secreto);

if (! hash_equals($esperada, $firma) || abs(time() - (int) $marca) > 300) {
    http_response_code(401);
    exit;
}

Para probar tu código: con el secreto un-secreto-de-ejemplo-de-al-menos-32-caracteres, la marca 1784492130 y este cuerpo, tal cual, en una sola línea:

{"id":"prueba:01K0KSKAN07AW2YNH65B4Y9B2M","delivery_id":"01k0kskan07aw2ynh65b4y9b2m","event":"test","occurred_at":"2026-07-19T20:15:30.000000Z","subject":{"type":"user","id":17},"data":{"title":"Notificación de prueba","message":"Tu aviso de ConvoChat está configurado correctamente."}}

la cabecera de la firma tiene que ser:

X-ConvoChat-Signature: v1=9fe1ecd01a52485861deb2e71d8bdf2b19e605a9da83260951acb6eb635c77fa

Reintentos y pausas

• Si no responde, tarda más de 8 segundos o contesta con un 5xx, 408 o 429, lo intentamos 4 veces en total, esperando 15 s, 60 s, 300 s entre uno y otro.
• Cualquier otro 4xx no se reintenta: esperar no lo arregla.
• Un 3xx tampoco: no seguimos redirecciones, así que tu dirección volvería a redirigir. Pega en el aviso la dirección final, la que queda después de redirigir.
• Tras 5 entregas seguidas que no llegan, pausamos el aviso y te lo decimos por correo y en el panel. En la pestaña «Entregas» del aviso ves cada envío y por qué falló.

Eventos

Cambios

Lo que cambia en la v1 y puede afectar a una integración que ya funciona se anota aquí, con su fecha.

6 de octubre de 2026

• link_id y block_id de GET /data-submissions, y default_link_id de GET /domains, pasan de número a texto: ahora son el id público de la página, del bloque o del enlace, el mismo que da el resto de la API. Antes eran ids internos que no se podían cruzar con nada. Al mandarlos —el filtro ?link_id, default_link_id en POST y PATCH /domains y content.link_id de un QR— vale el id público, y el número de antes se sigue aceptando.
• POST /links ya no te devuelve como reutilizado (200) un enlace que no está en servicio o que no es igual al que pides —otras utm, otro alias, reglas de destino—: crea otro (201). Si el igual lo retiró el equipo de ConvoChat, responde 409 duplicate_destination_unavailable. Lee «Creación y reutilización».
• Con OAuth, un token sin el permiso de la ruta responde 403 missing_ability con details.required_abilities, igual que una API key; antes era 403 forbidden.
• Con OAuth, el token de acceso vale una hora y el de renovación 60 días (antes, un año los dos), y PKCE con S256 es obligatorio para todas las apps, también las que tienen secreto.
• El límite por minuto se reparte entre las credenciales que lo usan a la vez (lee «Límites»). Con una sola credencial no cambia nada.
• PATCH /qr-codes/{id} cambia solo lo que mandas: antes, no mandar design lo devolvía a sus valores por defecto y no mandar project_id sacaba el QR de su proyecto.
• POST y PATCH /links aplican project_id, method, splash_page_id, overlay_id y pixel_ids, que antes se descartaban sin avisar, y GET los devuelve.

Nuevo ese día: la cabecera Idempotency-Key en todos los POST —si ya la mandabas, ahora se respeta, y una mal formada responde 400 invalid_idempotency_key—, GET /domains?include=shared, y content y design en los códigos QR.