Public API

Public API

At BRN platform we have some API, that can be sent not from BRN server with our authorization, but from other services with special authorization.

API with bot token

Every bot has its own token, which can be used at public API requests. This token you can see, if you go to bot Settings page, section Other and find field Api access token.

This token you can use as a parameter: ?access_token = < bot_token > at next API requests:

1. Creating broadcast:

POST request https://api.brn.ai/api/broadcast?access_token=

With request body, like at this example:

{
  "name": "Test broadcast",
  "type": "manual/collection/scenario",
  "timing": {
        "type": "repeat",
        "date":  "2016-12-05T11:28:50.235Z",
        "frequency": "daily"
  },
  "subscribers": {
  "gender": "male",
  "providers": ["messenger", "widget"],
  "context ": [
        { 
            "field": "age",
            "condition": “lte”,
            "value": 30
        }
    ]
  },
  "broadcast_data": "Object with data according to type (see below)"
}

Type manual:

"broadcast_data":{
     "messages": [
        {
           "content": {
                "text":"Text message"
           },
           "type":"text"
         },
         {
           "content":{
                 "url":"https://api-dev.brn.ai/upload/img/messages/X4nOCquNfY.jpg"
         },
            "type":"image"
         }
    ]
}

Type collection:

"broadcast_data":{
     "scenario_id":"PRPEPMFLLX",
     "text":"Intro text",
     "collection_id":"E4CL2H2KBY",
     "template":{
         "options":{"top_element_style":"compact"},
         "link":"{{link}}",
         "text":"{{description}}",
         "title":"{{title}}",
         "image":"{{image}}",
         "type":"list",
         "buttons":[
               {"url":"URl","title":"Url button","type":"link"},
               {"content":"my_data","title":"Postback button","type":"suggest"}
          ]
      }
}

Type scenario:

"broadcast_data":{
    "text":"Text to pass to scenario",
    "scenario_id":"PRPEPMFLLX"
}

This request you can use, if you want to send broadcast to bot users from other site, for example, every time, when new article is created at the site, send this article to bot users.

This request must have these parameters at its body:

  1. name – name of your broadcast, must be string, unique for each broadcast (unique for each new article in our example);
  2. type – must have one of three values: “manual”, “collection”, “scenario” – determines type of your broadcast. At BRN platform three types of broadcast are used:
    1. manual – you send message, which you type manually;
    2. collection – you send the newest 10 elements of your collection, using Cards;
    3. scenario – bot begins to talk with user according to certain scenario
  3. timing – must be an object according to timing, that you need. Broadcast can belong to one of three types of timing:
    1. now – if you want to send broadcast only one time, immediately. At this case, timing object must have only one property:
      1. type: now
    2. schedule – if you want to send broadcast only one time, but not immediately. Properties of timing object must be:
      1. type: schedule;
      2. date: date and time, when you want to send broadcast at format like this: “2016-12-05T11:28:50.235Z”;
      3. optional, if you want to send broadcast according to users timezones, you can add property time_travel: true
    3. repeat – if you want to send broadcast every day or every month, beginning from certain date. At this case properties of timing object will be next:
      1. type: repeat;
      2. date: date and time, when you want to send broadcast first time at format like this: “2016-12-05T11:28:50.235Z”;
      3. frequency: must be “daily” or “monthly”
      4. optional, if you want to send broadcast according to users timezones, you can add property time_travel: true
  4. subscribers – must be an object, defining users, who will receive this broadcast:

    1. if you want to send broadcast to all users of your bot, object must be empty {};
    2. if you want to send broadcast to users, subscribed to bot alerts by Subscription component, object must have property: subscription: true;
    3. if you want to send broadcast to users with certain gender, provider(s) or other tag(s), defined on Audience page, object must have properties : or : [, …]. For example: {“gender”: “male”, “providers”: [ “messenger”, “widget”]};
    4. if you want to send broadcast only to users, which have variables at their User storage, corresponding to certain criteria, object must have property context, which must be an array. Every element of this array must be an object with these properties:

      1. field: name of user variable, which must have user to receive broadcast;
      2. condition: must be one of these: “equal”, “ne”, “gt“, “gte“, “lt“, “lte“, “days“. “exists“, “not exists“;
      3. value: value, with which you want to compare your variable.

      For example, if you want to send your broadcast only to users, which tell to bot their age, and it was written into variable age type user, and this age is under 30, you have to add to subscribers object next property:

      "context ": [
          { "field": "age",
            "condition": “lte”,
            "value": 30}
      ]
      
  5. broadcast_data – must be an object, that describes, what information will be sended. Broadcast_data depends of broadcast type:

    1. if type is manual, broadcast_data contains property messages, which is an array. Elements of this array are messages, which will be sent by broadcasts, in JSON form. For example:
      "broadcast_data":{
           "messages": [
              {
                  "content": {
                      "text":"Text message"
                  },
                  "type":"text"
              },
              {
                  "content":{
                      "url":"https://api-dev.brn.ai/upload/img/messages/X4nOCquNfY.jpg"
                  },
                  "type":"image"
              }
          ]
      }
      

