API Requests

Sending single or batch push messages

Documentation has moved

The information on this page is no longer updated and may be obsolete. The most current Koshelek documentation is now available at the new address:

https://developers.koshelek.app/en/

Push API

Send Single Push Message

POST https://api.cardsmobile.ru/push/delivery

The request is used by a partner to send a single push message (transactional, service or advertising) to a certain recipient.

Request Body

Name	Type	Description
pushType*	string	Type of the message: TRANSACTION — for transactional; SERVICE — for service; PROMO — for advertising.
msisdn*	integer	Recipient phone number without the + prefix.
payload*	object	Message to be sent (JSON object Payload).
qos	object	Message delivery settings (JSON object QoS).
utm	object	Additional delivery settings (JSON object UTM).

200: OK The request is processed. The response body consists of a JSON object containing ID of the message delivery session and current message delivery status:

General view of response body

{
  "messageId": "UUID",
  "state": "MSISDN_NOT_REGISTERED|ENQUEUED"
}

Example of response body

{
  "messageId": "aeb739ab-8b3a-4404-94ce-3ec96b3c0afa",
  "state": "ENQUEUED"
}

429: Too Many Requests Frequency limit for sending push messages is exceeded. The response body is empty.

For description of Payload, QoS and QoS objects, see API Objects.

If a push message was not sent due to sending rate limit exceeding, attempt to send the message later.

Example of request body:

Send a transactional message

{
    "pushType": "TRANSACTION",
    "msisdn": 71234567890,
    "payload": {
        "title": "Bonus points written off",
        "message": "Your card balance is reduced by 10 bonuses",
        "image": "http://partnerdomain/logo.jpg",
        "deeplink": {
            "target": "card"
        }
    },
    "qos": {
        "deliveryStatusNotifications": true
    }
}

Single Push Message Bulk Sending

POST https://api.cardsmobile.ru/bulk/single

The request is used by a partner to send a single push message (transactional, service or advertising) to a certain list of recipients.

Request Body

Name	Type	Description
pushType*	string	Type of the message: TRANSACTION — for transactional message; SERVICE — for service; PROMO — for advertising.
msisdn*	array	Array of recipient phone numbers. Integers without the + prefix.
payload*	object	Message to be sent (JSON object Payload, see above).
qos	object	Message delivery settings (JSON object QoS, see above).
utm	object	Additional delivery settings (JSON object UTM, see above).

200: OK The request is processed. The response body consists of an array of JSON objects containing ID of the message delivery session and current message delivery status:

General view of response body

[
  {
    "msisdn": MSISDN,
    "messageId": "UUID",
    "state": "MSISDN_NOT_REGISTERED|ENQUEUED"
  }, ...
]

Example of response body

[
  {
    "msisdn": 79001234567,
    "messageId": "aeb739ab-8b3a-4404-94ce-3ec96b3c0afa",
    "state": "ENQUEUED"
  },
  {
    "msisdn": 79001234578,
    "messageId": "8df6fed9-73ab-40d0-800c-08bd5343e7f4",
    "state": "ENQUEUED"
  },
  {
    "msisdn": 79001234589,
    "messageId": "1be1561e-c108-4603-9334-567d6db15bf5",
    "state": "ENQUEUED"
  }
]

429: Too Many Requests Frequency limit for sending push messages is exceeded. The response body is empty.

503: Service Unavailable Bulk sending is not accessible or the request is incorrect. The response body consists of a JSON object containing the error description.

General view of response body

{
  "status": "ERROR_CODE",
  "errors": [
    "Error description", ...
  ]
}

Example of response body

{
  "status": "BATCH_SIZE_EXCEEDED",
  "errors": [
    "The allowed batch size has been exceeded"
  ]
}

Example of request body:

{
  "pushType": "TRANSACTION",
  "msisdn": [
    79001234567,
    79001234578,
    79001234589,
    79001234590
  ],
  "payload": {
    "title": "Bonus points written off",
    "message": "Your card balance is reduced by 10 bonuses",
    "image": "http://partnerdomain/logo.jpg",
    "deeplink": {
      "target": "card"
    }
  },
  "qos": {
    "deliveryStatusNotifications": true
  },
  "utm": {
    "utmSource": "cardsmobile",
    "utmMiddle": "cpc",
    "utmCampaign": "campaign_name"
  }
}

Multiple Push Messages Bulk Sending

POST https://api.cardsmobile.ru/bulk/multi

The request is used by a partner to send several push messages (transactional, service or advertising) to several recipients at once (one message to one recipient).

Request Body

Name	Type	Description
*	array	Array of JSON objects describing a push message to be sent (body of a /delivery request, see above).

200: OK The request is processed. The response body consists of an array of JSON objects containing the ID of the message delivery session and current message delivery status:

General view of response body

[
  {
    "msisdn": MSISDN,
    "messageId": "UUID",
    "state": "MSISDN_NOT_REGISTERED|ENQUEUED"
  }, ...
]

