HTTP API

Junebug’s HTTP API.

HTTP API endpoints

Channels

GET /channels/

List all channels

POST /channels/

Create a channel.

Parameters:
  • type (str) – channel type (e.g. smpp, twitter, xmpp)
  • label (str) – user-defined label
  • config (dict) – channel connection settings (a blob to pass to the channel type implementor)
  • metadata (dict) – user-defined data blob (used to record user-specified information about the channel, e.g. the channel owner)
  • status_url (str) – URL that junebug should send status events to. May be null if not desired. Not supported by every channel.
  • mo_url (str) – URL to call on incoming messages (mobile originated) from this channel. One or both of mo_url or amqp_queue must be specified. If both are specified, messages will be sent to both.
  • amqp_queue (str) – AMQP queue to repost messages onto for mobile originated messages. One or both of mo_url or amqp_queue must be specified. If both are specified, messages are sent to both. See AMQP integration for more details.
  • rate_limit_count (int) – Number of incoming messages to allow in a given time window. See rate_limit_window.
  • rate_limit_window (int) – Size of throttling window in seconds.
  • character_limit (int) – Maximum number of characters allowed per message.

Returns:

Parameters:
  • status (int) – HTTP status code (usually 201 on success).
  • code (str) – HTTP status string.
  • description (str) – Description of result (usually "channel created").
  • result (dict) – The channel created.
GET /channels/(channel_id: str)

Return the channel configuration and a nested status object.

The status object takes the following form:

Parameters:
  • status (str) – The worst case of each component’s status level. For example if the redis component’s status is degraded and the amqp component’s status is down, this field’s value will will be down.
  • components (dict) – An object showing the most recent status event for each component.
  • inbound_message_rate (float) – The inbound messages per second for the channel.
  • outbound_message_rate (float) – The outbound messages per second for the channel.
  • submitted_event_rate (float) – The submitted events per second for the channel.
  • rejected_event_rate (float) – The rejected events per second for the channel.
  • delivery_succeeded_rate (float) – The delivery succeeded events per second for the channel.
  • delivery_failed_rate (float) – The delivery failed events per second for the channel.
  • delivery_pending_rate (float) – The delivery pending events per second for the channel.

Example response:

{
  status: 200,
  code: "OK",
  description: "channel status",
  result: {
    id: "uuid-1234",
    type: "smpp",
    label: "An SMPP Transport",
    config: {
      system_id: "secret_id",
      password: "secret_password"
    },
    metadata: {
      owned_by: "user-5",
    },
    status_url: "http://example.com/user-5/status",
    mo_url: "http://example.com/user-5/mo",
    rate_limit_count: 500,
    rate_limit_window: 10,
    character_limit: null,
    status: {
       status: 'ok',
       components: {
          smpp: {
             component: 'smpp',
             channel_id: "channel-uuid-1234",
             status: 'ok',
             reasons: [],
             details: {}
          },
          amqp: {
             component: 'amqp',
             channel_id: "channel-uuid-1234",
             status: 'ok',
             reasons: [],
             details: {}
          }
      },
      inbound_message_rate: 1.75,
      outbound_message_rate: 7.11,
      submitted_event_rate: 6.2,
      rejected_event_rate: 2.13,
      delivery_succeeded_rate: 5.44,
      delivery_failed_rate: 1.27,
      delivery_pending_rate: 4.32
    }
  }
}
POST /channels/(channel_id: str)

Modify a channel’s configuration.

Accepts the same parameters as POST /channels/. Only the parameters provided are updated. Others retain their original values.

DELETE /channels/(channel_id: str)

Delete a channel.

POST /channels/(channel_id: str)/restart

Restart a channel.

Logs

GET /channels/(channel_id: str)/logs

Get the most recent logs for a specific channel.

Query Parameters:
 
  • n (int) – Optional. The number of logs to fetch. If not supplied, then the configured maximum number of logs are returned. If this number is greater than the configured maximum logs value, then only the configured maximum number of logs will be returned.

The response is a list of logs, with each log taking the following form:

Parameters:
  • logger (str) – The logger that created the log, usually the channel id.
  • level (int) – The level of the logs. Corresponds to the levels found in the python module logging.
  • timestamp (float) – Timestamp, in the format of seconds since the epoch.
  • message (str) – The message of the log.

In the case of an exception, there will be an exception object, with the following parameters:

Parameters:
  • class (str) – The class of the exception.
  • instance (str) – The specific instance of the exception.
  • stack (list) – A list of strings representing the traceback of the error.

