Note: Available since ISL Pronto module version 2.1.5.
ISL Pronto supports filtering of chat through the use of external commands. This can be configured under the 'External command for processing chat lines' option. The format is the same as used for configuring the conference proxy external authenticator. This setting is available per domain, and when configured conference proxy will invoke the command and communicate with the resulting process through standard input and output. It is advisable that the process be designed as a persistent process, so that it does not need to be invoked for every line of chat.
External Process Protocol
ISL Conference Proxy will communicate with the external process through standard input and output by sending utf-8 encoded text lines, that are in the URL parameter format. Each request will contain at least the 'cmd' keyword, which specifies the request command. There are two commands currently implemented:
filter
The filter command is specified by the 'cmd=filter' text. It always contains the 'id' key-value pair aswell. Which identifies the request, so that the response can be correctly parsed. This id must be returned in the response to the command. The line will also contain the 'chat' key-value pair, which has the chat line in the value field. If the chat was entered by a supporter, the key 'supporter' will have the value 1.
Example of filter requests:
cmd=filter&id=12345&chat=Tessting&supporter=1
The filter command will anticipate a response from the external process. The response must be URL(utf8) encoded. And must contain the 'result' key-value pair with the 'ok' value being a success. If nothing else is given, then the chat line is not changed. There are two ways to filter the chat message, by giving two results:
- chat_filtered : specifies that the original message was filtered (either for spellchecking errors, or profanity, etc...). It will replace the original message as the new original and will make the real original unavailable for future use.
- chat_translated: specifies that the original message( or the filtered one, if chat_filtered is now the original ) has been translated. This will replace the shown message, but the original message is kept intact, and can also be seen.
Example of a response to above filter request (with text repaired, and also translated to Slovenian langauge):
result=ok&id=12345&chat_filtered=Testing&chat_translated=Testiranje
exit
The exit command is specified by the 'cmd=exit' text. It does not contain any other information. And is a simple request for the external process to finish and quit.
Extra parameters
You can configure the conference proxy to send extra parameters to the external script. It is configured as a list of semi-colon separated key-value pairs. There are certain keywords you can use, that will be replaced at runtime for each chat message sent.
{{custom}} - will be replaced with the current customization used in this chat
{{chatsid}} - will be replaced with a session id for this chat
Example configuration:
chat_id={{chatsid}};customization={{custom}};static_argument=test;
The above example would add, chat_id, customization, and static_argument keys as cgi parameters to the server request.
Error handling
The ISL Conference Proxy will send each filter request to the process and wait for response for at most 5 seconds of time. If the process should exit unexpectedly or crash, the process will be restarted and the request repeated in the new process for at most 5 times for each chat line. If all fails, the chat line will be sent to chat unchanged.