NAV Navbar
shell

Overview

The Maqpie API allows you to build your own chat clients or deeper integrate with chat widget.

Introduction

API libraries: We are planning to release official libraries, but haven’t moved in this direction yet. If would like to help us build some - let us know.

API Endpoint: https://api.maqpie.com/

API is organized around REST. All api access is over HTTPS, all responses, including errors are sent as JSON.

To make the API as explorable as possible, every account has a test and production mode api keys. There is no “switch” for changing between modes, just use the appropriate key to perform a production or test transaction. All tests requests are completely isolated from production environments.

Vulnerability & Improvement Rewards

We have strong focus to keep our API as predictable and developer-friendly as we can. Please, submit any issues or improvement requests using our github feedback forum. We reward all the cutting-edge external contributions to the Maqpie with a service discounts up to 100% for one year.

Authentication

# Example Invalid Request:
curl https://api.maqpie.com/users?appId=YOUR_APP_ID \
-H "Authorization: Bearer YOUR_API_SECRET"

To authenticate your account you must include Authorization: Bearer YOUR_API_SECRET_GO_HERE header with your secret key in the request. You can find your test and production API keys on the admin site.

Keep your api keys secret and do not share in public places, such as Github, client-side code, etc.

Errors

# Example request:
curl https://api.maqpie.com/users?appId=YOUR_APP_ID&sortBy=invalid
-H "Authorization: Bearer YOUR_API_SECRET"

Example error response:

{
   "errors":[
      {
         "sortBy":"Invalid sortBy value. Use one of the following: username, companyName, stats.lastMessageTime, stats.contactsCount, stats.conversationsCount, stats.totalMessagesCount."
      }
   ]
}

Maqpie uses conventional HTTP response codes to indicate the success or failure of an API request. In short: 2xx - success, 4xx - error due to invalid information provided, 5xx - something went wrong on our end.

HTTP status code summary

Code Meaning
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized Missing or incorrect access token.
404 - Not Found The requested resource doesn’t exist.
500, 502, 503, 504 - Server Errors something went wrong on our end.

All bad requests (status code: 400) returns a JSON object with errors array, where key typically equals to the name of the request parameter and value contains explanation of what went wrong.

Application

Application is a container object, that mainly contains configuration settings and secret keys for the chat. Application is not directly available using public api. Secret keys can be found using admin panel. Listed here just for reference. Application is a root chat resource. Every other resource has a reference to the applicationId. Application also used internally to make sure data segregation between companies and other chats.

The application object

Example application object:

{
    "_id" : "YOUR_APP_ID",
    "companyId" : "57a1bfdbdee29620b21631fc",
    "name" : "Magpie",
    "hashSecret" : "7cb59ccf1a9791674672fa4a98717b4",
    "isSecureMode" : false,
    "setup" : {
      "invite" : false,
      "chatSetup" : true,
      "userSetup" : true,
      "customizeStep" : true,
      "secureModeSetup" : false,
      "billing" : false,
      "contactListSetup" : true
    },
    "aws" : {
      "s3" : false,
      "region" : "",
      "accessKey" : "",
      "secretKey" : "",
      "userName" : "",
      "bucket" : ""
    },
    "settings" : {
      "chatEnabled" : true
    },
    "plan": "free",
    "status" : "active",
    "createdOn" : "2017-01-04T13:47:32.001Z",
    "updatedOn" : "2017-01-04T13:47:32.001Z"
}
Field Meaning
_id A unique identifier of the application.
companyId A unique identifier of the company this application belongs to.
name Application name. By default same as company subdomain.
hashSecret Secret key, that used in client side authentication.
isSecureMode Force secure mode, enabled by default when .
plan Could be ‘free’ or 'standard’.
setup Boolean list with completed Getting Started wizard steps on admin.
aws Amazon S3 settings for custom attachments storage
settings.chatEnabled Used for A/B testing. When set to false - chat won’t show for users by default and can be enabled manually using admin interface.
status 'active’ or 'archived’.
createdOn Date, when application was created.
updatedOn Date of the last update.

User

User object represents chat user. Api allows to retrieve users.

The user object

Example user object:

