Client Endpoints¶

These endpoints allow acting as your OAuth 2.0 client. They require authentication with an active client token. They should only ever be called from a backend.

Note

As these endpoints don't need a user token they are considered "offline", so they can't be used to view connections that don't have the offline_access scope, or send messages to those users.

Connections¶

When a user approves a OAuth 2.0 request from a client, a connection between the user and client is established.

The connection records the user's alias ID generated for their connection with the client, the scopes they granted, any communication channels they granted, and the nickname they provided (if relevant).

The connection is updated when the user approves more permissions in subsequent auth requests, or revokes permissions from the Alias UI. A user can also revoke a connection entirely if they desire.

Warning

There is a slight delay between a user granting permissions and the connection being created/updated in these endpoints. Don't rely on changes being present immediately after an auth request.

Search¶

GET https://projectalias.com/api/client/connections

List connections between users and the client. Only connections with the offline_access scope are returned. A number of querystring options are provided to filter results.

Authentication

Scope	Required
`client:connections`	Yes

Querystring Options

Option	Type	Default	Description
`alias_id`	`[string]`		Filter by user alias ID.
`scope`	`[string]`		Filter by granted scopes.
`channel`	`[string]`		Filter by granted channels.
`created_from`	`date-time`		Filter to connections created on/after a date-time. `T00:00:00Z` is appended if only a date is provided.
`created_to`	`date-time`		Filter to connections created on/before a date-time. `T23:59:59Z` is appended if only a date is provided.
`updated_from`	`date-time`		Filter to connections updated on/after a date-time. `T00:00:00Z` is appended if only a date is provided.
`updated_to`	`date-time`		Filter to connections updated on/before a date-time. `T23:59:59Z` is appended if only a date is provided.
`sort`	`[string]`	`-created,-id`	Set result sort order. Supports sorting by `id`, `created`, `updated`. Prefix `-` to sort descending.
`offset`	`integer`	`0`	The offset of the first result to return in this page of results.
`limit`	`integer`	`10`	The number of results to return in this page.
`timeout`	`integer`	`30`	Max time to spend performing the request, in seconds.

Response Body

Field	Type	Description
`connections`	`[object]`	An array of connections.
`connections[].client_id`	`string`	The ID for the client.
`connections[].alias_id`	`string`	The alias ID for the connection user.
`connections[].scopes`	`[string]`	The scopes the user has granted the client.
`connections[].channels`	`[string]`	The communication channels the user has granted the client. `null` if the token doesn't have the `contact` scope.
`connections[].nickname`	`string`	The nickname the user provided. `null` if the token doesn't have the `nickname` scope.
`connections[].create_dt`	`date-time`	When the connection between the client and user was first created.
`connections[].update_dt`	`date-time`	When the connection between the client and user was last updated.
`paging`	`object`	Result paging information.
`paging.total`	`integer`	The total number of results for this search.
`paging.more`	`boolean`	Whether there are more pages of results.
`paging.next`	`integer`	The offset of the next page of results. `null` if no more pages.

Examples

Example Request

HTTP

GET /api/client/connections?channel=notifications&created_from=2020-01-19T10:00:00Z HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>

cURL

curl "https://projectalias.com/api/client/connections?channel=notifications&created_from=2020-01-19T10:00:00Z" \
    -H "Authorization: Bearer <access-token>"

Python

import requests
r = requests.get('https://projectalias.com/api/client/connections',
                 headers={'Authorization': 'Bearer <access-token>'},
                 params={'channel': 'notifications',
                         'created_from': '2020-01-19T10:00:00Z'})

Example Response

{
    "connections": [
        {
            "client_id": "bjOB6HV7cTKtxvfr2k2ucg",
            "alias_id": "epGEcGfc6LQMmKTqffWW2g",
            "scopes": ["openid", "offline_access", "contact", "nickname"],
            "channels": ["_meta", "notifications", "product_updates"],
            "nickname": "Fred",
            "create_dt": "2020-01-19T10:30:00+00:00",
            "update_dt": "2020-06-30T12:15:30+00:00"
        }
    ],
    "paging": {
        "total": 1,
        "more": false,
        "next": null
    }
}

