API - dwilkie/nuntium GitHub Wiki

= Public API =

== Libraries ==

There are some in-progress libraries for accessing this API in several languages:

== Authentication ==

none: no authentication is required
account: HTTP Basic Auth with username "account_name" and account's password
application: HTTP Basic Auth with username "account_name/application_name" and application's password
account and application: both account and application authentication are supported

== Carriers ==

=== List all carriers ===

{{{HTTP GET /api/carriers.{xml|json}?country_id=CC(C)}}}

//Authentication: none//

List of carriers with their GUIDs for a given country. The country code can be the iso 2 or 3 letters. If no country code is given, all carriers are listed.

Examples

Request:

{{{HTTP GET /api/carriers.xml?country_code=ar}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!xml

}}}

Request:

{{{HTTP GET /api/carriers.json?country_code=ar}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!js [{"name":"Personal","guid":"c09dc81a-2f0d-4332-9459-ab49e6690908","country_iso2":"ar"}] }}}

=== Show a carrier ===

{{{HTTP GET /api/carriers/.{xml|json}}}}

//Authentication: none//

Show a carrier given its GUID. Responds with {{{HTTP_NOT_FOUND}}} if the carrier with the given GUID does not exist.

Examples

Request:

{{{HTTP GET /api/carriers/c09dc81a-2f0d-4332-9459-ab49e6690908.xml}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!xml

}}}

Request:

{{{HTTP GET /api/carriers/c09dc81a-2f0d-4332-9459-ab49e6690908.json}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!js {"name":"Personal","guid":"c09dc81a-2f0d-4332-9459-ab49e6690908","country_iso2":"ar"} }}}

== Channels ==

=== Channel specification ===

Every channel in nuntium must have the following properties:

