Freeside:4:Documentation:ExternalMessaging

From Freeside
Revision as of 17:07, 30 August 2015 by Mark (talk | contribs) (Some basic docs for this feature)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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.