Details¶

GET https://projectalias.com/api/client/connections/<alias_id>

Fetch a user's connection with the client. Only connections with the offline_access scope are available.

Authentication

Scope	Required
`client:connections`	Yes

Querystring Options

Option	Type	Default	Description
`timeout`	`integer`	`30`	Max time to spend performing the request, in seconds.

Response Body

Field	Type	Description
`client_id`	`string`	The ID for the client.
`alias_id`	`string`	The alias ID for the connection user.
`scopes`	`[string]`	The scopes the user has granted the client.
`channels`	`[string]`	The communication channels the user has granted the client. `null` if the token doesn't have the `contact` scope.
`nickname`	`string`	The nickname the user provided. `null` if the token doesn't have the `nickname` scope.
`create_dt`	`date-time`	When the connection between the client and user was first created.
`update_dt`	`date-time`	When the connection between the client and user was last updated.

Examples

Example Request

HTTP

GET /api/client/connections/epGEcGfc6LQMmKTqffWW2g HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>

cURL

curl "https://projectalias.com/api/client/connections/epGEcGfc6LQMmKTqffWW2g" \
    -H "Authorization: Bearer <access-token>"

Python

import requests
r = requests.get('https://projectalias.com/api/client/connections/epGEcGfc6LQMmKTqffWW2g',
                 headers={'Authorization': 'Bearer <access-token>'})

Example Response

{
    "client_id": "bjOB6HV7cTKtxvfr2k2ucg",
    "alias_id": "epGEcGfc6LQMmKTqffWW2g",
    "scopes": ["openid", "offline_access", "contact", "nickname"],
    "channels": ["_meta", "notifications", "product_updates"],
    "nickname": "Fred",
    "create_dt": "2020-01-19T10:30:00+00:00",
    "update_dt": "2020-06-30T12:15:30+00:00"
}

Send Message¶

POST https://projectalias.com/api/client/send

Send a message to a user, or all users subscribed to a channel. Can only send to users that have granted the offline_access scope.

An outbound message is created, along with a delivery record for each recipient. The outbound message shows the overall sending process, and the individual delivery records can be checked to determine which recipients the message has been successfully delivered to.

Authentication

Scope	Required
`client:send`	Yes

Request Body

Field	Type	Required	Description
`version`	`string`	Yes	The version of the message schema being used. `v0` is the only version currently supported.
`outbound_message_id`	`string`	No	The ID for this outbound message. Will be generated if not provided. 10-30 characters (inclusive). Must match `^[0-9a-zA-Z-_]+$`.
`channel`	`string`	Yes	The communication channel to send the message on. The token must include this channel.
`to`	`string`	Yes	The alias ID for the user to send the message to. Use `*` to send to all users currently subscribed to the channel.
`title`	`string`	Yes	The message title. 5-100 characters (inclusive).
`body`	`string`	No	The message body. 5-500 characters (inclusive).
`link`	`object`	No	Details of the message link.
`link.uri`	`string`	Yes	The message link URI.
`link.text`	`string`	No	Custom link text to display. 1-50 characters (inclusive).

Response Body

Field	Type	Description
`outbound_message_id`	`string`	The ID for the created outbound message.

Examples

Example Request

HTTP

POST /api/client/send HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "version": "v0",
    "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
    "channel": "notifications",
    "to": "epGEcGfc6LQMmKTqffWW2g",
    "title": "Here is your reminder",
    "body": "You asked to be reminded about this note.",
    "link": {
        "uri": "https://example.com/notes/z7I6s3jljh5RUoUYmqxxPw",
        "text": "Open your note"
    }
}

cURL

curl -XPOST "https://projectalias.com/api/client/send" \
    -H "Authorization: Bearer <access-token>" \
    -H "Content-Type: application/json" \
    -d '{
            "version": "v0",
            "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
            "channel": "notifications",
            "to": "epGEcGfc6LQMmKTqffWW2g",
            "title": "Here is your reminder",
            "body": "You asked to be reminded about this note.",
            "link": {
                "uri": "https://example.com/notes/z7I6s3jljh5RUoUYmqxxPw",
                "text": "Open your note"
            }
        }'

