Vumi Go’s HTTP API¶

The API allows for sending & receiving Vumi messages via HTTP. These messages are plain JSON strings. Three types of messages are available:

Inbound and outbound user messages (e.g. SMSes, USSD responses, Twitter messages)

Events (e.g. delivery reports, acknowledgements)

Metrics (values recorded at a specific time)

Inbound user messages and events can be received via streaming HTTP or can be pushed to a third party URL via HTTP POST. Outbound messages and metrics can be pushed to Vumi Go via HTTP PUT.

Each HTTP api is bound to a conversation which stores all of the messages sent and received. HTTP Basic auth is used for authentication, the username is the Vumi Go account key and the password is an access token that is stored in the conversation. In order to connect three keys are required:

The account key
The accesss token
The conversation key

Inbound and Outbound User Messages¶

This is the format for messages being sent to, or received from, a person.

User messages are JSON objects of the following format:

{
    "message_id": "59b37288d8d94e42ab804158bdbf53e5",
    "in_reply_to": null,
    "session_event": null,
    "to_addr": "1234",
    "to_addr_type": "msisdn",
    "from_addr": "+27761234567",
    "from_addr_type": "msisdn",
    "content": "This is an incoming SMS!",
    "transport_name": "smpp_transport",
    "transport_type": "sms",
    "transport_metadata": {
        // this is a dictionary containing
        // transport specific data
    },
    "helper_metadata": {
        // this is a dictionary containing
        // application specific data
    }
}

A reply to this message would put the value of the “message_id” in the “in_reply_to” field so as to link the two.

The from_addr_type and to_addr_type fields describe the type of address declared in from_addr and to_addr. The default for to_addr_type is msisdn, and the default for from_addr_type is null, which is used to mark that the type is unspecified. The other valid values are irc_nickname, twitter_handle, gtalk_id, jabber_id, mxit_id, and wechat_id.

The “session_event” field is used for transports that are session oriented, primarily USSD. This field will be either “null”, “new”, “resume” or “close”. There are no guarantees that these will be set for USSD as it depends on the networks whether or not these values are available. If replying to a message in USSD session then set the “session_event” to “resume” if you are expecting a reply back from the user or to “close” if the message you are sending is the last message and the session is to be closed.

The go-heroku application is an example app that uses the HTTP API to receive and send messages.

A Python client for the HTTP API is available at https://github.com/praekelt/go-http-api. It can be installed with pip install go-http.

Sending Messages¶

$ curl -X PUT \
       --user '<account-key>:<access-token>' \
       --data '{"in_reply_to": "59b37288d8d94e42ab804158bdbf53e5", \
                "to_addr": "+27761234567", \
                "to_addr_type": "msisdn", \
                "content": "This is an outgoing SMS!"}' \
       http://go.vumi.org/api/v1/go/http_api_nostream/<conversation-key>/messages.json \
       -vvv

The UI expects you to specify an access token. All requests to the API require you to use your account key as the username and the token as the password.

The response to the PUT request is the complete Vumi Go user message and includes the generated Vumi message_id which should be stored if you wish to be able to associate events with the message later.

If a message is sent to a recipient that has opted out, the response will be an HTTP 400 error, with the body detailing that the recipient has opted out. Messages sent as a reply will still go through to an opted out recipient. The following is an example response of the error returned by the API:

{
    "success": false,
    "reason": "Recipient with msisdn +12345 has opted out"
}

This behaviour can be overridden by setting the disable_optout flag in the account to True. Ask a Vumi Go admin if you need to have optouts disabled.

Receiving User Messages¶

Vumi Go will forward any inbound messages to your application via an HTTP POST. Please specify the URL in the Go UI. You can include a username and password in the URL and use HTTPS if you require authentication.

There is a separate URL for receiving events.

Events¶

This is the format for events. Each event is associated with an outbound user message.

Events are JSON messages with the following format:

{
    "message_type": "event",
    "event_id": "b04ec322fc1c4819bc3f28e6e0c69de6",
    "event_type": "ack",
    "user_message_id": "60c48289d8d94e42ab804159acce42d4",
    "helper_metadata": {
        // this is a dictionary containing
        // application specific data
    },
    "timestamp": "2014-10-28 16:19:37.485612",
    "sent_message_id": "external-id",
}

The event_id unique id for this event.

The user_message_id is the id of the outbound message the event is for (this should be returned to you when you post the message to the HTTP API).

The event_type is the type of event and can be either ack, nack or delivery_report.

An ack indicates that the outbound message was succesfully sent to a third party (e.g. a cellphone network operator) for sending. A nack indicates that the message was not successfully sent to a third party and should be resent. The reason the message could not be sent will be given in the nack_reason field. Every outbound message should receive either an ack or a nack event.

A delivery_report indicates whether a message has successfully reached it’s final destination (e.g. a cellphone). Delivery reports are only available for some SMS channels. The delivery status will be given in the delivery_status field and can be one of pending (SMS is still waiting to be delivered to the cellphone), failed (the cellphone operator has given up attempting to deliver the SMS) or delivered (the SMS was successfully delivered to the cellphone).

Note

The meaning of delivery statuses can vary subtly between cellphone operators and should not be relied upon without careful testing of your specific use case.

Receiving Events¶

Vumi Go will forward any events to your application via an HTTP POST. Please specify the URL in the Go UI. You can include a username and password in the URL and use HTTPS if you require authentication.

This is a separate URL to the one for receiving user messages.

Publishing Metrics¶

You are able to publish metrics to Vumi Go via the HTTP APIs metrics endpoint. These metrics are able to be displayed in the Vumi GO UI using the dashboards.

How these dashboards are configured is explained in Vumi Go Dashboards.

PUT http://go.vumi.org/api/v1/go/http_api_nostream/<conversation-key>/metrics.json

An example using curl from the commandline:

$ curl -X PUT \
    --user '<account-key>:<access-token>' \
    --data '[["total_pings", 1200, "MAX"]]' \
    https://go.vumi.org/api/v1/go/http_api_nostream/<conversation-key>/metrics.json \
    -vvv