Example of response body

[
  {
    "msisdn": 79001234567,
    "messageId": "aeb739ab-8b3a-4404-94ce-3ec96b3c0afa",
    "state": "ENQUEUED"
  },
  {
    "msisdn": 79001234578,
    "messageId": "8df6fed9-73ab-40d0-800c-08bd5343e7f4",
    "state": "ENQUEUED"
  },
  {
    "msisdn": 79001234589,
    "messageId": "1be1561e-c108-4603-9334-567d6db15bf5",
    "state": "ENQUEUED"
  }
]

503: Service Unavailable Bulk sending is not accessible or the request is incorrect. The response body consists of a JSON object containing the error description.

General view of response body

{
  "status": "ERROR_CODE",
  "errors": [
    "Error description", ...
  ]
}

Example of response body

{
  "status": "BATCH_SIZE_EXCEEDED",
  "errors": [
    "The allowed batch size has been exceeded"
  ]
}

Example of request body:

[
  {
    "pushType": "TRANSACTION",
    "msisdn": 71234567890,
    "payload": {
        "title": "Bonus points written off",
        "message": "Your card balance is reduced by 10 bonuses",
        "image": "http://partnerdomain/logo.jpg",
        "deeplink": {
            "target": "card"
        }
    },
    "qos": {
        "deliveryStatusNotifications": true
    }
  }
]

Get Promotional Action List From Personal Account

GET https://api.cardsmobile.ru/promos

A partner that has an account in Koshelek for Business can set up and publish promotional actions for the customers in the Koshelek app. This API method allows to get identifiers of current active promotional actions which can be used for setting up a redirection from a push message to the screen of the corresponding offer in the Koshelek app.

200: OK The request is processed. The response body consists of a JSON object containing array of current active promotional actions of the partner:

General view of response body

{
    "promos": [
        {
            "id": <promo action ID>,
            "name": "Promo action name",
            "active": true
        },
        {
            "id": <promo action ID>,
            "name": "Promo action name",
            "active": true
        }
    ]
}

Response body example

{
    "promos": [
        {
            "id": 1060,
            "name": "Discount 10% for a second item",
            "active": true
        },
        {
            "id": 435,
            "name": "Discount for Seniors",
            "active": true
        }
    ]
}

404: Not Found No active promotional actions for the partner are found. The response body is empty.

Body of the request is empty.

Get Delivery Status For a Single Message

GET https://api.cardsmobile.ru/push/{messageId}/transactional-state

The method is used to get the delivery status of a certain single push message.

Path Parameters

Name	Type	Description
messageId*	string	ID of the message.

200: OK The request is processed. The response body consists of a JSON object containing the sequence of push message statuses:

General view of response body

{
    "states": [
        {
            "msisdn": <MSISDN>,
            "state": "MSISDN_NOT_REGISTERED|ENQUEUED|DELIVERED|OPENED",
            "time": "yyyy-MM-ddThh:mm:ssZ"
        },
        {
            "msisdn": <MSISDN>,
            "state": "MSISDN_NOT_REGISTERED|ENQUEUED|DELIVERED|OPENED",
            "time": "yyyy-MM-ddThh:mm:ssZ"
        }
    ]
}

Response body example

{
    "states": [
        {
            "msisdn": 79000000011,
            "state": "DELIVERED",
            "time": "2022-11-11T16:30:08+0300"
        },
        {
            "msisdn": 79000000011,
            "state": "ENQUEUED",
            "time": "2022-11-11T16:30:08+0300"
        },
        {
            "msisdn": 79000000011,
            "state": "OPENED",
            "time": "2022-11-11T16:32:05+0300"
        }
    ]
}

Callback API

Inform About Changing Delivery Status

POST https://<partner-base-url>/<callback-endpoint>

If the delivery is created with the "true" value of deliveryStatusNotifications parameter, the Cardsmobile host will call URL specified by the partner during the integration at each changing of push message status (refer to Connection to API).

Request Body

Name	Type	Description
msisdn*	integer	Phone number of recipient without the + prefix.
messageId*	string	ID of the message.
state*	string	Current delivery status of the message: DELIVERED — if the message is delivered to user's device; OPENED — if the message has opened by user.
time	string	Time ("yyyy-MM-ddThh:mm:ssZ") when the message got the status.
utm	object	Object identifier with additional parameters for the delivery (as set upon delivery creation — see above).

200: OK The request is processed. The response body is empty:

Example of request body:

{
    "msisdn": 79051234567,
    "messageId": "c506b550-a309-11e9-a2a3-2a2ae2dbcce4",
    "state": "DELIVERED",
    "time": "2019-11-29T17:11:42Z",
    "utm": {
           "utmSource": "cardsmobile",
           "utmMiddle": "cpc",
           "utmCampaign": "campaign_name"
  }
}