Python

import requests
r = requests.post('https://projectalias.com/api/client/send',
                  headers={'Authorization': 'Bearer <access-token>'},
                  json={'version': 'v0',
                        'outbound_message_id': 'LzIX47-iIDVpNmnbXqCYXg',
                        'channel': 'notifications',
                        'to': 'epGEcGfc6LQMmKTqffWW2g',
                        'title': 'Here is your reminder',
                        'body': 'You asked to be reminded about this note.',
                        'link': {'uri': 'https://example.com/notes/z7I6s3jljh5RUoUYmqxxPw',
                                 'text': 'Open your note'}})

Example Response

{
    "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg"
}

Outbound Messages¶

When a client sends a message, an outbound message is created. Outbound messages initially have the status of pending. Once delivery records have been created for all recipients, the status is updated to sending. Once all deliveries have completed - successfully or not - the status is updated to sent. The individual delivery records can be checked to determine which recipients the message has been successfully delivered to.

Search¶

GET https://projectalias.com/api/client/outbound-messages

List outbound messages that have been sent by the client. A number of querystring options are provided to filter results.

Authentication

Scope	Required
`client:outbound_messages`	Yes

Querystring Options

Option	Type	Default	Description
`channel`	`[string]`		Filter by message channel.
`status`	`[string]`		Filter by status. Statuses are `pending`, `sending`, `sent`.
`created_from`	`date-time`		Filter to messages created on/after a date-time. `T00:00:00Z` is appended if only a date is provided.
`created_to`	`date-time`		Filter to messages created on/before a date-time. `T23:59:59Z` is appended if only a date is provided.
`updated_from`	`date-time`		Filter to messages updated on/after a date-time. `T00:00:00Z` is appended if only a date is provided.
`updated_to`	`date-time`		Filter to messages updated on/before a date-time. `T23:59:59Z` is appended if only a date is provided.
`sort`	`[string]`	`-created,-id`	Set result sort order. Supports sorting by `id`, `created`, `updated`. Prefix `-` to sort descending.
`offset`	`integer`	`0`	The offset of the first result to return in this page of results.
`limit`	`integer`	`10`	The number of results to return in this page.
`timeout`	`integer`	`30`	Max time to spend performing the request, in seconds.

Response Body

Field	Type	Description
`outbound_messages`	`[object]`	An array of outbound messages.
`outbound_messages[].client_id`	`string`	The ID for the client.
`outbound_messages[].outbound_message_id`	`string`	The ID for the outbound message.
`outbound_messages[].channel`	`string`	The communication channel the message was sent on.
`outbound_messages[].recipient_count`	`integer`	The number of users the message was sent to.
`outbound_messages[].delivered_count`	`integer`	The number of users the message was delivered to.
`outbound_messages[].failed_count`	`integer`	The number of users the message could not be delivered to.
`outbound_messages[].status`	`string`	One of `pending`, `sending`, `sent`.
`outbound_messages[].create_dt`	`date-time`	When the outbound message was first created.
`outbound_messages[].update_dt`	`date-time`	When the outbound message was last updated.
`paging`	`object`	Result paging information.
`paging.total`	`integer`	The total number of results for this search.
`paging.more`	`boolean`	Whether there are more pages of results.
`paging.next`	`integer`	The offset of the next page of results. `null` if no more pages.

Examples

Example Request

HTTP

GET /api/client/outbound-messages?channel=notifications&created_from=2020-01-19T10:30:00Z HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>

cURL

curl "https://projectalias.com/api/client/outbound-messages?channel=notifications&created_from=2020-01-19T10:30:00Z" \
    -H "Authorization: Bearer <access-token>"

Python

import requests
r = requests.get('https://projectalias.com/api/client/outbound-messages',
                 headers={'Authorization': 'Bearer <access-token>'},
                 params={'channel': 'notifications',
                         'created_from': '2020-01-19T10:30:00Z'})

Example Response