Every message contains type and content. Form of content depends of type:

Text messages:

        type: text,
        content: {
            text: "message text"
        }

Messages, which send images, audio, video:

        type: image (or audio, or video),
        content: {
            url: "url to image (audio, video) file"
        }

Messages, which send file to download:

        type: file,
        content: {
            url: "url to file",
            name: "file name"
        }

Messages with text and buttons: type: suggest, content: { buttons: [ { content: “button content”, title: “button title” } ], text: “text part” }

Messages with cards (for details, look to description of Card component)

        type: card,
        content: {
        elements: [ 
            {
                buttons: [
                    {
                        title: "button title",
                        type: "link",
                        url: "button url"
                    },
                    {
                        title: "button title",
                        type: "suggest",
                        content: "button postback content"
                    }
                ],
                collapse: [
                    {
                        content: "collapse block content",
                        title: "collapse block title"
                    }
                ],
                link: "card link",
                text: "card text",
                image: "image url",
                title: "card title required"
            }
        ]
    }


2. if type of broadcast is collection, broadcast_data contains next properties:

    1. scenario_id - id of scenario, that must start after showing cards, may be empty string;
    2. text - text, that will be shown before card, may be empty string;
    3. collection_id - id of collection, 10 elements of which will be shown;
    4. template - object, which describes, how collection element will be shown in card form, for example:

        "template":{
             "options":{"top_element_style":"compact"},
             "link":"{{link}}",
             "text":"{{description}}",
             "title":"{{title}}",
             "image":"{{image}}",
             "type":"list",
             "buttons":[
                {"url":"URl","title":"Url button","type":"link"},
               {"content":"my_data","title":"Postback button","type":"suggest"}
             ]
       }

For more details look description on broadcast with collection type, collections and Card component

3. if type of broadcast is scenario, broadcast_data contains next properties:
    1. text - message, which bot receives before scenario start, may be empty string;
    2. scenario_id - id of scenario, which must start

If your request will be made successfully, you will receive response like this:

    {
        "status": true
    }

If there is error in your broadcast, you will receive next response:

    {
      "status": false,
      "error": "Error message"
    }

2. Uploading file:

This request you can use, if you want to upload certain file from your computer to storage on BRN.

POST request https://api.brn.ai/api/upload/:type?access_token=

Parameter: type – type of file, which you want to upload. It may be one of these types: “image”, “file”, “audio”, “video”.

Body of this request is form-data. You must send via form-data one variable with type file, which must contain file, that you want to upload.

If request will be made successfully, you will receive response like this:

{
    "status":true,
    "name":"file.jpg",
    "url":"url to file"
}

where:

name – name of your file,

url – url to it on BRN

