Users Object

📘

Don't have an Instabot account yet?

Start your free trial today!

The Users Object API provides methods for managing your users in Instabot. To understand basic principles of working with objects it is recommended to read the Working with Objects guide first.

Contents

  1. Create a User
  2. Update a User
  3. Delete a User
  4. Get a User
  5. Get Users List
  6. User Object Schema
    6a. Conversation Object Schema
    6b. Session Object Schema
    6c. Responses Object Schema
    6d. Goal-Node Object Schema

1. Create User

To create a user, send POST request with JSON defining the user:

curl -X POST \
        "https://api.instabot.io/v1/users" \
    -H "X-Instabot-Api-Key:{API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}" \
    -H "Content-Type:application/json" \
    -d '{JSON_DATA}'

Here is the sample JSON that can be supplied within the request:

{  
   "email":"[email protected]",
   "phone":"",
   "photoFile":{  
            "objectId":322673813
    },
   "userName":"user1",
   "userPassword":"password",
   "name":"User First",
   "description":"First user"
}

Detailed description of User fields can be found in the User Object Schema section. Please note that the userName and userPassword fields are required for user creation.

If everything ok then API should respond with HTTP Status 201 and with body containing id of created object.

{
    "apiStatusCode" : "Success",
    "data": {
        "objectId" : 400
    }
}

2. Update User

To update the user object, send a PUT request with the {OBJECT_ID} identifier of the user object you want to update:

curl -X PUT \
        "https://api.instabot.io/v1/users/{OBJECT_ID}" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}" \
    -H "Content-Type: application/json" \
    -d '{JSON_DATA}'

Here is the sample JSON that can be supplied within the request:

{  
   "email":"[email protected]",
   "phone":null,
   "photoFile":{  
       "objectId":322673813
   },
   "username":"user1",
   "name":"User First",
   "description":"Sample user description"
}

Detailed description of User fields can be found in User Object Schema section.


3. Delete User

User can be deleted by sending a DELETE request using the {OBJECT_ID} identifier of the object you want to delete:

curl -X DELETE \
        "https://api.instabot.io/v1/users/{OBJECT_ID}" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

If you want to restore a deleted user object, send a POST request using the {OBJECT_ID} identifier of the deleted object.

curl -X POST \
        "https://api.instabot.io/v1/users/{OBJECT_ID}" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

4. Get User

To get information about the user call GET method using as {OBJECT_ID} identifier of the object you need to retrieve:

curl -X GET \
        "https://api.instabot.io/v1/users/{OBJECT_ID}" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

On success API should respond with JSON describing the user:

{  
   "apiStatusCode":"Success",
   "data":{  
      "email":"[email protected]",
      "phone":null,
      "photoFile":{  
         "url":"https://roko-mobi.s3.amazonaws.com/...",
         "urlExpiresAt":"2016-12-31T22:22:07.5124322Z",
         "objectId":322673979
      },
      "firstLoginTime":null,
      "lastLoginTime":null,
      "username":"user1",
      "referralCode":"PZGJX873",
      "userType":"general",
      "name":"User First",
      "description":"Sample users",
      "createDate":"2016-12-26T21:05:47.1064Z",
      "updateDate":"2016-12-26T22:21:11.1711Z",
      "objectId":322673814
   }
}

5. Get Users List

List of Users can be retrieved by any of two methods described in the Searching for Objects guide. Here is the sample call that retrieves first 20 users from the system:

curl -X GET \ 
        "https://api.instabot.io/v1/users?type=all&limit=20&skip=0" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

Available options for resolve query parameter:

value parameter

Comments

organizations

returns list of organizations user belongs to

userSegments

returns list of user segments user belongs to

conversations

returns list of conversations user has engaged with

Available options for the type query parameter:

type parameter

Comments

all

Return both anonymous, and registered users

Additionally, the lastUpdated users endpoint, and the since query parameter can be used to restrict the returned users to only those users with updated/changed information since the datetime specified. For example, the following call would return only those users that have been updated since 2017-03-30T14:44:55:

curl -X GET \
        "https://api.instabot.io/v1/users/lastUpdated?since=2017-03-30T14%3A44%3A55" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

6. User Object Schema

Here is the list of all possible properties for the User Object:

User Object Schema

Field Name

Type

Constraints

Comments

userName

string

Required, Unique

Unique user name

name

string

Read-write

User display name

description

string

Read-write

User description

email

string

Read-write

User e-mail

phone

string

Read-write

User phone number

photoFile

File Object

Read-write

Reference to File Object

userPassword

string

Required

User password should be passed during user creation. Never returned by other methods.

userType

enum

Read-only

Type of the user

lastActivityTime

date

Read-only

Datetime (ISO-8601) of the when any property* in the user object was updated.

*Excludes changes in the systemProperties and lastLastLoginTime properties

firstLoginTime

date

Read-only

Datetime (ISO-8601) of first user login

lastLoginTime

