Crea un plugin

Un plugin es un endpoint HTTPS que recibe eventos firmados de RolChat, más las llamadas opcionales que hace de vuelta a RolChat. No hay código que subir ni entorno de ejecución que alojar dentro de RolChat.

1. Registra el plugin

En Configuración → Plugins → Catálogo → Personalizado, o con la API:

POST /api/v1/plugins
Authorization: Bearer rcp_…
X-Account-Id: <account uuid>

{
  "plugin_type": "custom",
  "name": "Acme back office",
  "api_key_external": "<key RolChat should use to call you, optional>",
  "webhook_url_outbound": "https://backoffice.acme.com/rolchat",
  "sync_config": {
    "enrich_contacts": true,
    "enrich_companies": true,
    "sync_agent_schedule": false,
    "create_contacts": false
  }
}

La respuesta contiene el ID del plugin y el secreto de webhook, que se muestra una vez. Guárdalo; cada evento que envía RolChat va firmado con él, y cada evento que envíes a RolChat también debe ir firmado.

2. Recibe eventos de RolChat

RolChat envía datos a webhook_url_outbound cuando algo cambia:

Evento	Cuándo
chats.conversation.created	Empieza una conversación
crm.contact.created	Se crea un contacto
crm.contact.updated	Cambia un contacto
tickets.ticket.created	Se crea un ticket
tickets.ticket.status_changed	Un ticket cambia de estado
marketing.meeting.booked	Se reserva una reunión
marketing.meeting.cancelled	Se cancela una reunión

{
  "event": "crm.contact.created",
  "account_id": "…",
  "plugin_id": "…",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": { … }
}

Verifica la firma, la vigencia y el nonce exactamente como se describe en Webhooks, responde 200 rápidamente y deduplica por ID de evento. Las familias de eventos más amplias disponibles para las suscripciones están en el catálogo de eventos.

3. Envía eventos a RolChat

Envía los datos al endpoint de entrada de tu plugin, firmados con el mismo secreto:

POST /api/v1/webhooks/plugin/{plugin_id}
Content-Type: application/json
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=…
X-RolChat-Nonce: nonce_01HK…

{
  "event": "contact.data_updated",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": {
    "external_id": "acme_user_123",
    "email": "user@company.com",
    "plugin_data": { "role": "Admin", "registered_at": "2024-03-15", "last_login": "2026-04-11" }
  }
}

Respuesta: { "received": true, "matched_contact_id": "…" }.

Evento entrante	Qué hace RolChat
contact.data_updated	Guarda plugin_data en el contacto coincidente
company.data_updated	Guarda plugin_data en la empresa coincidente
contact.created_external	Crea o actualiza un contacto
agent.unavailable	Ejecuta la estrategia de no disponibilidad del formulario de reserva (cancelar, reasignar, ofrecer una franja nueva)
agent.available	Avisa al agente de las reuniones pendientes

Asociación. RolChat busca el contacto primero por email y después por el external_id que tu plugin guardó antes. Si no lo encuentra, se crea un lead cuando sync_config.create_contacts está activado; si no, el evento se registra como no asociado.

4. Dónde aparecen los datos del plugin

Las fichas de contacto y de empresa muestran una sección con el nombre de tu plugin y los campos que enviaste, de solo lectura, con la hora de la última actualización. La API devuelve los mismos datos:

GET /api/v1/contacts/{id}
{
  "data": {
    "id": "…",
    "plugin_data": {
      "{plugin_id}": { "plugin_name": "Acme back office", "updated_at": "…", "data": { … } }
    }
  }
}

Las condiciones de automatización pueden evaluar los datos del plugin, así que una regla puede enrutar una conversación según el plan del cliente en tu sistema.

5. API de gestión

GET    /api/v1/plugins                      connected plugins
GET    /api/v1/plugins/catalog              catalogue
POST   /api/v1/plugins                      connect
GET    /api/v1/plugins/{id}                 details
PATCH  /api/v1/plugins/{id}                 settings
DELETE /api/v1/plugins/{id}                 remove
POST   /api/v1/plugins/{id}/activate        activate
POST   /api/v1/plugins/{id}/deactivate      pause
POST   /api/v1/plugins/{id}/test            test the external key
POST   /api/v1/plugins/{id}/webhook-secret/rotate    rotate with a 7-day overlap
POST   /api/v1/plugins/{id}/webhook-secret/revoke    revoke immediately
GET    /api/v1/plugins/{id}/events          event log (direction, status, type, dates, cursor)
GET    /api/v1/plugins/{id}/sync-schedule   schedule and last run
PATCH  /api/v1/plugins/{id}/sync-schedule   { enabled, cron, timezone }
POST   /api/v1/plugins/{id}/sync-schedule/trigger    run now (one per 5 minutes)

6. Manifiesto

Un plugin publicado se declara en un manifiesto: nombre, categoría, los ámbitos que solicita, los eventos a los que se suscribe, su formulario de ajustes, allowed_source_ips opcional, recommended_rotation_days y su precio si es de pago. El manifiesto determina la pantalla de conexión y la revisión previa a la publicación de un plugin de la comunidad.

Límites y buenas prácticas

• Cuerpo entrante de hasta 5 MB; saliente de 1 MB por defecto.
• Las claves de API de plugins están limitadas a 300 peticiones por minuto; los webhooks entrantes, a 120 por minuto por plugin.
• Los fallos de entrega continuados marcan un plugin como degradado; si más de la mitad fallan durante una hora, se pausa y se avisa a los administradores de la cuenta.
• Nunca registres ni muestres el secreto de webhook. Rótalo si sospechas que se ha expuesto; gracias a la ventana de solapamiento, nada se rompe.