If request will be made with error, response will be next:

{
    status": false,
    "error": "Error message"
}

3. Get products:

This request you can use to see all products at the bot store

GET request https://api.brn.ai/api/products?access_token=

If you want to filter product, that will be shown, you can add next parameters after “?”:

  1. category= – get only products of category, which has id or name, that you specified;
  2. =. Product has certain attributes, for example: title, brand, power and others. Attributes has many types. If type of attribute is string and it has determined list of values, request with this parameter will show only product with specified value of attribute. For example, if you set color=red, only products with red color. To set 2 colors you can write color=red&color=yellow. If parameter is string, but has not determined list of values, for example, title, request will read your value as regex pattern, match which must title of every shown product. If attribute type is number, for example, price, you can determine range of values that you want, for example, price=15-30, or give one condition to attribute, for example price=lte30, but not use some conditions to determine range. Conditions may be: eq, ne, lt, lte, gt, gte.

If you want to sort shown products by values of one of attributes, you can use parameters:

  1. sort_field= – defines attribute, by which products will be shown, for example sort_field=price, by default products are sorted by creation time, from newer to older;
  2. sort_direction= – defines sort direction, sort_direction may be asc for ascending direction or desc – for descending.

If you want to see not all attributes of product, but only some of them, use this parameter:

fields=,<…For example, if you want to see only title, brand and price, but not other attributes, you can type: fields=title,brand,price

Other parameters:

  1. limit – defines, how many products would you like to see in request, by default, limit = 10;
  2. offset – defines, how many products do you want to skip, as default, offset=0.

Response for successfully made request has for like in next example:

{
  "status": true,
  "products": [
    {
      "product_id": "66XVLDC0HA",
      "category_id": "GCKPYI9ULX",
      "bot_id": "Q2FJP26VDR",
      "slug": "red_shirt",
      "name": "Red Shirt",
      "price": 42,
      "attributes": {
            "title": "Red Shirt",
            "color": "red",
            "material": "cotton",
            "size": "s",
            "type": "summer",
            "price": 42
      },
      "ancestors": [
        "UI96EMWPBN",
        "TKIJN9ZFYN",
        "GCKPYI9ULX"
      ]
    }
  ]
}

where:

products is an array of searched products. Every product in it has next properties:

  1. product_id – id of product;
  2. category_id – id of category, to which product belongs;
  3. bot_id – id of bot, which has store with this product;
  4. slug – product name for mobile services links, without spaces;
  5. name – product name, shown at products table;
  6. price – product price;
  7. attributes – object, which contains product attributes and their values;
  8. ancestors – ids of categories and subcategories, to which product belongs, path to product by category tree.

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

4. View of one certain product:

This request you can use to see one certain product

GET request https://api.brn.ai/api/product/:id?access_token=

Parameter :id in link may be id, slug or name of product, that you want to see. If you want to see not all attributes of your product, but only some of them, use this parameter after “?”:

fields=,…For example, if you want to see only title, brand and price, but not other attributes, you can type: fields=title,brand,price.

Response for successfully made request has for like in next example:

{
  "status": true,
   "product_id": "66XVLDC0HA",
   "category_id": "GCKPYI9ULX",
   "bot_id": "Q2FJP26VDR",
   "slug": "red_shirt",
   "name": "Red Shirt",
   "price": 42,
   "attributes": {
        "title": "Red Shirt",
        "color": "red",
        "material": "cotton",
        "size": "s",
        "type": "summer",
        "price": 42
    },
    "ancestors": [
        "UI96EMWPBN",
        "TKIJN9ZFYN",
        "GCKPYI9ULX"
      ]
    }
  ]
}

where:

  1. status – is request was made successfully or not;
  2. product_id – id of product;
  3. category_id – id of category, to which product belongs;
  4. bot_id – id of bot, which has store with this product;
  5. slug – product name for mobile services links, without spaces;
  6. name – product name, shown at products table;
  7. price – product price;
  8. attributes – object, which contains product attributes and their values;
  9. ancestors – ids of categories and subcategories, to which product belongs, path to product by category tree.

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