date

Read-only

Datetime (ISO-8601) of last user login

systemProperties

dictionary

Read-only

System properties collected by Instabot

customProperties

dictionary

Read-write

Custom properties

organizations

array

Read-only

Can be resolved as &resolve=organizations

conversations

array of conversation objects

Read-only

See Conversation Object Schema


Conversation Object Schema

🚧

You must include the `resolve=conversations' in your API request in order to receive the
'conversations', 'sessions', 'goalnodes', and 'responses' objects in the returned user object.

For example:
https://api.instabot.io/v1/users/<USER_ID>?resolve=conversations

Field Name

Type

Comments

objectId

integer

Instabot conversation ID

name

string

Instabot conversation name

status

enumeration

Possible values - active, draft, pending, inactive, completed

platform

enumeration

Possible values - mobile, web

url

string

URL to this specific conversation in the Instabot portal

sessions

array of session objects

See Session Object schema

goalNodes

array of goalNode objects

See Goal-Node Object schema


Session Object Schema

Field Name

Type

Comments

objectId

integer

Instabot conversation session ID

engaged

boolean

True if user engaged with the conversation. Else, false

startDate

date

Datetime (ISO-8601) of Instabot session launching to the user

isAbandoned

boolean

True if user engaged but did not complete the conversation. Else, false

isMicrosite

boolean

True if the session was engaged in a microsite. Else, false.

deviceModel

string

Browser user-agent if session was taken in web. Else, make and build of mobile device if session was taken in iOS/Android (native in-app)

status

enumeration

Possible values - noreply, engaged, completed

url

string

URL to this specific conversation session in the Instabot portal

responses

array of Response objects

See Response Object schema


Responses Object Schema

messageText

string

The text of the Instabot question/statement.

response

string

The text of the end-user's response to the messageText.
This field will only be present if the Instabot question/statement requires a response from the user.

date

date

Datetime (ISO-8601) of when this message response occurred.

uploadedFileUrl

URI

URI of the file asset uploaded by the end-user.
This field will only be present if the Instabot question/statement is of type "file-upload".

Sample response:

{
    "hasMoreRecords": true,
    "totalCount": 16,
    "apiStatusCode": "Success",
    "data": [
        {
            "developmentCompany": {
                "objectId": 16250400
            },
            "name": "zhuchkovat",
            "email": null,
            "phone": null,
            "photoFile": null,
            "firstLoginTime": "2018-03-21T14:15:26.9713Z",
            "lastLoginTime": "2018-03-22T08:36:54.4006Z",
            "lastSeenDate": "2018-03-22T08:37:16.7267Z",
            "username": "zhuchkovat",
            "systemProperties": {
                "deviceModel": "Chrome 64.0.3282",
                "deviceType": "Web",
                "city": "Saint Petersburg",
                "region": "Sankt-Peterburg",
                "country": "Russian Federation",
                "clientPlatform": "web"
            },
            "userType": "reference",
            "conversations": [
                {
                    "name": "14 03 Regression",
                    "status": "Active",
                    "platform": "Web",
                    "url": "<url-placeholder>",
                    "goalNodes": [],
                    "sessions": [
                        {
                            "status": "Engaged",
                            "startDate": "2018-03-21T14:17:04.99Z",
                            "deviceType": "Web",
                            "isAbandoned": false,
                            "isEngaged": true,
                            "isMicrosite": false,
                            "url": "<url-placeholder>",
                            "objectId": 70627752,
                            "responses": [
                                {
                                    "messageText": "Hello, friend! Your username is zhuchkovat and Carrier is Beeline"
                                    "date": "2018-03-21T14:17:05Z"
                                },
                                {
                                    "messageText": "Select 1,2 or 3",
                                    "response": "1",
                                    "date": "2018-03-21T14:17:07Z"
                                },
                                {
                                    "messageText": "Please upload your photo",
                                    "uploadedFileUrl": "https://roko-mobi-qa.s3.amazonaws.com/9dde2edc-813c-476f-a138-147e14ebe0b4/486c6264-30da-4a5a-8a5f-e2be743aabf6",
                                    "date": "2018-03-21T14:17:09Z"
                                }
                            ]
                        }
                    ],
                    "objectId": 70619441
                }
            ],
            "lastActivityDate": "2018-03-22T08:38:13.0856Z",
            "requestInfo": null,
            "visitInfo": [
                {
                    "application": {
                        "objectId": 70378010
                    },
                    "count": 3
                }
            ],
            "rowVersion": 75308456,
            "createDate": "2018-03-21T14:12:57.7386Z",
            "updateDate": "2018-03-22T08:38:13.0856Z",
            "objectId": 70627747
        }
    ]
}

Goal-Node Object Schema

Field Name

Type

Comments

goalName

string

Name of goal (as named in the Instabot portal)

nodeName

string

Name of the node designated as a goal (as named in the Instabot portal)

objectId

integer

Goal-node ID