API docs by Redocly

Swoo Push (2.0.0)

Introduction

This is an API of Swoo Push intended for partners that would like to use Swoo application as a delivery channel.

Swoo push API allows

  • checking if corresponding msisdn is Swoo-enabled (Pushes / Verify account)
  • supplying the notification message to be processed by Swoo platform (Pushes / Send push message)
    • the partner can optionally provide tariff.baseValue. Tariff base value is the value in USD that client is paying for this push notification. If not provided, Swoo's default tariffs will be used for billing.
  • Swoo platform then dispatches callbacks with statuses of the corresponding deliveries
    • we expect partner's endpoint to accept and process requests as defined in Callbacks / Push delivery callback.

Please contact us for

  • API extension / customizations
  • openapi spec file
  • SLO/As
  • credentials
  • pre-prod and prod environment configuration and access (including callback URL configuration)

The diagram below outlines baseline interaction for the partner. image

Authentication

For the Swoo Push API, the following Auth Schema is used in addition to IP-based whitelists:

AuthSwooSchema_ApiToken

Swoo partner API token. Authorization: Bearer <token>

Security Scheme Type: API Key
Header parameter name: Authorization

Pushes

Verify account

Check if msisdn is registered and account is subscribed to receive push notifications

Authorizations:
AuthSwooSchema_ApiToken
path Parameters
partnerId
required
string

Partner ID

Request Body schema: application/json
required
msisdn
required
string [ 8 .. 15 ] characters

Account phone number without leading +

Responses

Request samples

Content type
application/json
{
  • "msisdn": "37520111111"
}

Response samples

Content type
application/json
{
  • "state": "MSISDN_NOT_REGISTERED"
}

Send push message

Send push notification to the subscribed account

Authorizations:
AuthSwooSchema_ApiToken
path Parameters
partnerId
required
string

Partner ID

Request Body schema: application/json
required
pushType
string
Enum: "SERVICE" "TRANSACTION" "PROMO" "WELCOME"

Push notification type determines priority & default expiration time:

  • SERVICE - Service notifications (like OTP), high priority, expires in 3 seconds
  • TRANSACTION - Transaction notifications, high priority, expires in 3 seconds
  • PROMO - Advertising notifications, normal priority, expires in 15 seconds
  • WELCOME - Swoo welcome push after successfull subscription, high priority, expires in 2 days
msisdn
required
string [ 8 .. 15 ] characters

Account phone number without leading +

required
object

Payload

required
object

Quality of service

object

Responses

Request samples

Content type
application/json
{
  • "pushType": "SERVICE",
  • "msisdn": "37520111111",
  • "payload": {
    },
  • "qos": {
    },
  • "tariff": {
    }
}

Response samples

Content type
application/json
{
  • "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",
  • "msisdn": "37520111111",
  • "state": "ACCEPTED",
  • "type": "SERVICE",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Callbacks

Push delivery callback

Request Body schema: application/json
required
messageId
required
string <uuid>

Push notification ID

msisdn
required
string [ 8 .. 15 ] characters

Account phone number without leading +

state
required
string
Enum: "ACCEPTED" "MSISDN_NOT_REGISTERED" "CLIENT_UNSUBSCRIBED" "CLIENT_UNREGISTERED" "ENQUEUED" "DELIVERED" "OPENED" "ERROR" "EXPIRED_DELIVERED"

Push notification delivery state:

  • ACCEPTED - Push is accepted for the async processing and delivery (internal)
  • MSISDN_NOT_REGISTERED - Push will not be sent because the user with the specified number is not registered in the application
  • CLIENT_UNSUBSCRIBED - Push will not be sent because the user has unsubscribed from the sender's pushes
  • CLIENT_UNREGISTERED - Push will not be sent because the application was unregistered (internal)
  • ENQUEUED - Push has been accepted for delivery but not yet delivered
  • DELIVERED - Push has been delivered to the user's device
  • OPENED - Push has been read by the user
  • ERROR - Technical failure occurred while sending the push
  • EXPIRED_DELIVERED - Push was not sent because its lifespan expired
time
required
string <date-time>

Created date

Responses

Request samples

Content type
application/json
{
  • "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",
  • "msisdn": "37520111111",
  • "state": "ACCEPTED",
  • "time": "2019-08-24T14:15:22Z"
}