API para desarrolladores
Integra contactos, conversaciones, mensajes y webhooks con Ricky.
La API REST estable de Ricky usa https://getricky.ai/api/v1. Su contrato OpenAPI describe cada ruta, parámetro y respuesta.
Empieza
- Un administrador entra en Configuración → Organización → API para desarrolladores.
- Crea una clave con los permisos mínimos y una fecha de vencimiento. Copia el secreto cuando aparece: Ricky solo lo muestra una vez.
- Envía la clave como
Authorization: Bearer rky_live_…desde tu servidor. No la incluyas en un navegador ni en una URL.
curl 'https://getricky.ai/api/v1/contacts?page_size=20' \
-H 'Authorization: Bearer TU_CLAVE'La clave pertenece a una organización. El acceso termina al revocarla, vencerla o quitar al creador su permiso de administrar la organización. Puedes revocarla en la misma pantalla.
Recursos
| Recurso | Rutas | Permisos |
|---|---|---|
| Contactos | GET/POST /contacts, GET/PATCH /contacts/{id} | contacts:read, contacts:write |
| Conversaciones | GET /conversations, GET /conversations/{id}, PATCH /conversations/{id}/assignment, POST /conversations/{id}/close, POST /conversations/{id}/reopen | conversations:read, conversations:write |
| Mensajes | GET/POST /conversations/{id}/messages | conversations:read, messages:send |
| Catálogos | GET /members, GET /tags, GET /templates | members:read, tags:read, templates:read |
| Webhooks | GET/POST /webhooks, DELETE /webhooks/{id}, GET /webhooks/{id}/deliveries, POST /webhooks/{id}/deliveries/{deliveryId}/retry | webhooks:manage |
Todas las rutas están bajo /api/v1. Las respuestas usan JSON y los errores contienen error.code y error.message. Guarda X-Request-Id al pedir soporte.
Paginación, límites y reintentos
Las listas de contactos y conversaciones aceptan page_size de 1 a 100 y devuelven next_cursor. Usa ese cursor sin modificarlo en la siguiente solicitud. Las listas de miembros, etiquetas y plantillas devuelven el catálogo completo de la organización. Las entregas de un webhook muestran las 100 más recientes.
Cada clave admite 120 solicitudes por minuto. Una respuesta 429 incluye Retry-After. Las respuestas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos Unix).
Los cambios de contactos y conversaciones y el envío de mensajes requieren Idempotency-Key de 8 a 200 caracteres. Reutiliza la misma clave solo para reintentar exactamente el mismo método, URL y cuerpo. Una respuesta repetida incluye Idempotency-Replayed: true. Si una operación queda en estado incierto, Ricky responde 409 request_processing: consulta el recurso y contacta soporte con X-Request-Id antes de intentar una operación nueva. Crear y desactivar suscripciones de webhook y reintentar entregas no requieren esa cabecera.
El envío de mensajes devuelve 202 cuando Ricky acepta el trabajo. No significa que el proveedor lo entregó. Consulta la conversación para ver el estado posterior. Las restricciones del canal, incluida la ventana de WhatsApp, siguen vigentes.
Webhooks
Suscríbete a message.received, message.sent, conversation.opened, conversation.closed o conversation.assignment_changed. El destino debe ser HTTPS público. La creación devuelve signing_secret una vez. Guarda ese secreto en tu servidor.
Cada entrega contiene id, type, occurred_at, organization_id y data con id y conversation_id. Ricky envía X-Ricky-Delivery-Id, X-Ricky-Timestamp y X-Ricky-Signature. La firma es v1= seguido del HMAC SHA-256 hexadecimal de timestamp + "." + cuerpo JSON exacto, con el secreto del webhook como clave. Comprueba la firma con comparación de tiempo constante y rechaza marcas de tiempo con más de cinco minutos de diferencia.
Responde con cualquier estado 2xx en menos de diez segundos. Ricky reintenta respuestas fallidas hasta diez veces con espera creciente. Las entregas pueden repetirse: deduplica por X-Ricky-Delivery-Id. Consulta /webhooks/{id}/deliveries para ver el resultado y usa la ruta de retry para volver a intentar una entrega fallida. Desactivar una suscripción impide entregas pendientes y nuevas.