{
    "_id" : "5899c4a7928682005b34ad13",
    "appId" : "57a1bfdbde",
    "vendorId" : "272827",
    "firstName" : null,
    "lastName" : null,
    "username" : "Kristopher Kirlin III",
    "avatarUrl" : "https://s3.amazonaws.com/uifaces/faces/twitter/mutlu82/128.jpg",
    "email" : null,
    "isDemo" : true,
    "groupId" : "131023",
    "companyId" : null,
    "companyName" : null,
    "status": "active",
    "onlineStatus" : {
      "lastActiveOnConnection" : "2017-02-07T12:59:19.791Z",
      "lastActiveOnPage" : "2017-02-07T12:59:19.791Z",
      "isOnline" : true
    },
    "updatedOn" : "2017-02-07T12:59:19.791Z",
    "stats" : {
      "lastMessageTime" : null,
      "contactsCount" : 0,
      "conversationsCount" : 0,
      "totalMessagesCount" : 0
    },
    "userSettings" : {},
    "settings" : {
        "chatEnabled" : true
    },
    "createdOn" : "2017-02-07T12:59:19.791Z"
}
Field Description
_id A unique identifier of the user.
appId Id of the application
vendorId UserId provided by the vendor
firstName First name of a user.
lastName Last name of a user.
username Username used in chat as display name
avatarUrl A url to the user profile provided by vendor. Chat users can change avatar in chat later.
email A user email, provided by vendor.
status Status of user. Could be active or archived.
isDemo Internal setting. Used to mark auto-generated users on landing site.
groupId A string, provided by vendor during chat integration. Used to automatically build contact lists for group of users.
companyId Optional companyId, provided by vendor. Mainly used to provide per company statistic.
companyName Optional company name, provided by vendor.
onlineStatus.lastActiveOnConnection Time of the last chat ping sent by the chat widget
onlineStatus.lastActiveOnPage Time of the last user activity on a page (clicks or mousemoves)
onlineStatus.isOnline Boolean, used to immediately set offline status of user, that closed browser tab with chat.
stats General statistic on a chat usage.
userSettings.avatarUrl Avatar, uploaded by user. If exists chat widget will use it over the avatarUrl provided by vendor
userSettings.notifications.newMessageSound Boolean, indicates whether sound notifications enabled or not.
userSettings.notifications.unreadMessageEmail Boolean, indicates whether email notifications enabled or not.
userSettings.timezone Time zone which is used for messages in a chat and in email notifications.
settings.chatEnabled Boolean, which indicates whether chat enabled for user or not

Get users list

Definition: GET https://api.maqpie.com/users

# Request Example
curl "https://api.maqpie.com/users?appId=YOUR_APP_ID&sortBy=username" \
-H "Authorization: Bearer YOUR_API_SECRET"

Example response:

{
   "pagesCount":1,
   "count":13,
   "results":[{
         "_id":"586cfedead6bc0005cb5c19e",
         "appId":"57a1bfdbde",
         "vendorId":"uladzimir-mitskevich",
         "firstName":"John",
         "lastName":"Doe",
         "username":"john13",
         "avatarUrl":"https://s3.amazonaws.com/uifaces/faces/twitter/bfrohs/128.jpg",
         "email":"john@maqpie.com",
         "isDemo":null,
         "groupId":"1",
         "companyId":"586cfed8ad6bc0005cb5c199",
         "companyName":"company1",
         "onlineStatus":{
            "lastActiveOnPage":"2017-02-08T10:37:44.367Z",
            "lastActiveOnConnection":"2017-02-08T10:38:03.985Z",
            "isOnline":false
         },
         "stats":{
            "lastMessageTime":"2017-02-07T20:44:06.625Z",
            "contactsCount":5,
            "conversationsCount":3,
            "totalMessagesCount":27,
            "changed":true
         },
         "settings":{
            "chatEnabled":true
         },
         "userSettings":{ },
         "createdOn":"2017-01-04T13:47:32.001Z",
         "updatedOn":"2017-02-07T20:39:26.219Z"
      },
      {},
      {}
   ]
}

All query parameters are optional.

Query Parameters Description
page Page to return. Each page return 25 items.
sortBy Field name which will be used as sort parameter. Could be one of the following: username, companyName, stats.lastMessageTime, stats.contactsCount, stats.conversationsCount, stats.totalMessagesCount. Default: onlineStatus.lastActiveOnPage.
sortDirection Sort direction. Could be ‘asc’ or 'desc’. Default: desc.
searchTerm Search text. Used to search users with specific username.
groupId Group id.
companyId Company id.

