API para desarrolladores
Envía un mensaje directo con un solo POST.
Una API REST para tu CRM en el plan Business: contactos, conversaciones, negocios, tareas, campañas y mensajes en Telegram, X y la bandeja social. Autenticación Bearer, claves con permisos acotados, idempotencia, cabeceras de límite de peticiones y webhooks salientes. Sin necesidad de SDK.
- JSON sobre HTTPS
- Respuestas de baja latencia
- Fiable por diseño
Última actualización:
El mismo endpoint. Cuatro lenguajes.
Un único contrato JSON. Copia, pega y publica. La especificación OpenAPI completa documenta cada endpoint, cada error y cada payload de webhook.
curl -X POST https://api.pinlyx.com/v1/telegram/messages \ -H "Authorization: Bearer csk_live_***" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"accountId":7421,"username":"sarah_miller","text":"Te damos la bienvenida"}'Referencia completa y catálogo de errores en docs.pinlyx.com/api
Claves con permisos acotados. Mínimo privilegio por defecto.
Genera claves de API con permisos acotados: solo lectura para paneles de analítica, escritura para los envíos en producción y gestión para la automatización de operaciones. Rótalas sin interrupciones: durante el cambio, ambas claves conviven y nada se rompe.
Autenticación Bearer
Envía
Authorization: Bearer csk_live_…en cada petición. Las claves de producción y de prueba se distinguen a simple vista, así tus flujos en producción están a salvo.Permisos acotados
Asigna a cada clave solo los permisos que necesita. Una clave de panel filtrada nunca podrá enviar un mensaje.
Rotación sin interrupciones
Emite una clave nueva, despliégala y revoca la anterior. Ambas son válidas durante el periodo de transición, sin avalanchas de errores 401.
contacts:readLista, busca y lee contactos y sus conversaciones.telegram:readConsulta el estado de un mensaje de Telegram en cola.analytics:readObtén estadísticas de embudos, campañas y cuentas.telegram:sendPon en cola mensajes de Telegram desde tus propias cuentas.contacts:writeCrea, actualiza y etiqueta contactos.sequences:writeInscribe contactos en campañas, y pausa o reanuda su avance.webhooks:writeRegistra y rota los endpoints de webhook.
Un control de carga que te lo cuenta todo.
Con las claves de idempotencia, reintentar es seguro: el mismo mensaje nunca se envía dos veces. Las cabeceras de límite de peticiones avisan a tu cliente de que debe ir más despacio antes de que llegue un 429.
- X-RateLimit-Limit
- 60
- # peticiones por minuto y por clave
- X-RateLimit-Remaining
- 48
- # restantes en la ventana actual
- X-RateLimit-Reset
- 1778077380
- # hora Unix en la que se reinicia la ventana
- Retry-After
- 12
- # ante un 429, espera estos segundos
Claves de idempotencia
Envía
Idempotency-Keyen cada escritura. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta original en lugar de volver a enviar.Límites por clave
Cada clave de API admite 60 peticiones por minuto por defecto, y el límite se ajusta por clave. Después, los envíos de Telegram siguen el ritmo propio de la cuenta: 20 mensajes por hora y 10 segundos entre mensajes por defecto, con espera automática ante el flood-wait.
Catálogo de errores estable
Cada error devuelve un
Errorestable sobre el que puedes ramificar tu lógica, y unMessagelegible que puedes mostrar al usuario, con la misma estructura JSON en todos los endpoints.
Webhooks salientes para cada evento.
Recibe 31 eventos del CRM en tiempo real. Firmas HMAC-SHA256, reintentos automáticos con espera exponencial y un registro de entregas desde el que puedes reintentar cualquier envío.
- message.sent
- contact.created
- pipeline.stage_changed
- sequence.completed
- outreach.replied
- task.completed
- support.ticket.created
- subscription.changed
{ "event": "message.received", "id": "8c1f4b9e2d7a4c03b5e6f1a2", "deliveredAt": "2026-05-06T14:32:18Z", "channel": "telegram", "contactId": 8821, "counterparty": "@sarah_miller", "text": "Hola, ¿me puedes enviar la demo?"}const sig = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');if ('sha256=' + sig !== headers['x-webhook-signature']) return 401;Cuando quieras empezar
Construye con Pinlyx. En marcha en minutos.
Con el plan Business, crea una clave en el panel, pega un curl y verás cómo el mensaje entra en la cola. La referencia OpenAPI documenta cada endpoint y cada error.
- Incluido en el plan Business
- Claves creadas en el panel
- Webhooks firmados con HMAC