Crie um plugin

Um plugin é um endpoint HTTPS que recebe eventos assinados do RolChat, mais chamadas opcionais que ele faz de volta ao RolChat. Não há código para enviar nem ambiente de execução para hospedar dentro do RolChat.

1. Registre o plugin

Em Configurações → Plugins → Catálogo → Personalizado, ou pela 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
  }
}

A resposta contém o ID do plugin e o segredo de webhook, exibido uma única vez. Guarde-o: todo evento que o RolChat envia é assinado com ele, e todo evento que você envia ao RolChat também precisa ser.

2. Receba eventos do RolChat

O RolChat faz um POST para webhook_url_outbound quando algo muda:

Evento	Quando
chats.conversation.created	Uma conversa começa
crm.contact.created	Um contato é criado
crm.contact.updated	Um contato muda
tickets.ticket.created	Um ticket é criado
tickets.ticket.status_changed	Um ticket muda de status
marketing.meeting.booked	Uma reunião é agendada
marketing.meeting.cancelled	Uma reunião é cancelada

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

Verifique a assinatura, a validade e o nonce exatamente como descrito em Webhooks, responda 200 rapidamente e elimine duplicados pelo ID do evento. As famílias de eventos mais amplas disponíveis para assinaturas estão no catálogo de eventos.

3. Envie eventos ao RolChat

Faça um POST para o endpoint de entrada do seu plugin, assinado com o mesmo segredo:

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" }
  }
}

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

Evento de entrada	O que o RolChat faz
contact.data_updated	Armazena plugin_data no contato correspondente
company.data_updated	Armazena plugin_data na empresa correspondente
contact.created_external	Cria ou atualiza um contato
agent.unavailable	Executa a estratégia de indisponibilidade do formulário de agendamento (cancelar, reatribuir, oferecer um novo horário)
agent.available	Notifica o agente sobre reuniões pendentes

Correspondência. O RolChat procura o contato primeiro pelo e-mail e depois pelo external_id que o seu plugin armazenou antes. Se não encontrar, um lead é criado se sync_config.create_contacts estiver ativado; caso contrário, o evento é registrado como sem correspondência.

4. Onde os dados do plugin aparecem

Os cartões de contatos e empresas mostram uma seção com o nome do seu plugin e os campos que você enviou, somente leitura, com o horário da última atualização. Os mesmos dados são retornados pela API:

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

As condições de automação podem testar os dados de plugins, então uma regra pode encaminhar uma conversa conforme o plano do cliente no seu sistema.

5. API de gerenciamento

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. Manifesto

Um plugin publicado se declara em um manifesto: nome, categoria, os escopos que solicita, os eventos que assina, o formulário de configurações, allowed_source_ips opcional, recommended_rotation_days e o preço, se for pago. O manifesto alimenta a tela de conexão e a revisão feita antes de um plugin da comunidade ser listado.

Limites e boas práticas

• Corpo de entrada de até 5 MB; de saída, 1 MB por padrão.
• As chaves de API de plugins são limitadas a 300 requisições por minuto; os webhooks de entrada, a 120 por minuto por plugin.
• Falhas contínuas de entrega marcam um plugin como degradado; mais da metade das entregas falhando por uma hora pausa o plugin e notifica os administradores da conta.
• Nunca registre em log nem exiba o segredo de webhook. Faça a rotação se suspeitar de exposição; graças à janela de sobreposição, nada quebra.