Response with list of user’s objects.

Retrieve a user

Return a user object by identifier.

Definition: GET https://api.maqpie.com/users/:userId?appId=YOUR_APP_ID

# Request Example
curl "https://api.maqpie.com/users/586cfedead6bc0005cb5c19e?appId=YOUR_APP_ID" \
-H "Authorization: Bearer YOUR_API_SECRET"

Example response:

{
    "_id":"586cfedead6bc0005cb5c19e",
    "appId":"57a1bfdbdev",
    "vendorId":"uladzimir-mitskevich",
    "firstName":"John",
    "lastName":"Doe",
    "username":"john13",
    "avatarUrl":"https://s3.amazonaws.com/uifaces/faces/twitter/bfrohs/128.jpg",
    "email":"john@maqpie.com",
    "isDemo":null,
    "groupId":"1",
    "companyId":"586cfed8ad6bc0005cb5c199",
    "companyName":"company1",
    "onlineStatus":{
       "lastActiveOnPage":"2017-02-08T10:37:44.367Z",
       "lastActiveOnConnection":"2017-02-08T10:38:03.985Z",
       "isOnline":false
    },
    "stats":{
       "lastMessageTime":"2017-02-07T20:44:06.625Z",
       "contactsCount":5,
       "conversationsCount":3,
       "totalMessagesCount":27,
       "changed":true
    },
    "settings":{
       "chatEnabled":true
    },
    "userSettings":{ },
    "createdOn":"2017-01-04T13:47:32.001Z",
    "updatedOn":"2017-02-07T20:39:26.219Z"
 }

Integration

Integration API allows to create or update user, import and archive/restore users from your API.

Create or update a user

Create or update chat user. Chat widget call this api method every time, when user refresh a page. If user data changes - it will be automatically updated.

Every change to the user automatically propagated through the our real time api to the all connected clients. For example, you can use this method to update user’s firstName in a chat when it changed in your product. Otherwise, user will see updated firstName only when page is refreshed.

Definition: PUT https://api.maqpie.com/integration/users

# Request Example
curl https://api.maqpie.com/integration/users?appId=YOUR_APP_ID \
-H "Authorization: Bearer YOUR_API_SECRET" \
-X PUT \
-d 'username=john' \
-d 'email=support@maqpie.com' \
-d 'vendorUserId=vendorUserId' \
-d 'groupId=1'

Example response:

{
   "_id":"589ca0ae45d937014bec5b56",
   "appId":"57a1bfdbde",
   "vendorId":"vendorUserId",
   "firstName":null,
   "lastName":null,
   "username":"john",
   "profileUrl":null,
   "avatarUrl":null,
   "email":"support@maqpie.com",
   "isDemo":null,
   "groupId":"1",
   "companyId":null,
   "companyName":null,
   "onlineStatus":{
      "lastActiveOnConnection":"2017-02-09T17:02:38.833Z",
      "lastActiveOnPage":"2017-02-09T17:02:38.833Z",
      "isOnline":true
   },
   "updatedOn":"2017-02-09T17:02:38.833Z",
   "stats":{
      "lastMessageTime":null,
      "contactsCount":0,
      "conversationsCount":0,
      "totalMessagesCount":0
   },
   "userSettings":{

   },
   "settings":{
      "chatEnabled":true
   },
   "createdOn":"2017-02-09T17:02:38.833Z"
}

Important notes:

  1. Either username or firstName are required. If username is missing, fistName and lastName are used as username.
  2. GroupId can be used to setup a contact lists for your users. Users with same groupId will automatically appear in contact list of each other and will be able to start chatting right away. At the moment groupId can not be changed. First groupId is used to setup contact list.
Body parameters Description
firstName First name of a user. From 1 to 50 characters. Optional.
lastName Last name of a user. From 1 to 50 characters. Optional.
username Username of a user. From 1 to 50 characters. Optional.
email Email of user. Required.
avatarUrl URL to avatar of user. Optional.
company.id Vendor company identifier. Used to split chat statistic data into companies.
company.name Optional vendor company name.
groupId A string, provided by vendor during chat integration. Used to automatically build contact lists for group of users.
settings.chatEnabled Boolean, which indicates whether chat enabled for user or not
userSettings.defaultTimezone A string with time zone identifier (e.g America/New_York). It’s using to initially set a time zone.
vendorUserId Unique id of a user.