5. Get product filters:

This request you can use to see all values of certain attributes for all products at certain category.

GET request https://api.brn.ai/api/products/filters?access_token=

You can use next parameters after “?”:

  1. fields=, – list of attributes, values of which you want to see, for example, fields=gallery,fin_period,price. This parameter is required;
  2. category_id= – id, name or title of category, for products from which you want to see lists of values of attributes. If category_id is not defined, request is made for default category.

Response for successfully made request has for like in next example:

{
    "status": true,
    "filters": {
        "gallery": [
            "http://12drive.fresh.techfunder.de/pictures/car/0e0cd1160a98e56939380f7e9a9be780.jpg",
            "http://12drive.fresh.techfunder.de/pictures/car/8537c852bcfc940c4eb4468e9136f7dc.png",
            "http://12drive.fresh.techfunder.de/pictures/car/a96bee237ba9de636be2eb547c3878f0.png",
            "http://12drive.fresh.techfunder.de/pictures/car/c9acc752f760f3e96e46cd978a63fc1c.jpg",
            "http://12drive.fresh.techfunder.de/pictures/car/05d278a8ebb1a4328384fe7ae5d826e4.jpg",
            "http://12drive.fresh.techfunder.de/pictures/car/1767882f6601b978c16f705c88cd2222.jpg",
            "http://12drive.fresh.techfunder.de/pictures/car/37d0c9d442d161d8981ac16f93abe824.jpg",
            "http://12drive.fresh.techfunder.de/pictures/car/60f943795443acd624f41b11d3e4789d.jpg",
            "http://12drive.fresh.techfunder.de/pictures/car/8bff38f888ab12a986eaa75f351af531.jpg"
        ],
        "fin_period": [
            "72 mth"
        ],
        "price": [
            425,
            629,
            660,
            195,
            161
        ]
    }
}

where

  1. status – is request was made successfully or not;
  2. filters – object with properties, each of which is name of certain attributes with array of existing values of this attribute in all products of certain category.

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

6. Customer registration:

This request you can use to register new customer of your bot store.

POST request https://api.brn.ai/api/customer/register?access_token=

Request body must look like at this example:

{
    "login": "cust1",
    "password": "123456",
    "profile": {
            "name": "Customer 1",
            "age": 25,
            "email": "example@example.com"
    }
}

Body must have next properties:

  1. loginstring, login of new customer, must be unique;
  2. passwordstring, password of new customer;
  3. profileobject, that must have fields, specified at bot.store.customer.profile;
  4. favoritesoptional, array of ids of products, which customer likes.

Response for successfully made request has for like in next example:

{
    "status": true,
    "customer_id": "M5M90WNG7Q",
    "token": "CUSTOMER TOKEN"
}
  1. status – is request was made successfully or not;
  2. customer_id – id of new customer
  3. token – customer token, which you need for sending request with customer authorization

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

7. Customer login:

This request you can use to login like an existing customer of your bot store

POST request https://api.brn.ai/api/customer/login?access_token=

Request body must look like at this example:

{
    "login": "cust1",
    "password": "123456"
}

Body must have next properties:

  1. loginstring, login of new customer, must be unique;
  2. passwordstring, password of new customer.

Response for successfully made request has for like in next example:

{
    "status": true,
    "token": "CUSTOMER TOKEN"
}
  1. status – is request was made successfully or not;
  2. token – customer token, which you need for sending request with customer authorization.

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

8. Get attribute range:

This request is used to get range of value of certain attribute among products of certain category of your bot store

GET request https://api.brn.ai/api/attributes/range/:attribute?access_token=

Parameter :attribute in link must be name of number attribute of products at certain category.

