Turn Channels API (EXPERIMENTAL: DO NOT USE IN PRODUCTION)

This application provides bidirectional messaging over HTTP, intended for integration with Turn’s Channels API.

Currently this only supports text message types. A future iteration will support other types.

Configuration

The application has the following configuration options:

connector_name: str

The name of the AMQP queue to publish outbound message on, and to consume inbound messages and events from. Required.

http_bind: str

The address to bind the HTTP server to. Required.

vumi_api_path: str

The base URL path for outbound message HTTP requests. Outbound message requests must be POSTed to <base_url_path>/messages. Defaults to an empty string.

turn_api_url: str

The base URL path for requests to Turn. Defaults to an empty string.

default_from_addr: str

The default from address to use for outbound messages. Required.

auth_token: str

The authorization token to use for requests to Turn. Required.

turn_hmac_secret: str

The secret key that Turn uses to sign its requests to us. Required.

request_timeout: float

Maximum time allowed (in seconds) for outbound message request handling. Defaults to 240 seconds.

mo_message_url_timeout: float

Maximum time allowed (in seconds) for inbound message HTTP requests. Defaults to 10 seconds.

event_url_timeout: float

Maximum time allowed (in seconds) for event HTTP requests. Defaults to 10 seconds.

transport_type: str

The transport_type to use for non-reply outbound messages. Defaults to sms.

message_cache_class: str

The message cache class to use for storing inbound messages. Defaults to MemoryMessageCache.

message_cache_config: dict

The configuration for the message cache. Defaults to an empty dictionary.

max_retries: int

The maximum number of retries to attempt for outbound message requests. Defaults to 3.

retry_delay_exponent: int

The exponent to use for retry delays. Defaults to 2.

retry_delay_base: int

The base to use for retry delays. Defaults to 2.

How it works

The application worker listens on HTTP for outbound messages from Turn and forwards them over AMQP to a router or transport. Inbound messages and events are forwarded to Turn over HTTP.

Outbound message API

When Turn needs to submit a message to a user, it will send a POST request to the configured URL.

For more information see the Turn Channels API documentation.

POST <base_url_path>/messages

Send an outbound (mobile terminated) message.

Request JSON Object:

• to (str) – The address (e.g. MSISDN) to send the message to.

• from (str) – The address the message is from. May be null if default_from_addr is configured.

• reply_to (str) – The uuid of the message being replied to if this is a response to a previous message. Important for session-based transports like USSD. Turn doesn’t supply a reply to address, so we plan to infer it based on the last inbound message. Optional.

• turn (dict) – The Turn message to send. Contains the message content. Required.

Example request:

{
  "to": "+26612345678",
  "from": "8110",
  "turn": {"type": "text", "text": {"body": "Hello world!"}},
}

Example response:

{
  "messages": [{"id": "message-uuid-5678"}]
}

Inbound message API

Inbound messages that are POSTed to turn_api_url/messages have the following format:

POST /<turn_api_url>/messages

Request JSON Object:

• contact (dict) – Information about the contact who sent the message.

• contact.id (str) – The Turn contact ID, which is an MSISDN.

• contact.profile (dict) – The contact’s profile information.

• contact.profile.name (str) – The contact’s name.

• message (dict) – The message received from the user.

• message.type (str) – The type of message. Currently only text is supported.

• message.text (dict) – Required when message type is text.

• message.text.body (str) – The text content of the message.

• message.from (str) – The user ID as an MSISDN. A Channel can respond to a user using this ID.

• message.id (str) – The ID for the message that was received by the Channel.

• message.timestamp (int) – Unix timestamp indicating when the message was received from the user.

Example response:

{
    "contact": {
        "id": "+26612345678",
        "profile": {
            "name": "John Doe"
        }
    },
    "message": {
        "type": "text",
        "text": {
            "body": "Hello world!"
        },
        "from": "+26612345678",
        "id": "message-uuid-5678",
        "timestamp": "1628345678"
    }
}

Event API

Events POSTed to turn_api_url/statuses have the following format:

POST /<turn_api_url>/statuses

Request JSON Object:

• user_message_id (str) – The UUID of the message the event is for.

• timestamp (str) – The timestamp at which the event occurred.

• status (str) – The status of the event. One of: sent, delivered.

Events are posted to the message’s event_url after the message is submitted to the provider, and when delivery reports are received. The default settings allow events to arrive for up to 24 hours; any further events will not be forwarded.

Request example:

{
  "user_message_id": "msg-uuid-1234",
  "timestamp": "2015-06-15 13:00:00",
  "status": "sent"
}

Event types

Sent when the message is submitted to the provider:

• sent: message successfully sent to the provider.

Sent later when (or if) delivery reports are received:

• delivered: provider confirmed that the message was delivered.

In the case where the delivery fails, Turn does not currently accept a failed status, so we send a sent event.

Turn state caches

A in-memory cache that stores the last inbound message for each user. This is used to link outgoing messages to incoming messages, which is required for USSD flows.

In memory state cache

See Message Caches for more information.