Partial user update

Definition: PUT https://api.maqpie.com/integration/users

# Request Example
curl https://api.maqpie.com/integration/users?appId=YOUR_APP_ID \
-H "Authorization: Bearer YOUR_API_SECRET" \
-X PUT \
-d 'username=john' \
-d 'email=support@maqpie.com' \
-d 'vendorUserId=vendorUserId'

In some cases it more convenient to update users partially. Here are full list of supported partial updates:

Body parameters Description
vendorUserId Unique id of a user. Required.
firstName First name of a user
lastName Last name of a user
username Username used in chat as display name
avatarUrl A url to the user profile provided by vendor. Chat users can change avatar in chat later.
email User’s email
companyId Vendor company identifier. Used to split chat statistic data into companies.
companyName Vendor company name.
settings.chatEnabled Disable or enable chat for the user
userSettings.timezone Time zone which is using for messages in chat and in email notifications
userSettings.notifications.newMessageSound Disable or enable sound notifications
userSettings.notifications.unreadMessageEmail Disable or enable email notifications

Bulk users add

Bulk user api allow you to import up to 100 users in a single request. There are few cases where you might need it:

  1. When chat deployed, contacts will gradually appears as users login to your system. In many cases you would want to have all user contacts be available right away.
  2. In cases where can’t use a groupId to automatically setup contact lists you’ll need to import users and setup contact lists using contact list api

Definition: POST https://api.maqpie.com/integration/users/bulk-add?appId=YOUR_APP_ID

# Request Example
curl "https://api.maqpie.com/integration/users/bulk-add?appId=YOUR_APP_ID" \
-d '{"users": [{"vendorId":"1","username":"john","email":"support@maqpie.com"}]}' \
-H "Authorization: Bearer YOUR_API_SECRET"
Body parameters Description
users An array of users data. See User fields table below for more details.
User fields Description
vendorId Vendor specific user identifier. Should not change over the time.
firstName First name of a user. From 1 to 50 characters. Optional.
lastName Last name of a user. From 1 to 50 characters. Optional.
username Username of a user. From 1 to 50 characters. Optional.
email Email of user. Required.
avatarUrl URL to avatar of user. Optional.
company.id Vendor company identifier. Used to split chat statistic data into companies.
company.name Optional vendor company name.
settings.chatEnabled Boolean, which indicates whether chat enabled for user or not

Note: Bulk api does not create contact lists. To create contact lists use Contact List api

Archive user

Definition: POST https://api.maqpie.com/integration/users/:vendorUserId/archive?appId=YOUR_APP_ID

# Request Example
curl "https://api.maqpie.com/integration/users/586cfed8ad6bc0005cb5c199/archive?appId=YOUR_APP_ID" \
-H "Authorization: Bearer YOUR_API_SECRET"

This endpoint can be used to archive user.

Important notes:

  1. You can archive only active user.
  2. This endpoint operates around vendor user id. You no need to fetch user to get his id. Just pass user id from your system and we will match them with our on our end.
  3. After archiving user will be removed from all group conversations.
  4. Personal conversations with that user will be archived too.

Respond with an empty object.

Restore user

Definition: POST https://api.maqpie.com/integration/users/:vendorUserId/restore?appId=YOUR_APP_ID

# Request Example
curl "https://api.maqpie.com/integration/users/586cfed8ad6bc0005cb5c199/restore?appId=YOUR_APP_ID" \
-H "Authorization: Bearer YOUR_API_SECRET"

This endpoint can be used to restore user.

Important notes:

  1. You can restore only archived user.
  2. This endpoint operates around vendor user id. You no need to fetch user to get his id. Just pass user id from your system and we will match them with our on our end.
  3. After restoring user will get his old contact list.
  4. Personal conversations with that user(if another participant is active) will be restored too.

Respond with an empty object.

Update user contacts

This endpoint can be used to update all contacts for a single user. You can use this endpoint to completely replace user contacts.

Note: This endpoint operates around vendor user ids. You no need to fetch users after bulk import to get their ids. Just pass user ids from your system and we will match them with our on our end.