Example Request:

GET /channels/123-456-7a90/logs?n=2 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

{
  status: 200,
  code: "OK",
  description: "Logs retrieved",
  result: [
      {
          logger: "123-456-7a90",
          level: 40,
          timestamp: 987654321.0,
          message: "Last log for the channel"
          exception: {
              class: "ValueError",
              instance: "ValueError("Bad value",)",
              stack: [
                  ...
              ]
          }
      },
      {
          logger: "123-456-7a90",
          level: 20,
          timestamp: 987654320.0,
          message: "Second last log for the channel"
      }
  ]
}

Messages

POST /channels/(channel_id: str)/messages/

Send an outbound (mobile terminated) message.

Parameters:
  • to (str) – the address (e.g. MSISDN) to send the message too. Should be omitted if reply_to is specified.
  • from (str) – the address the message is from. May be null if the channel only supports a single from address.
  • 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. Optional. Only one of to or reply_to may be specified. The default settings allow 10 minutes to reply to a message, after which an error will be returned.
  • event_url (str) – URL to call for status events (e.g. acknowledgements and delivery reports) related to this message. The default settings allow 2 days for events to arrive, after which they will no longer be forwarded.
  • priority (int) – Delivery priority from 1 to 5. Higher priority messages are delivered first. If omitted, priority is 1.
  • channel_data (dict) – Additional data that is passed to the channel to interpret. E.g. continue_session for USSD, direct_message or tweet for Twitter.

Example request:

{
  to: "+26612345678",
  from: "8110",
  reply_to: "uuid-1234",
  event_url: "http://example.com/events/msg-1234",
  content: "Hello world!",
  priority: 1,
  channel_data: {
    continue_session: true,
  }
}

Example response:

{
  status: 201,
  code: "created",
  description: "message submitted",
  result: {
    id: "message-uuid-1234"
  }
}
GET /channels/(channel_id: str)/messages/(msg_id: str)

Retrieve a message’s status.

Example response:

{
  status: 200,
  code: "OK",
  description: "message status",
  result: {
    id: "msg-uuid-1234",
    last_event_type: "ack",
    last_event_timestamp: "2015-06-15 13:00:00",
    events: [
        /* array of all events; formatted like events */
    ]
  }
}

Events

Events POSTed to the event_url specified in POST /channels/(channel_id:str)/messages/ have the following format:

POST /event/url
Parameters:
  • event_type (str) – The type of the event. See the list of event types below.
  • message_id (str) – The UUID of the message the event is for.
  • channel_id (str) – The UUID of the channel the event occurred for.
  • timestamp (str) – The timestamp at which the event occurred.
  • event_details (dict) – Details specific to the event type.

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 2 days; any further events will not be forwarded.

Request example:

{
  event_type: "submitted",
  message_id: "msg-uuid-1234",
  channel_id: "channel-uuid-5678",
  timestamp: "2015-06-15 13:00:00",
  event_details: {
     /* detail specific to the channel implementation. */
  }
}

Event types

Sent when the message is submitted to the provider:

  • submitted: message successfully sent to the provider.
  • rejected: message rejected by the channel.

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

  • delivery_succeeded: provider confirmed that the message was delivered.
  • delivery_failed: provider declared that message delivery failed.
  • delivery_pending: provider is still attempting to deliver the message.

Status events

Status events POSTed to the status_url specified in POST /channels/ have the following format:

POST /status/url
Parameters:
  • component (str) – The component relevant to this status event.
  • channel_id (str) – The UUID of the channel the status event occurred for.
  • status (str) – The status level this event was categorised under.
  • type (str) – A programmatically usable string value describing the reason for the status event.
  • message (str) – A human-readable string value describing the reason for the status event.
  • details (dict) – Details specific to this event intended to be used for debugging purposes. For example, if the event was related to a component establishing a connection, the host and port are possible fields.

Request Example:

{
   status: "down",
   component: "smpp",
   channel_id: "channel-uuid-5678",
   type: "connection_lost",
   message: "Connection lost",
   details: {}
}

Components

Each status event published by a channel describes a component used as part of the channel’s operation. For example, an smpp channel type will have a redis component describing its redis connection, an amqp component describing its amqp connection and an smpp component describing events specific to the SMPP protocol (for example, connections, binds, throttling).

Status levels

A status event can be categorised under one of the following levels:

  • ok: The component is operational.
  • degraded: The component is operational, but there is an issue which may affect the operation of the component. For example, the component may be throttled.
  • down: The component is not operational as a result of the issue described by the event.