{
    "outbound_messages": [
        {
            "client_id": "bjOB6HV7cTKtxvfr2k2ucg",
            "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
            "channel": "notifications",
            "recipient_count": 1,
            "delivered_count": 1,
            "failed_count": 0,
            "status": "sent",
            "create_dt": "2020-06-30T13:30:00+00:00",
            "update_dt": "2020-06-30T13:30:10+00:00"
        }
    ],
    "paging": {
        "total": 1,
        "more": false,
        "next": null
    }
}

Details¶

GET https://projectalias.com/api/client/outbound-messages/<outbound_message_id>

Fetch an outbound message that has been sent by the client.

Authentication

Scope	Required
`client:outbound_messages`	Yes

Querystring Options

Option	Type	Default	Description
`timeout`	`integer`	`30`	Max time to spend performing the request, in seconds.

Response Body

Field	Type	Description
`client_id`	`string`	The ID for the client.
`outbound_message_id`	`string`	The ID for the outbound message.
`channel`	`string`	The communication channel the message was sent on.
`recipient_count`	`integer`	The number of users the message was sent to.
`delivered_count`	`integer`	The number of users the message was delivered to.
`failed_count`	`integer`	The number of users the message could not be delivered to.
`status`	`string`	One of `pending`, `sending`, `sent`.
`create_dt`	`date-time`	When the outbound message was first created.
`update_dt`	`date-time`	When the outbound message was last updated.

Examples

Example Request

HTTP

GET /api/client/outbound-messages/LzIX47-iIDVpNmnbXqCYXg HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>

cURL

curl "https://projectalias.com/api/client/outbound-messages/LzIX47-iIDVpNmnbXqCYXg" \
    -H "Authorization: Bearer <access-token>"

Python

import requests
r = requests.get('https://projectalias.com/api/client/outbound-messages/LzIX47-iIDVpNmnbXqCYXg',
                 headers={'Authorization': 'Bearer <access-token>'})

Example Response

{
    "client_id": "bjOB6HV7cTKtxvfr2k2ucg",
    "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
    "channel": "notifications",
    "recipient_count": 1,
    "delivered_count": 1,
    "failed_count": 0,
    "status": "sent",
    "create_dt": "2020-06-30T13:30:00+00:00",
    "update_dt": "2020-06-30T13:30:10+00:00"
}

Message Deliveries¶

When a client tries to send a message to a user, a delivery record is created. Delivery records initially have the status of delivering. If the message is delivered successfully, the status is updated to delivered. If the message couldn't be delivered - e.g. because the user has revoked the message's channel - the status is updated to failed.

Search¶

GET https://projectalias.com/api/client/outbound-messages/<outbound_message_id>/deliveries

List delivery records for an outbound message that has been sent by the client. A number of querystring options are provided to filter results.

Authentication

Scope	Required
`client:outbound_messages`	Yes

Querystring Options

Option	Type	Default	Description
`alias_id`	`[string]`		Filter by the alias ID for the recipient user.
`status`	`[string]`		Filter by delivery status. Statuses are `delivering`, `delivered`, `failed`.
`created_from`	`date-time`		Filter to deliveries created on/after a date-time. `T00:00:00Z` is appended if only a date is provided.
`created_to`	`date-time`		Filter to deliveries created on/before a date-time. `T23:59:59Z` is appended if only a date is provided.
`updated_from`	`date-time`		Filter to deliveries updated on/after a date-time. `T00:00:00Z` is appended if only a date is provided.
`updated_to`	`date-time`		Filter to deliveries updated on/before a date-time. `T23:59:59Z` is appended if only a date is provided.
`sort`	`[string]`	`-created,-id`	Set result sort order. Supports sorting by `id`, `created`, `updated`. Prefix `-` to sort descending.
`offset`	`integer`	`0`	The offset of the first result to return in this page of results.
`limit`	`integer`	`10`	The number of results to return in this page.
`timeout`	`integer`	`30`	Max time to spend performing the request, in seconds.

Response Body