Definition: POST https://api.maqpie.com/integration/users/:vendorUserId/contacts/update?appId=YOUR_APP_ID

# Request Example
curl "https://api.maqpie.com/integration/users/586cfed8ad6bc0005cb5c199/contacts/update?appId=YOUR_APP_ID" \
-d '{"contactIds": ["586cfed8ad6bc0005cb5c110"]}' \
-H "Authorization: Bearer YOUR_API_SECRET"
Body parameters Description
contactIds New list of user contacts.

Respond with an empty object.

Add user contacts

This endpoint can be used to add contacts to the user.

Note: This endpoint operates around vendor user ids. You no need to fetch users after bulk import to get their ids. Just pass user ids from your system and we will match them with our on our end.

Definition: POST https://api.maqpie.com/integration/users/:vendorUserId/contacts/add?appId=YOUR_APP_ID

# Request Example
curl "https://api.maqpie.com/integration/users/586cfed8ad6bc0005cb5c199/contacts/add?appId=YOUR_APP_ID" \
-d '{"contactIds": ["586cfed8ad6bc0005cb5c110"]}' \
-H "Authorization: Bearer YOUR_API_SECRET"
Body parameters Description
contactIds An array of vendor user ids.

Respond with an empty object.

Remove user contacts

This endpoint can be used to remove user contacts.

Note: This endpoint operates around vendor user ids. You no need to fetch users after bulk import to get their ids. Just pass user ids from your system and we will match them with our on our end.

Definition: POST https://api.maqpie.com/integration/users/:vendorUserId/contacts/remove?appId=YOUR_APP_ID

# Request Example
curl "https://api.maqpie.com/integration/users/586cfed8ad6bc0005cb5c199/contacts/remove?appId=YOUR_APP_ID" \
-d '{"contactIds": ["586cfed8ad6bc0005cb5c110"]}' \
-H "Authorization: Bearer YOUR_API_SECRET"
Body parameters Description
contactIds An array of vendor ids of users that you want to remove.

Respond with an empty object.

Contact List

The contact list object represent list of all contacts for a give user. The contact object is a ‘short’ version of a user object. Any user can send a personal message only if another user is in his contact list. If user is in contact list he could also be invited into group conversations.

Empty contact list is created every time when you create a new user.

The contact list object

Contact List object example:

[
   {
      "userId":"586cfed9ad6bc0005cb5c19c",
      "vendorId":"john",
      "firstName":"John",
      "lastName":"Doe",
      "username":"John Doe",
      "onlineStatus":{
         "lastActiveOnPage":"2017-01-04T13:59:00.319Z",
         "lastActiveOnConnection":"2017-01-04T15:16:06.175Z",
         "isOnline":false
      },
      "groupId":"1",
      "avatarUrl":"https://s3.amazonaws.com/uifaces/faces/twitter/leehambley/128.jpg",
      "userSettings":{}
   },
   {}
]
Field Meaning
_id Equal to _id of user to that the contact belongs.
appId An application contact list belongs to.
vendorId User identifier provided by the vendor
firstName First name of the user
lastName Last name of the user
username Username used in chat as display name
onlineStatus Object, representing user online status. See User object.
groupId See User object for details.

Retrieve a contact list by userId

Return a contact list by user identifier.

Definition: GET https://api.maqpie.com/users/:userId/contacts

# Request Example
curl "https://api.maqpie.com/users/586cfedead6bc0005cb5c19e/contacts?appId=YOUR_APP_ID" \
-H "Authorization: Bearer YOUR_API_SECRET"

Response Example:

{
  "results": [
     {
        "userId":"586cfed9ad6bc0005cb5c19c",
        "vendorId":"john",
        "firstName":"John",
        "lastName":"Doe",
        "username":"John Doe",
        "onlineStatus":{
           "lastActiveOnPage":"2017-01-04T13:59:00.319Z",
           "lastActiveOnConnection":"2017-01-04T15:16:06.175Z",
           "isOnline":false
        },
        "groupId":"1",
        "avatarUrl":"https://s3.amazonaws.com/uifaces/faces/twitter/leehambley/128.jpg",
        "userSettings":{}
     },
     {}
  ]
}

Company

