Freeside:4:Documentation:ExternalMessaging
Contents
Creating the messaging service
The Freeside external messaging interface is a REST client. It communicates with the service by POSTing to specified URLs (which can be different for each kind of message, but need not be). The body of the POST is always a JSON object.
Messages are processed in two stages. At either stage the server can report failure by returning an HTTP failure status (non-200). The body of the HTTP response will be saved as the error message.
Prepare
Freeside POSTs a JSON object containing all of the same substitution variables available to internal message templates. See http://localhost/freeside/edit/msg_template/email.html for a list of these. The element names in the object are the same as the variable names, minus the '$' sigil. The messaging service must return a document containing the "prepared message": everything it needs to successfully send the message later. This should be a JSON document, though that's not yet enforced (as of September 2015).
At this stage the user might still decide not to send the message, so the messaging service shouldn't do anything irreversible yet.
Send
Freeside POSTs the prepared message verbatim. At this point the messaging service should deliver it to the customer.
On success, the body of the response message will be ignored.
Example
There's an example REST server in bin/msg_template_http-demo.pl, using Mojolicious. It shows how to take substitution variables, insert them into a body of text, and return a JSON object representing the message to be sent, and then (at the Send stage) how to take that object and turn it into an email message.
Configuring the message interface in Freeside
From the menu bar, open Configuration -> Miscellaneous -> Message templates. Click the link for External message interfaces, then Add a new interface.
Agent is which agent will have access to this interface (or "all" for it to be globally available). Interface name is a descriptive name for your use. Prepare URL and Send URL are the URLs to be POSTed to in the Prepare and Send stages, respectively. No variable substitution is performed on these. HTTP username and password are a login for Basic authentication. This is optional. Additional POST content is an optional JSON object (a complete object, including surrounding { } delimiters) to be included in the Prepare document. All the standard substitution variables will be added to it. If you don't specify one, you'll send an object containing only the standard variables.