Field	Type	Description
`deliveries`	`[object]`	An array of delivery records.
`deliveries[].client_id`	`string`	The ID for the client.
`deliveries[].outbound_message_id`	`string`	The ID for the outbound message.
`deliveries[].alias_id`	`string`	The alias ID for the recipient user.
`deliveries[].channel`	`string`	The communication channel the message was sent on.
`deliveries[].status`	`string`	One of `delivering`, `delivered`, `failed`.
`deliveries[].create_dt`	`date-time`	When the delivery record was first created.
`deliveries[].update_dt`	`date-time`	When the delivery record was last updated.
`paging`	`object`	Result paging information.
`paging.total`	`integer`	The total number of results for this search.
`paging.more`	`boolean`	Whether there are more pages of results.
`paging.next`	`integer`	The offset of the next page of results. `null` if no more pages.

Examples

Example Request

HTTP

GET /api/client/outbound-messages/LzIX47-iIDVpNmnbXqCYXg/deliveries?channel=notifications&created_from=2020-01-19T10:30:00Z HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>

cURL

curl "https://projectalias.com/api/client/outbound-messages/LzIX47-iIDVpNmnbXqCYXg/deliveries?channel=notifications&created_from=2020-01-19T10:30:00Z" \
    -H "Authorization: Bearer <access-token>"

Python

import requests
r = requests.get('https://projectalias.com/api/client/outbound-messages/LzIX47-iIDVpNmnbXqCYXg/deliveries',
                 headers={'Authorization': 'Bearer <access-token>'},
                 params={'channel': 'notifications',
                         'created_from': '2020-01-19T10:30:00Z'})

Example Response

{
    "deliveries": [
        {
            "client_id": "bjOB6HV7cTKtxvfr2k2ucg",
            "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
            "alias_id": "epGEcGfc6LQMmKTqffWW2g",
            "channel": "notifications",
            "status": "delivered",
            "create_dt": "2020-06-30T13:30:00+00:00",
            "update_dt": "2020-06-30T13:30:10+00:00"
        }
    ],
    "paging": {
        "total": 1,
        "more": false,
        "next": null
    }
}

Details¶

GET https://projectalias.com/api/client/outbound-messages/<outbound_message_id>/deliveries/<alias_id>

Fetch a delivery record for an outbound message that has been sent by the client to a user.

Authentication

Scope	Required
`contact`	Yes

Querystring Options

Option	Type	Default	Description
`timeout`	`integer`	`30`	Max time to spend performing the request, in seconds.

Response Body

Field	Type	Description
`client_id`	`string`	The ID for the client.
`outbound_message_id`	`string`	The ID for the outbound message.
`alias_id`	`string`	The alias ID for the recipient user.
`channel`	`string`	The communication channel the message was sent on.
`status`	`string`	One of `delivering`, `delivered`, `failed`.
`create_dt`	`date-time`	When the delivery record was first created.
`update_dt`	`date-time`	When the delivery record was last updated.

Examples

Example Request

HTTP

GET /api/client/outbound-messages/LzIX47-iIDVpNmnbXqCYXg/deliveries/epGEcGfc6LQMmKTqffWW2g HTTP/1.1
Host: projectalias.com
Authorization: Bearer <access-token>

cURL

curl "https://projectalias.com/api/client/outbound-messages/LzIX47-iIDVpNmnbXqCYXg/deliveries/epGEcGfc6LQMmKTqffWW2g" \
    -H "Authorization: Bearer <access-token>"

Python

import requests
r = requests.get('https://projectalias.com/api/client/outbound-messages/LzIX47-iIDVpNmnbXqCYXg/deliveries/epGEcGfc6LQMmKTqffWW2g',
                 headers={'Authorization': 'Bearer <access-token>'})

Example Response

{
    "client_id": "bjOB6HV7cTKtxvfr2k2ucg",
    "outbound_message_id": "LzIX47-iIDVpNmnbXqCYXg",
    "alias_id": "epGEcGfc6LQMmKTqffWW2g",
    "channel": "notifications",
    "status": "delivered",
    "create_dt": "2020-06-30T13:30:00+00:00",
    "update_dt": "2020-06-30T13:30:10+00:00"
}