This page is for developers who adapt the module to a theme or connect it with other code. Customer Messages is built on the Ka Extensions library: the module does not change OpenCart files, its changes are applied by the library (kamod overrides and .xml patches) and are rebuilt with Extensions > Modifications > Refresh.
Files
| Folder | Content |
|---|---|
admin/controller/extension/ka_extensions/ka_messages/ |
Admin pages: tickets, ticket, message dialogs, bans, attachments; controller/ holds overrides of OpenCart pages (menu, store settings). |
admin/controller/extension/ka_extensions/ka_messages.php |
Settings page, installation and the database structure. |
catalog/controller/extension/ka_extensions/ka_messages/ |
Customer pages (tickets, ticket, attachments), cron.php; controller/ holds overrides of account, order history, contact form and alert mail controllers. |
catalog/model/extension/ka_extensions/ka_messages/cron.php |
Import of emails from the mailbox. |
system/library/extension/ka_extensions/ka_messages/ |
Shared models (tickets, messages, attachments, emails), IMAP reader, ban list, image and attachment rules, HTML / Markdown conversion. |
admin/view/template/extension/ka_extensions/ka_messages/, catalog/view/theme/default/template/extension/ka_extensions/ka_messages/ |
Templates, including mail/ with the email templates. |
system/config/ka_messages.php |
The email signing key, created on installation. |
customer_verification, ka_messages_for_mv folders |
The bundled Customer Email Verification and Messages For Multivendor extensions. |
Database tables
| Table | Content |
|---|---|
ka_tickets |
Tickets: subject, status (O / C), answered flag, assigned administrator, ticket note, source, email verification. |
ka_ticket_customers |
Customers of every ticket. |
ka_ticket_messages |
Messages: ticket, author id and type (C customer, U admin user, V vendor), text, source message of a split. |
ka_ticket_attachments |
Attached files and images of messages. Files are in <storage>/ticket_attachments/<ticket_id>/<message_id>/. |
ka_ticket_message_emails |
Delivery status of message emails per recipient: S sent, F failed, L being sent, attempts, last error. |
ka_ticket_bans |
Ban rules. |
ka_user_settings |
Saved list filters of administrators. |
The installation also adds customer.customer_note and the email verification fields of the customer table.
Message format
Messages are stored in Markdown. The editor (Summernote) sends HTML, the module converts it to Markdown on saving and back to HTML with Parsedown for display and emails. Images are stored as  links to attachment records, never as URLs with session tokens.
Email templates
Email templates are Twig files named <template>_<language code>.twig in the mail/admin/ and mail/customer/ folders (mail/vendor/ for vendors), separately in the admin and catalog template folders. _en and _ru files are included; when the store has no file for the language of the recipient, the _en template is used (getTemplateForLanguage() of AModelEmails). The subjects "Ticket #N Was Assigned to You" and "Ticket #N has been closed" are in the language file extension/ka_extensions/ka_messages/mail.php. The templates get:
| Variable | Content |
|---|---|
reply_above_this_line |
The marker line; keep it at the top. |
ticket |
The ticket with ticket_id, subject, customers (list of customer records), author, email_verified. |
recipient |
The recipient: a customer record, an admin user record or a vendor record (firstname, lastname, email). |
message.body |
The message as HTML. |
attachments |
A list of name and url of attached files. |
Keep the marker in your templates, otherwise the quoted text is not removed from replies.
Linking of replies
Every email gets a Message-ID of the form <m{type}{message id}.{signature}@tickets.local>, plus In-Reply-To and References with the ids of the previous messages of the ticket. Incoming emails are matched by In-Reply-To first, then by References from the newest id. Ids with a wrong signature are ignored. The subject is never parsed.
Creating a ticket from your code
The contact form creates tickets with the system tickets model of the catalog. The same call can be used by other extensions:
$kamodel_tickets = $this->load->kamodel('extension/ka_extensions/ka_messages/system_tickets'); $ticket_id = $kamodel_tickets->addTicket([ 'customer_id' => $customer_id, 'subject' => 'Return request for order #15', 'body' => 'Text of the first message (Markdown)', 'source' => 'form', 'email_verified' => 1, ]);
The ticket gets the Default Assigned User, the administrator and the customer get the emails about the new ticket. To find or create a customer account for an email, use fetchCustomersFromEmails() of the extension/ka_extensions/ka_messages/cron model as the contact form does.
Custom themes
The customer templates are in the default theme folder. If your theme does not show the ticket pages correctly, copy the templates from catalog/view/theme/default/template/extension/ka_extensions/ka_messages/ to the same path in your theme and adjust the markup. The changes of the account, order history and contact pages are .twig.xml patches; if a patch does not find its place in your theme template, the link or button is not added.