You can use this parameter after “?”:

  1. category_id= – id or name of category, for products from which you want to see range of values of attribute. If category_id is not defined, request is made for default category

Response for successfully made request has for like in next example:

{
    "status": true,
    "min": 4,
    "max": 5
}

where

  1. status – is request was made successfully or not;
  2. min – minimum value of attribute;
  3. max – maximum value of attribute.

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

9. Get list of values of one of selectable fields of customer profile:

GET request https://api.brn.ai/api/store/profile/:field/list?access_token=

Parameter :field in link must be name of selectable field of profile for customers at certain bot store.

Response for successfully made request has for like in next example:

{
    "status": true,
    "values": [
        "France",
        "Germany"
    ]
}

where

  1. status – is request was made successfully or not;
  2. values – array of possible values of specified profile field

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

API with customer token

These API requests are used not for certain bot, but for certain customer. Customer is identifying by token and receive information, actual for him: his orders, his favorite products etc. To receive token customer must register by registration request or login. He will take token at the response of these requests.

Requests of getting product and view current product may be sent with customer token too.

Besides them, you can send next requests with customer token:

1. Create order:

This request must be sent, when customer wants to create new order with some products.

POST request https://api.brn.ai/api/order?access_token=

It must have body like in example:

{
    "products": [
        {
            "product_id": "XE90XHQUAK",
            "count":1,
            "price": 40
        }, {
            "product_id": "W0V2U15N26",
            "count": 3,
            "price": 25
        }
     ],
     "attachments": [
        {
            "type": "image",
            "url": "Link to image",
            "label": "Sign"
        }
    ]
}

It must have properties:

  1. productsarray of objects, every item of which describes certain product in order. Elements of this array have next properties:
    1. product_id – id of product;
    2. count – number of products in order;
    3. price – price of one product;
  2. attachmentsoptional, array of object, every of what determines file, which customer wants to add to order. If customer does not want add any file, he does not need this property. Structure of every attachment object:
    1. typestring, must be one of these: “image”, “audio”, “video“, “file”;
    2. urlstring, url to your file, if you have it on your computer, you have first upload id to BRN, using Upload file request and receive url in response;
    3. labelstring, name, which you want to give your attachment

Response for successfully made request has for like in next example: { status: true, order_id: “GCKPYI9ULX” }

where:

  1. status – is request was made successfully or not;
  2. order_id – id of new order

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

2. Get orders:

This request must be sent, when customer wants to see all his or her orders.

GET request https://api.brn.ai/api/orders?access_token=

At this request you can use next parameters:

  1. limit – defines, how many products would you like to see in request, by default, limit = 30;
  2. offset – defines, how many products do you want to skip, as default, offset=0.

Response for successfully made request has for like in next example:

{
  "status": true,
  "orders": [
    {
      "updated_at": "2017-05-22T13:47:44.340Z",
      "created_at": "2017-05-22T13:47:44.340Z",
      "order_id": "OYXTUANIR1",
      "amount": 60,
      "customer": {
        "customer_id": "SQ9H5A4V41",
        "name": "John Snow"
      },
      "bot_id": "DLM5HJF7CQ1",
      "order_status": "new",
      "products": [
        {
          "product_id": "BKLTG4KVVZ",
          "name": "Mercedes-Benz CLA 2014",
          "price": 30,
          "count": 2
        }
      ],
      "attachments": [
        {
          "type": "image",
          "url": "Link to image",
          "label": "Sign"
        }
      ]
    }
  ]
}

where:

  1. status – is request was made successfully or not;
  2. ordersarray of objects, describing all customer’s orders. Every element of this array is an object with next properties:
    1. order_id – id of current object;
    2. bot_id – id of current bot;
    3. order_status – status of order, may be “new” or “closed”;
    4. created_at – time of creating order;
    5. updated_at – time of last update orde;
    6. amount – total order value;
    7. customerobject, describing customer, with properties:
      1. customer_id – id of customer;
      2. name – customer name;
    8. productsarray of objects, describing products in order. Every element has next properties:
      1. product_id – id of product;
      2. name – product name;
      3. price – price of one product;
      4. count – number of products in order;
    9. attachmentsarray of object, every of what describes file, added to order. Structure of every attachment object:
      1. type – type of file, one of these variants: “image”, “audio”, “video“, “file”;
      2. url – url to file;
      3. label – attachment name.