name: must only contain alphanumeric characters, dash or underscore. Spaces are not allowed
[Channels#Kinds kind]
[Channels#Protocols protocol]
[Channels#Directions direction]: incoming, outgoing or bidirectional
address: (optional) the address from which an incoming or bidirectional channel sends messages (informative)
priority: a number
throttle: (optional) number of messages to send per minute, or zero for non-throttled
enabled: (optional) true or false

Additionally each channel has configuration properties that are specific to each channel kind.

==== clickatell ====

user: (only for outgoing or bidirectional channels)
password: (only for outgoing or bidirectional channels)
from: (only for outgoing or bidirectional channels)
api_id
network: (optional) 61, 44a, 46, 49, 45, 44b or usa
concatenation
incoming_password: (only for incoming channels)

==== dtac ====

user
password
sno

==== pop3 ====

host
port
user
password
use_ssl: true or false

==== qst_client ====

url
user
password

==== qst_server ====

password

==== smpp ====

host
port
user
password
system_type: for example 'vma'
source_ton
source_npi
destination_ton
destination_npi
endianess: big or little
accept_mo_hex_string: true or false
default_mo_encoding: ascii, latin1, ucs-2 or gsm
mt_encodings: comma separated list of values that can be ascii, latin1 or ucs-2
mt_max_length
mt_csms_method: udh, optional_parameters or message_paylod

==== smtp ====

host
port
user
password
use_ssl: true or false

==== twitter ====

screen_name
welcome_message: (optional) message to send to users subscribing to the user
token: obtained via OAUTH authentication
secret: obtained via OAUTH authentication

==== xmpp ====

user
domain
password
server (optional)
port
resource (optional)
status: (optional) the status to show in the contact list when connecting

=== List all channels ===

{{{HTTP GET /api/channels.{xml|json}}}}

//Authentication: account, application//

List both channels that belong to an application and that does not belong to any application.

Examples

Request:

{{{HTTP GET /api/channels.xml}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!xml

}}}

Request:

{{{HTTP GET /api/channels.json}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!js [{ "kind": "clickatell", "direction": "outgoing", "enabled": "true", "configuration":[ {"value": "1", "name": "api_id"}, {"value": "c", "name": "from"}, {"value": "45", "name": "network"}, {"value": "a", "name": "user"}, {"value": "3", "name": "concat"} ], "restrictions":[ {"value": ["bar", "baz"], "name": "foo"}, {"value": "prop", "name": "another"} ] "name":"foo", "protocol":"sms", "priority":100, "address":"sms://1234" }] }}}

=== Create a channel ===

{{{HTTP POST /api/channels.{xml|json}}}}

//Authentication: account, application//

Creates a channel that will belong to an application.

Responds with {{{HTTP_BAD_REQUEST}}} if the some of the channel's fields are not valid. Check the [API#Channel_errors errors section] for more info.

Examples

Request:

{{{HTTP POST /api/channels.xml}}}

{{{ #!xml

}}}

Response:

{{{HTTP/1.1 200 OK}}}

Request:

{{{HTTP POST /api/channels.json}}}

{{{ #!js { "kind": "clickatell", "direction": "outgoing", "enabled": "true", "configuration":[ {"value": "1", "name": "api_id"}, {"value": "c", "name": "from"}, {"value": "45", "name": "network"}, {"value": "a", "name": "user"}, {"value": "3", "name": "concat"} ], "restrictions":[ {"value": ["bar", "baz"], "name": "foo"}, {"value": "prop", "name": "another"} ] "name":"foo", "protocol":"sms", "priority":100, "address":"sms://1234" } }}}

Response:

{{{HTTP/1.1 200 OK}}}

=== Update a channel ===

{{{HTTP POST /api/channels.{xml|json}}}}

//Authentication: account, application//

Updates a channel that belongs to an application.

Only the attributes present in the given xml/json will be updated: the others will remain untouched. If a configuration element is present, all of the configuration values will be updated. The same is true for the restrictions element.

Responds with {{{HTTP_NOT_FOUND}}} if the channel does not exist.

Responds with {{{HTTP_FORBIDDEN}}} if the channel belongs to another application (when authenticated as an application).

Responds with {{{HTTP_BAD_REQUEST}}} if some of the channel's fields are not valid. Check the [API#Channel_errors errors section] for more info.

Examples

Request:

{{{HTTP PUT /api/channels/foo.xml}}}

{{{ #!xml

}}}

Response:

{{{HTTP/1.1 200 OK}}}

Request:

{{{HTTP PUT /api/channels/foo.json}}}

{{{ #!js { "kind": "clickatell", "direction": "outgoing", "enabled": "true", "configuration":[ {"value": "1", "name": "api_id"}, {"value": "c", "name": "from"}, {"value": "45", "name": "network"}, {"value": "a", "name": "user"}, {"value": "3", "name": "concat"} ], "restrictions":[ {"value": ["bar", "baz"], "name": "foo"}, {"value": "prop", "name": "another"} ] "protocol":"sms", "priority":100, "address":"sms://1234" } }}}

Response:

{{{HTTP/1.1 200 OK}}}

=== Show a channel ===

{{{HTTP GET /api/channels/<channel_name>.{xml|json}}}}

//Authentication: account, application//

Show the channel that belong to an application or that does not belong to any application.

Responds with {{{HTTP_NOT_FOUND}}} if the channel does not exist.

Examples

Request:

{{{HTTP GET /api/channels/foo.xml}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!xml

}}}

Request:

{{{HTTP GET /api/channels/foo.json}}}

Response:

{{{HTTP/1.1 200 OK}}}

=== Delete a channel ===

{{{HTTP DELETE /api/channels/<channel_name>}}}

//Authentication: account, application//

Deletes a channel that belong to an application.

Responds with {{{HTTP_NOT_FOUND}}} if the channel does not exist.

Responds with {{{HTTP_FORBIDDEN}}} if the channel belongs to another application (when authenticated as an application).

Examples

Request:

{{{HTTP DELETE /api/channels/foo}}}

Response:

{{{HTTP/1.1 200 OK}}}

=== Candidate channels ===

{{{HTTP GET /api/candidate/channels.{xml|json}?from=...&to=...&subject=...&body=...}}}

//Authentication: application//

List candidate channels that will be used when routing the given AO Message, that is, the result of the [Channels#Channel_Filter_Phase Channel Filter Phase]. This does not perform the routing, it just simulates it and returns the candidate channels list.

Examples

Request:

{{{HTTP GET /api/candidate/channels.xml?from=sms://1&to=sms://2&subject=Hello&body=Hi}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!xml

}}}

Request:

{{{HTTP GET /api/candidate/channels.json?from=sms://1&to=sms://2&subject=Hello&body=Hi}}}

Response:

{{{HTTP/1.1 200 OK}}}

=== Specific channel APIs ===

Some channel kinds support additional API methods.

==== Twitter ===

===== Create friendship =====

{{{HTTP GET /api/channels//twitter/friendships/create?user=&follow=}}}

//Authentication: account, application//

Creates a friendship between the channel's twitter account and the given user.

Returns {{{HTTP_OK}}} if the friendship could be created or if the frienship already existed.

Refer to Twitter's documentation: http://apiwiki.twitter.com/Twitter-REST-API-Method:-friendships%C2%A0create

Responds with {{{HTTP_NOT_FOUND}}} if the channel does not exist.

Responds with {{{HTTP_FORBIDDEN}}} if the channel belongs to another application (when authenticated as an application).

Responds with {{{HTTP_BAD_REQUEST}}} if the channel is not a Twitter channel.

==== XMPP ===

===== Add contact =====

{{{HTTP GET /api/channels//xmpp/add_contact?jid=}}}

//Authentication: account, application//

Adds a contact in the xmpp account associated to the channel.

Returns {{{HTTP_OK}}} if the contact was successfully added. Note that the user identified by the given JID still needs to approve this request.

Responds with {{{HTTP_NOT_FOUND}}} if the channel does not exist.

Responds with {{{HTTP_FORBIDDEN}}} if the channel belongs to another application (when authenticated as an application).

Responds with {{{HTTP_BAD_REQUEST}}} if the channel is not an XMPP channel.

=== Channel errors ===

When creating or updating a channel, if some of the fields are missing or are invalid, an {{{HTTP_BAD_REQUEST}}} response is returned. The body of the response contains the error messages.

Examples

Request:

{{{HTTP POST /api/channels.xml}}}

{{{ #!xml

}}}

Response:

{{{HTTP/1.1 400 BAD REQUEST}}}

{{{ #!xml

}}}

Request:

{{{HTTP POST /api/channels.json}}}

Response:

{{{HTTP/1.1 400 BAD REQUEST}}}

{{{ #!js { "summary": "There were some problems", "properties" => { "protocol" => "can't be blank" } } }}}

== Countries ==

=== List all countries ===

{{{HTTP GET /api/countries.{xml|json}}}}

//Authentication: none//

List of countries with their phone prefixes known for Nuntium.

Examples

Request:

{{{HTTP GET /api/countries.xml}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!xml

}}}

Request:

{{{HTTP GET /api/countries.json}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!js [{ "name": "Argentina", "iso2": "ar", "phone_prefix": "54", "iso3": "arg" }] }}}

=== Show a country ===

{{{HTTP GET /api/countries/<iso2_or_iso3>.{xml|json}}}}

//Authentication: none//

Shows a country given its iso2 or iso3 code. Responds with {{{HTTP_BAD_REQUEST}}} if no country exists with that iso code.

Examples

Request:

{{{HTTP GET /api/countries/ar.xml}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!xml

}}}

Request:

{{{HTTP GET /api/countries/ar.json}}}

Response:

{{{HTTP/1.1 200 OK}}}

{{{ #!js { "name": "Argentina", "iso2": "ar", "phone_prefix": "54", "iso3": "arg" } }}}

== Messages ==

=== Send an Application Originated message ===

{{{ HTTP GET /<account_name>/<application_name>/send_ao.{xml|json} HTTP POST /<account_name>/<application_name>/send_ao.{xml|json} }}}

//Authentication: application//

Sends one or more Application Originated messages.

If no format is specified (the request is made as just send_ao) one message will be sent and the request should include form data. The form data can contain the following fields: from, to, subject, body, guid, timestamp, token. Additional form data will be set as custom attributes, with the exception of the following fields: controller, action, application_name, account_name.

If the JSON format is specified (send_ao.json) the POST body must be an array of hashes.

If the XML format is specified (send_ao.xml) the POST body must be as specified in the https://bitbucket.org/instedd/geochat/wiki/QueueStateTransfer.

Responds with {{{HTTP_OK}}}. In any case, the following custom HTTP headers will be sent in the response:

X-Nuntium-Id: (when no format is specified) the id of the message kept by Nuntium.
X-Nuntium-Guid: the guid of the message. This is the one that was sent in the request, or a randomly generated one if none was specified.
X-Nuntium-Token: a token to be able to retrieve messages sent in this request. See Get Application Originated Messages and Tokens. This will be automatically generated if not specified in the request.

Examples

Request:

{{{HTTP GET /account_name/application_name/send_ao?from=sms://0&to=sms://1&subject=Hello}}}

Response:

{{{ HTTP/1.1 200 OK X-Nuntium-Id: 1343 X-Nuntium-Guid: 2b483424-2c2a-4702-b391-651f2a21da9d X-Nuntium-Token: 8212275-c104-1bbd-4a22-a94943fa263d2 }}}

=== Get Application Originated messages ===

{{{ HTTP GET /<account_name>/<application_name>/get_ao.json?token={token} }}}

//Authentication: application//

Gets Application Originated messages with the given [Tokens token].

Returns a JSON, an array of hashes with the properties of the message: from, to, subject, body, guid, state, channel (the channel's name), channel_kind and custom atrributes.

Responds with {{{HTTP_OK}}}.

API - dwilkie/nuntium GitHub Wiki

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️