This object represent a company, user belong to. The company identifier and name can be supplied optionally as part of create or update user request.

If you are running SaaS application or want to split all your chat users into smaller chunks - company is for you. Our admin panel provides a data analytics per company. So you can evaluate which companies are using chat and which are not.

Also, you can turn chat off on a company level (for all users within same company).

The company object

Company Object Example:

{
    "_id" : "586cfed8ad6bc0005cb5c199",
    "appId" : "57a1bfdbde",
    "vendorId" : "1234",
    "name" : "Maqpie",
    "settings" : {
        "chatEnabled" : true
    },
    "createdOn" : "2017-01-04T13:55:36.183Z",
    "stats" : {
        "lastOnlineTime" : "2017-02-17T12:41:58.609Z",
        "conversationsCount" : 8,
        "totalMessagesCount" : 92,
        "totalUsersCount" : 6
    }
}
Field Meaning
_id A unique identifier for the company.
appId An application company belongs to.
name Company name.
vendorId Identifier of the company provided by vendor
stats General statistic on a chat usage for the given company
settings.chatEnabled Enable or disable chat for user. Disabling chat for the company automatically disables chat for all users within the company.
createdOn Date of company creation
updatedOn Date of the last company update

Get companies list

Get list of the all companies

Definition: GET https://api.maqpie.com/companies

# Request Example
curl "https://api.maqpie.com/companies?appId=YOUR_APP_ID" \
-H "Authorization: Bearer YOUR_API_SECRET"
Query Parameters Info
page Page to return. Each page return 25 items.
sortBy Field name which will be used as sort parameter. Could be one of the following: name, stats.lastOnlineTime, stats.totalUsersCount, stats.conversationsCount, stats.totalMessagesCount.
sortDirection Sort direction. Could be asc or desc. Default: desc.

Response example

{
   "pagesCount":1,
   "results":[
      {
         "_id":"586cfed8ad6bc0005cb5c199",
         "appId":"57a1bfdbde",
         "vendorId":"1234",
         "name":"Maqpie",
         "settings":{
            "chatEnabled":true
         },
         "createdOn":"2017-01-04T13:55:36.183Z",
         "stats":{
            "lastOnlineTime":"2017-02-17T12:41:58.609Z",
            "conversationsCount":8,
            "totalMessagesCount":92,
            "totalUsersCount":6,
            "changed":true
         }
      },
      {}
   ],
   "count": 5
}

Get company by id

Return a company by id

Definition: GET https://api.maqpie.com/companies/:companyId

# Request Example
curl "https://api.maqpie.com/companies/586cfed8ad6bc0005cb5c199?appId=YOUR_APP_ID" \
-H "Authorization: Bearer YOUR_API_SECRET"

Response example

{
   "_id":"586cfed8ad6bc0005cb5c199",
   "appId":"57a1bfdbde",
   "vendorId":"1234",
   "name":"Maqpie",
   "settings":{
      "chatEnabled":true
   },
   "createdOn":"2017-01-04T13:55:36.183Z",
   "stats":{
      "lastOnlineTime":"2017-02-17T12:41:58.609Z",
      "conversationsCount":8,
      "totalMessagesCount":92,
      "totalUsersCount":6,
      "changed":true
   }
}

Update a company

At the moment, the only part of the company you can update is a chatEnabled setting, which controls chat availability for the users from this company.

Definition: POST https://api.maqpie.com/companies/:companyId

# Request Example
curl https://api.maqpie.com/companies/586cfed8ad6bc0005cb5c199?appId=YOUR_APP_ID \
-H "Authorization: Bearer YOUR_API_SECRET" \
-X POST \
-d 'chatEnabled=false'

Here are full list of supported partial updates:

Body parameters Description
chatEnabled Disable or enable chat for the all users within the company

Response example

{
   "_id":"586cfed8ad6bc0005cb5c199",
   "appId":"57a1bfdbde",
   "vendorId":"1234",
   "name":"Maqpie",
   "settings":{
      "chatEnabled":false
   },
   "createdOn":"2017-01-04T13:55:36.183Z",
   "stats":{
      "lastOnlineTime":"2017-02-17T12:41:58.609Z",
      "conversationsCount":8,
      "totalMessagesCount":92,
      "totalUsersCount":6,
      "changed":true
   }
}