Backends ======== A backend is what is responsible for sending the actual messages. A backend implements a "protocol" like email or SMS. Multiple backends might implement the same protocol, so you might have a backend that sends email via SMTP, and another one that uses the mailgun API. The important thing is that all the backends implementing a specific protocol must accept the same form of addresses. Most of these backends require extra dependencies that are not required for the base package. The specific extras are listed in the documentation, and you can mix/match them. For example:: # adds dependencies for markdown email, xmpp, twitter and the twilio # backends pip3 install django-vox[xmpp,markdown,twitter,twilio] In order to add or remove backends, you need to set the ``DJANGO_VOX_BACKENDS`` setting in your projects ``settings.py`` file. The setting is a list of class names for backends that are in-use/enabled. If not set, the default is (assuming you have the required dependencies):: DJANGO_VOX_BACKENDS = ( # disabled by default # 'django_vox.backends.activity.Backend', 'django_vox.backends.html_email.Backend', 'django_vox.backends.markdown_email.Backend', 'django_vox.backends.postmark_email.Backend', 'django_vox.backends.template_email.Backend', 'django_vox.backends.twilio.Backend', 'django_vox.backends.twitter.Backend', 'django_vox.backends.slack.Backend', 'django_vox.backends.json_webhook.Backend', 'django_vox.backends.xmpp.Backend', ) Django-vox provides a few built-in backends. Here's how to set them up and use them. Activity Backend ---------------- Protocol ``activity`` Class ``django_vox.backends.activity.Backend`` This is the backend for Activity Streams support. Setup is covered on the :doc:`activities` page. Email Backends -------------- Protocol ``email`` These backends are a wrapper around Django's internal mailing system. As such, it uses all of the built-in email settings including ``DEFAULT_FROM_EMAIL``, and everything that starts with ``EMAIL`` in the standard `django settings`_. There are 3 backends included: * One that uses HTML (and converts it to text for you) * One that uses Markdown (and coverts it to HTML for you) * One that uses Django template blocks to specify both HTML & text (not recommended) HTML Email Backend ~~~~~~~~~~~~~~~~~~ Class ``django_vox.backends.html_email.Backend`` When using this, the content of your template will have to be HTML. If you don't, it will be HTML anyways, but it will look real bad, and the god will frown on you. The backend automatically uses a library to convert the HTML into plain-text, so that there is a text version of the email, and so that the spam filters think better of you. Incidentally, the subject field is not HTML formatted. Markdown Email Backend ~~~~~~~~~~~~~~~~~~~~~~ Class ``django_vox.backends.markdown_email.Backend`` Extra ``[markdown]`` This backend has you specify the content of your templates with markdown. While markdown doesn't give you quite the flexibility as HTML, it's a bit more intuitive. Template-based Email Backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Class ``django_vox.backends.template_email.Backend`` This backend isn't recommended because it's probably too confusing to be wroth it. However, if you really need to tailor-make your emails, it's a solution that you can make work. Writing notification templates for emails are a little more complicated than they are for the other backends, because emails can have multiple parts to them (subject, text, and html). The basic form looks like this:: {% block subject %}Email Subject{% endblock %} {% block text_body %}Text body of email{% endblock %} {% block html_body %}HTML body of email{% endblock %} Postmark Templates ------------------ Class ``django_vox.backends.postmark_email.Backend`` This backend requires one config setting: ``DJANGO_VOX_POSTMARK_TOKEN``. It should be, unsurprisingly, your token for interacting with the postmark API. When using this backend, the 'Subject' field refers to Postmark's "template alias" and the template content should look something like this:: parameter_one: {{ content.attribute }} parameter_two: {{ recipient.name }} Twilio ------ Protocol ``sms`` Class ``django_vox.backends.twilio.Backend`` Extra ``[twilio]`` The twilio backend uses Twilio's python library. It depends on 3 settings, all of which needs to be set for proper functioning. ================================= =============================== ``DJANGO_VOX_TWILIO_ACCOUNT_SID`` Twilio account ID ``DJANGO_VOX_TWILIO_AUTH_TOKEN`` Twilio authentication token ``DJANGO_VOX_TWILIO_FROM_NUMBER`` Phone # to send Twilio SMS from ================================= =============================== Twitter ------- Protocol ``twitter`` Class ``django_vox.backends.twitter.Backend`` Extra ``[twitter]`` The twitter backend allows you to post updates to twitter and (with the right permissions), send direct messages to your followers. In order to set it up, you first need to create a twitter application. The `python-twitter docs`_ explain the process well. Note that you can ignore callback URL, and you'll want to set the name, description, and website fields to the name, description, and website of your application. Once you're done that, you may want to turn on "Read, Write and Access direct messages" in the "Permissions" tab. Then generate/regenerate your access token and secret. Once you're done that, you'll want to set the following values in your settings.py file: ====================================== ============================ ``DJANGO_VOX_TWITTER_CONSUMER_KEY`` Consumer Key (API Key) ``DJANGO_VOX_TWITTER_CONSUMER_SECRET`` Consumer Secret (API Secret) ``DJANGO_VOX_TWITTER_TOKEN_KEY`` Access Token ``DJANGO_VOX_TWITTER_TOKEN_SECRET`` Access Token Secret ====================================== ============================ .. note:: In order to post a message to your wall, make a site contact with the the twitter protocol and a *blank* address. In order to send a direct message, you'll need a address that equals your user's twitter handle (not including the "@" prefix). Webhook (JSON) -------------- Protocol ``json-webhook`` Class ``django_vox.backends.json_webhook.Backend`` This backend post JSON-formatted data to webhook. It's useful for implementing generic webhooks or integrating with systems like Huginn or Zapier. The way you specify parameters is the same as with the Postmark backend:: parameter_one: {{ content.attribute }} parameter_two: Hello World This will translate into:: {'parameter_one': '', 'parameter_two': 'Hello World'} Webhook (Slack) --------------- Protocol ``slack-webhook`` Class ``django_vox.backends.slack.Backend`` This backend requires no configuration in django, all of the configuration is essentially part of the addresses used in the protocol. For setting up slack-webhook addresses, see the documentation on :doc:`protocols `. XMPP ------- Protocol ``xmpp`` Class ``django_vox.backends.xmpp.Backend`` Extra ``[xmpp]`` This backends lets you send messages over xmpp to other xmpp users. It's pretty straightforward; however, it's also pretty slow right now, so don't use it unless your also doing notifications in the background. To set this up, you need to have the XMPP address and password in your settings. Here's the relevant settings. ============================ ============ ``DJANGO_VOX_XMPP_JID`` XMPP address ``DJANGO_VOX_XMPP_PASSWORD`` Password ============================ ============ .. _django settings: https://docs.djangoproject.com/en/1.11/ref/settings/ .. _python-twitter docs: https://python-twitter.readthedocs.io/en/latest/getting_started.html