Δημιουργία plugin

Ένα plugin είναι ένα HTTPS endpoint που λαμβάνει υπογεγραμμένα συμβάντα από το RolChat, μαζί με προαιρετικές κλήσεις που κάνει πίσω προς το RolChat. Δεν υπάρχει κώδικας για ανέβασμα ούτε runtime για φιλοξενία μέσα στο RolChat.

1. Καταχωρίστε το plugin

Στις Ρυθμίσεις → Plugins → Κατάλογος → Προσαρμοσμένο ή με το 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
  }
}

Η απόκριση περιέχει το αναγνωριστικό του plugin και το μυστικό webhook, που εμφανίζεται μία φορά. Αποθηκεύστε το· κάθε συμβάν που στέλνει το RolChat υπογράφεται με αυτό, και το ίδιο πρέπει να ισχύει για κάθε συμβάν που στέλνετε εσείς στο RolChat.

2. Λήψη συμβάντων από το RolChat

Το RolChat στέλνει στο 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 ακριβώς όπως περιγράφεται στα Webhooks, απαντήστε γρήγορα 200 και αφαιρέστε διπλότυπα με βάση το αναγνωριστικό συμβάντος. Οι ευρύτερες οικογένειες συμβάντων που είναι διαθέσιμες για συνδρομές βρίσκονται στον κατάλογο συμβάντων.

3. Αποστολή συμβάντων στο RolChat

Στείλτε στο εισερχόμενο endpoint του plugin σας, υπογεγραμμένα με το ίδιο μυστικό:

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 αναζητά την επαφή πρώτα με βάση το email και μετά με βάση το external_id που αποθήκευσε νωρίτερα το plugin σας. Αν δεν βρεθεί: δημιουργείται υποψήφιος πελάτης αν είναι ενεργό το sync_config.create_contacts, διαφορετικά το συμβάν καταγράφεται ως μη αντιστοιχισμένο.

4. Πού εμφανίζονται τα δεδομένα του plugin

Οι κάρτες επαφών και εταιρειών δείχνουν μια ενότητα με το όνομα του plugin σας και τα πεδία που στείλατε, μόνο για ανάγνωση, με τον χρόνο της τελευταίας ενημέρωσης. Τα ίδια δεδομένα επιστρέφονται από το API:

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

Οι συνθήκες αυτοματισμών μπορούν να ελέγχουν δεδομένα plugin, οπότε ένας κανόνας μπορεί να δρομολογεί μια συνομιλία με βάση το πρόγραμμα του πελάτη στο σύστημά σας.

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

Ένα δημοσιευμένο plugin δηλώνει τον εαυτό του σε ένα manifest: όνομα, κατηγορία, τα scopes που ζητά, τα συμβάντα στα οποία εγγράφεται, τη φόρμα ρυθμίσεων, προαιρετικά allowed_source_ips, recommended_rotation_days και την τιμολόγησή του αν είναι επί πληρωμή. Το manifest καθορίζει την οθόνη σύνδεσης και τον έλεγχο πριν καταχωριστεί ένα plugin της κοινότητας.

Όρια και καλές πρακτικές

• Εισερχόμενο σώμα έως 5 MB· εξερχόμενο 1 MB από προεπιλογή.
• Τα κλειδιά API plugin περιορίζονται σε 300 αιτήματα το λεπτό· τα εισερχόμενα webhooks σε 120 το λεπτό ανά plugin.
• Οι παρατεταμένες αποτυχίες παράδοσης επισημαίνουν ένα plugin ως υποβαθμισμένο· αν αποτυγχάνουν περισσότερες από τις μισές για μία ώρα, το plugin τίθεται σε παύση και ειδοποιούνται οι admins του λογαριασμού.
• Μην καταγράφετε και μην επιστρέφετε ποτέ το μυστικό webhook. Εναλλάξτε το αν υποψιάζεστε έκθεση· το παράθυρο επικάλυψης σημαίνει ότι τίποτα δεν σπάει.