If request is made with errors, response will be next:

{
     "status": false,
     "error": "Error message"
}

3. Update customer:

This request must be sent, when customer wants to change his password or edit his profile.

PUT request https://api.brn.ai/api/customer?access_token=

It must have body like in example:

{
    "password": "New password (optional)",
    "profile": {
        "email": "example@example.com",
        "age": 26,
        "name": "Customer 1",
         "new_field": "value"
    }
}

It must have properties:

  1. passwordoptional, new password;
  2. profileobject, which content information about customer. Profile must correspond with field customer.schema of bot store, where names and types of profile field are written.

Response for successfully made request has for like in next example:

{
    "status": true,
    "customer_id": "M5M90WNG7Q",
    "name": "Customer 1",
    "login": "cust1",
    "profile": {
        "email": "example@example.com",
        "age": 26,
        "name": "Customer 1",
         "new_field": "value"
    }
}

where:

  1. status – is request was made successfully or not;
  2. customer_id – id of current customer;
  3. name – customer name;
  4. login – customer login;
  5. profile – object with information about customer at form {property1: value1, property2: value2 …}

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

4. View customer:

This request must be sent, when customer wants to watch information about him.

GET request https://api.brn.ai/api/customer?access_token=

Response for successfully made request has for like in next example:

{
    "status": true,
    "customer_id": "M5M90WNG7Q",
    "name": "Customer 1",
    "login": "cust1",
    "profile": {
        "email": "example@example.com",
        "age": 26,
        "name": "Customer 1"
    }
}

where:

  1. status – is request was made successfully or not;
  2. customer_id – id of current customer;
  3. name – customer name;
  4. login – customer login;
  5. profile – object with information about customer at form {property1: value1, property2: value2 …}

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

5. Add favorite:

This request must be sent, when customer wants to add new product to his favorites.

POST request https://api.brn.ai/api/customer/favorite/:product_id?access_token=

Parameter :product_id in link may be id of product, that customer wants to add to favorites.

Response for successfully made request has for like in next example:

{
    status: true
}

where:

  1. status – is request was made successfully or not.

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

6. Delete favorite:

This request must be sent, when customer wants to delete product from his favorites.

DELETE request https://api.brn.ai/api/customer/favorite/:product_id?access_token=

Parameter :product_id in link may be id of product, that customer wants to add to favorites.

Response for successfully made request has for like in next example:

{
    status: true
}

where:

  1. status – is request was made successfully or not

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}

7. Get favorites list:

This request must be sent, when customer wants to view list of his or her favorites products.

GET request https://api.brn.ai/api/customer/favorites?access_token=

At this request you can use next parameters:

  1. limit – defines, how many products would you like to see in request, by default, limit = 10;
  2. offset – defines, how many products do you want to skip, as default, offset=0.

Response for successfully made request has for like in next example:

{
    "status": true,
    "favorites": [
        {
            "product_id": "CZ6XP3RG7I",
            "name": "Black trousers",
            "attributes": {
                "price": 40,
                "title": "Black trousers",
                "material": [
                    "cotton",
                    "textile"
                ]
            }
         }
    ]
}

where:

  1. status – is request was made successfully or not;
  2. favoritesarray, every item of which is an object, describing product in customer favorites list. Every element of this array has these properties:
    1. product_id – id of current product;
    2. name – name of current product;
    3. attributes – object, which contains product attributes and their values

If request is made with errors, response will be next:

{
  "status": false,
  "error": "Error message"
}