Създаване на плъгин

Плъгинът е HTTPS крайна точка, която получава подписани събития от RolChat, плюс незадължителни извиквания, които тя прави обратно към RolChat. Няма код за качване и няма среда за изпълнение, която да се хоства в RolChat.

1. Регистрирайте плъгина

В Настройки → Плъгини → Каталог → Персонализиран или чрез 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
  }
}

Отговорът съдържа ID на плъгина и тайната за уебхука, която се показва веднъж. Запазете я; всяко събитие, което RolChat изпраща, е подписано с нея, и всяко събитие, което изпращате към RolChat, също трябва да бъде.

2. Получаване на събития от RolChat

RolChat изпраща POST заявка към webhook_url_outbound, когато нещо се промени:

Събитие	Кога
chats.conversation.created	Започва разговор
crm.contact.created	Създаден е контакт
crm.contact.updated	Контакт е променен
tickets.ticket.created	Създаден е тикет
tickets.ticket.status_changed	Тикет сменя статуса си
marketing.meeting.booked	Резервирана е среща
marketing.meeting.cancelled	Среща е отменена

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

Проверявайте подписа, актуалността и nonce точно както е описано в Уебхукове, отговаряйте бързо с 200 и премахвайте дубликатите по ID на събитието. По-широките семейства събития, достъпни за абонаменти, са в каталога със събития.

3. Изпращане на събития към RolChat

Изпращайте POST заявки към входящата крайна точка на плъгина, подписани със същата тайна:

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

Отговор: { "received": true, "matched_contact_id": "…" }.

Входящо събитие	Какво прави RolChat
contact.data_updated	Съхранява plugin_data в съответния контакт
company.data_updated	Съхранява plugin_data в съответната фирма
contact.created_external	Създава или обновява контакт
agent.unavailable	Изпълнява стратегията за неналичност на формуляра за резервация (отмяна, преразпределяне, предлагане на нов час)
agent.available	Уведомява агента за предстоящи срещи

Съпоставяне. RolChat търси контакта първо по имейл, после по external_id, който плъгинът ви е съхранил по-рано. Ако не бъде намерен: създава се лийд, ако sync_config.create_contacts е включено, иначе събитието се записва като несъпоставено.

4. Къде се показват данните на плъгина

Картите на контактите и фирмите показват раздел с името на вашия плъгин и изпратените от вас полета, само за четене, с времето на последното обновяване. Същите данни се връщат от API:

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

Условията на автоматизацията могат да проверяват данните на плъгина, така че правило да насочи разговор според плана на клиента във вашата система.

5. API за управление

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. Манифест

Публикуваният плъгин се описва в манифест: име, категория, исканите обхвати, събитията, за които се абонира, формулярът за настройки, незадължителните allowed_source_ips и recommended_rotation_days, както и цената, ако е платен. Манифестът задава екрана за свързване и прегледа, преди плъгин от общността да бъде включен в каталога.

Лимити и добри практики

• Входящо тяло до 5 MB; изходящо по подразбиране 1 MB.
• API ключовете на плъгини са ограничени до 300 заявки на минута; входящите уебхукове до 120 на минута за плъгин.
• Продължителните неуспешни доставки маркират плъгина като влошен; ако повече от половината се провалят за един час, той се спира временно и администраторите на акаунта получават известие.
• Никога не записвайте в лога и не връщайте тайната за уебхука. Сменете я, ако подозирате изтичане; периодът на застъпване гарантира, че нищо няма да спре да работи.