Example RapidSMS handler for Formhub.

rapidsms_formhub_app.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# vim: ai ts=4 sts=4 et sw=4 nu

''' Example RapidSMS Handler for use with Formhub

    This handler will receive a message from RapidSMS and forward it to
    the Formhub SMS API.
    The Formhub SMS API will reply with a status for the submission and
    a text message for the end user.
    The handler will forward the message to the SMS sender.

    If the submission is accepted, an `id` is provided.

    Statuses:
        SMS_SUBMISSION_ACCEPTED
        SMS_API_ERROR
        SMS_PARSING_ERROR
        SMS_SUBMISSION_ACCEPTED
        SMS_SUBMISSION_REFUSED
        SMS_INTERNAL_ERROR

    This code is meant to be an example of querying the Formhub API.
    Please refer to formhub.org for extended documentation.

    Dependencies:
        requests (pip install requests)'''

import json
import logging as log

import requests
from rapidsms.apps.base import AppBase

# setting your formhub username is mandatory.
# it's the username of the owner of the target form.
FORMHUB_USERNAME = 'mberg'
# the `id_string` of the form to submit text submissions to.
# If set to None, the form-unaware endpoint will be called
# and message will be routed according to the `sms_keyword` inside the text.
FORMHUB_FORM = None

# Formhub endpoints (don't change)
FORMHUB_SMS_SUBMISSION = 'https://formhub.org/{username}/sms_submission' \
                         .format(username=FORMHUB_USERNAME,
                                 id_string=FORMHUB_FORM)
FORMHUB_SMS_SUBMISSION_FORM = 'https://formhub.org/{username}/forms/' \
                              '%(id_string)s/sms_submission' \
                              .format(username=FORMHUB_USERNAME,
                                      id_string=FORMHUB_FORM)


class App(AppBase):

    def handle(self, message):

        # selecting endpoint based on knwoledge of Form's id_string.
        url = FORMHUB_SMS_SUBMISSION if FORMHUB_FORM is None \
            else FORMHUB_SMS_SUBMISSION_FORM

        # sends the text message to Formhub and create a submission.
        req = requests.get(url, params={'identity': message.peer,
                                        'text': message.text})

        # raise an Exception if status not in 200/201
        req.raise_for_status()

        # retrieve formhub's response
        response = json.loads(req.content)

        if response.get('code') == 'SMS_SUBMISSION_ACCEPTED':
            # do something with the submission ID
            log.info(u"Submission %(id)s created by %(identity)s"
                     % {'id': response.get('id'), 'identity': message.peer})
        else:
            # the submission failed (it did not create a submission)
            log.debug(u"%(identity)s sent an erroneous submission -- %(text)s"
                      % {'identity': message.peer, 'text': message.text})

        message.respond(response.get('message'))

        return True