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": "unpaid",
    "isTrial": true,
    "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 ‘unpaid’ or 'paid’.
isTrial	If the trial period has’t passed - `true`.
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",
   "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:

Either username or firstName are required. If username is missing, fistName and lastName are used as username.
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:

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.
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:

You can archive only active user.
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.
After archiving user will be removed from all group conversations.
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:

You can restore only archived user.
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.
After restoring user will get his old contact list.
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.

Create conversation

This endpoint can be used to create a conversation.

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/conversations

# Request Example
curl "https://api.maqpie.com/integration/conversations" \
-d '{"participantIds": ["andrew-orsich", "nikita-sergeevich", "evgeny-marushko"], title: "conversation"}' \
-H "Authorization: Bearer YOUR_API_SECRET"

Example response:

{
  "_id": "5bd076b8a4ce43074a465388",
  "createdOn": "2018-10-24T13:42:16.836Z"
}

Body parameters	Description
participantIds	An array of vendor ids of users that you want add to conversation. Length must be greater than 3. Required.
title	Conversation title. Optional.
creatorId	User `vendorId` that will be the creator of the conversation. Optional.

Add users to conversation

Add users to the conversation using vendor ids. Users may or may not be in the contacts of each other to communicate together.

Definition: POST https://api.maqpie.com/integration/conversations/:conversationId/participants/add

# Request Example
curl -H "Content-Type: application/json" -X POST -d '{"userId":"string","participantIds":["string"]}' \
https://api.maqpie.com/integration/conversations/:conversationId/participants/add

Arguments	Meaning
participantIds	An array of vendor ids of users that you want add to conversation. Required.

Response with empty object.

Remove users from conversation

Removes users to the conversation using vendor ids.

Definition: POST https://api.maqpie.com/integration/conversations/:conversationId/participants/remove

# Request Example
curl -H "Content-Type: application/json" -X POST -d '{"userId":"string","participantIds":["string"]}' \
https://api.maqpie.com/integration/conversations/:conversationId/participants/remove

Arguments	Meaning
participantIds	An array of vendor ids of users that you want remove from conversation. Required.

Response with 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
   }
}

Conversation

A conversation object represent a conversation between two or more users. Every chat message belongs to a particular conversation. Using api you can create conversation, update conversation title, add or remove other members to the conversation, mark all messages as read for the particular user within conversation. How to create a conversation, see above.

The conversation object

Conversation Object Example:

{
    "_id" : "58871aa2127578005b9ee077",
    "participantsHash" : "641723779551cdd7a8fe0d0e51afd4f4",
    "lastMessage" : {
        "_id" : "58a84bc7d08a000061566973",
        "userId" : "586cfed8ad6bc0005cb5c19a",
        "content" : "That was really good",
        "sentOn" : "2017-02-18T13:27:35.509Z",
        "isSystem" : null,
        "attachments" : [],
        "index" : 14
    },
    "participants" : {
        "58871966127578005b9ee074" : {
            "userId" : "58871966127578005b9ee074",
            "username" : "Chris Duggan",
            "avatarUrl" : "https://s3.amazonaws.com/uifaces/faces/twitter/moscoz/128.jpg",
            "onlineStatus" : {
                "lastActiveOnPage" : "2017-01-24T10:19:32.685Z",
                "lastActiveOnConnection" : "2017-01-24T10:20:29.015Z",
                "isOnline" : true
            },
            "userSettings" : {},
            "unreadMessagesCount" : 11,
            "firstName" : "Chris",
            "lastName" : "Duggan",
            "showMessagesFromDate": "1970-01-01T00:00:00.000"
        },
        "586cfed8ad6bc0005cb5c19a": {}
    },
    "messagesCount" : 15,
    "participantIds" : [
        "586cfed8ad6bc0005cb5c19a",
        "58871966127578005b9ee074"
    ],
    "appId" : "YOUR_APP_ID",
    "userId" : "58871966127578005b9ee074",
    "title" : null,
    "status": "active",
    "type" : "personal"
}

Field	Meaning
_id	A unique identifier for the conversation.
appId	An application conversation belongs to.
userId	Identifier of the user, who created conversation.
title	The title of conversation.
status	Status of conversation. Could be `active` or `archived`.
type	Could be ‘personal’ or 'group’.
messagesCount	The total count of the messages in this conversation.
participantsHash	A unique hash of the conversation. Used internally to make that same to members can have only one conversation between them.
participants	A hash map with userId as a key and short version of user. See above.
participantIds	A list of user ids within conversation.
createdOn	When conversation was created.
updatedOn	When conversation was updated.

Participant inner object:

Field	Description
userId	A unique identifier of the user.
avatarUrl	A url to the user avatar 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.
userSettings.avatarUrl	An avatar of the user, upload through the chat.
unreadMessagesCount	Number of unread messages by this user.
firstName	First name of a user.
lastName	Last name of a user.
username	Username used in chat as display name.
showMessagesFromDate	A date from which participant can see conversation history.

Get conversations list

Return a conversation list for given user.

Definition: GET https://api.maqpie.com/integration/conversations/

# Request Example
curl "http://lvh.me:8081/integration/conversations?perPage=4&page=2" \
  -H "Authorization: Bearer YOUR_API_SECRET"

Support token and hash authentications.

Arguments	Meaning
participantId	If it was sent search conversations with this participant. Optional.
perPage	The number of conversations returned per request. Optional. By default 25.
page	Page to return. By default 1.

Response Example:

{
  "pagesCount": 2,
  "results": [{
    "_id" : "58871aa2127578005b9ee077",
    "participantsHash" : "641723779551cdd7a8fe0d0e51afd4f4",
    "lastMessage" : {
      "_id" : "58a84bc7d08a000061566973",
      "userId" : "586cfed8ad6bc0005cb5c19a",
      "content" : "That was really good",
      "sentOn" : "2017-02-18T13:27:35.509Z",
      "isSystem" : null,
      "attachments" : [],
      "index" : 14
    },
    "participants" : {
      "58871966127578005b9ee074" : {
        "userId" : "58871966127578005b9ee074",
        "username" : "Chris Duggan",
        "avatarUrl" : "https://s3.amazonaws.com/uifaces/faces/twitter/moscoz/128.jpg",
        "onlineStatus" : {
          "lastActiveOnPage" : "2017-01-24T10:19:32.685Z",
          "lastActiveOnConnection" : "2017-01-24T10:20:29.015Z",
          "isOnline" : true
        },
        "userSettings" : {},
        "unreadMessagesCount" : 11,
        "firstName" : "Chris",
        "lastName" : "Duggan",
        "showMessagesFromDate": "1970-01-01T00:00:00.000"
      },
      "586cfed8ad6bc0005cb5c19a": {}
    },
      "messagesCount" : 15,
      "participantIds" : [
        "586cfed8ad6bc0005cb5c19a",
        "58871966127578005b9ee074"
      ],
      "appId" : "YOUR_APP_ID",
      "userId" : "58871966127578005b9ee074",
      "title" : null,
      "status": "active",
      "type" : "personal"
    },
    {}
  ],
  "count": 5
}

If user was removed from conversation that object is replaced by removedFromConversation object. removedFromConversation is conversation object in moment of removing.

Mark conversation as read

Definition: POST https://api.maqpie.com/conversations/:conversationId/mark-as-read

# Request Example
curl -X POST -d '{"userId":"string"}' \
  https://api.maqpie.com/conversations/:conversationId/mark-as-read

Set zero unreadMessagesCount for user. Also marks as 'read' all messages in this conversation for user.

Support token and hash authentications.

Arguments	Meaning
userId	Id of a user for whom need to mark messages as 'read’. Required.

Response with conversation object.

Add users to conversation

Definition: POST https://api.maqpie.com/conversations/:conversationId/participants/add

# Request Example
curl -H "Content-Type: application/json" -X POST -d '{"userId":"string","participantIds":["string"]}' \
  https://api.maqpie.com/conversations/:conversationId/participants/add

Support token and hash authentications.

If participantIds count equal to 0 or if some of participantIds are not in user’s contacts or if conversation is 'personal' or if user is not a member of conversation or if conversation doesn’t exist request will fail.

Arguments	Meaning
userId	Id of a user who is initiator of an action. Required.
participantIds	Array of user’s identifiers. Required.

Response with empty object.

Remove users from conversation

Definition: POST https://api.maqpie.com/conversations/:conversationId/participants/remove

# Request Example
curl -H "Content-Type: application/json" -X POST -d '{"userId":"string","participantIds":["string"]}' \
  https://api.maqpie.com/conversations/:conversationId/participants/remove

Support token and hash authentications.

If participantIds count equal to 0 or if some of participantIds are not in user’s contacts or if conversation is 'personal' or if user is not a member of conversation or if some of participantIds are not an identifiers of conversation’s participants or if conversation doesn’t exist request will fail.

Arguments	Meaning
userId	Id of a user who is initiator of an action. Required.
participantIds	Array of user’s identifiers. Required.

Response with empty object.

Rename conversation

Definition: POST https://api.maqpie.com/conversations/:conversationId/rename

# Request Example
curl -H "Authorization: Bearer YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-X POST -d '{"userId":"string","newTitle":"string"}' \
  https://api.maqpie.com/conversations/:conversationId/rename

Support token and hash authentications.

If conversation is 'personal' or if user is not a member of conversation or if conversation doesn’t exist request will fail.

Arguments	Meaning
userId	Id of a user who is initiator of an action. Required.
newTitle	New title of conversation. From 1 to 100 characters. Required.

Response with empty object.

Open conversation

Definition: POST https://api.maqpie.com/conversations/:conversationId/open

# Request Example
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_SECRET" \
-X POST \
https://api.maqpie.com/conversations/:conversationId/open

Returns an empty object.

Close conversation

Definition: POST https://api.maqpie.com/conversations/:conversationId/close

# Request Example
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_SECRET" \
-X POST \
https://api.maqpie.com/conversations/:conversationId/close

Returns an empty object.

Settings

Settings object

Settings object is the part of user data.

<script>
var MP = {
  data: {
    appId: "your_app_id",
    user: {
      username: "username",
      firstName: "firstname",
      lastName: "lastname",
      email: "email@email.com",
      userId: "userid"
    },
    userHash: "userhash"
  },
  settings: { // SETTINGS OBJECT
    // settings
  }
}
</script>

Example settings object:

{
  "demoMode": false,
  "disableExpand": false,
  "disableChatWhenNoContacts": true,
  "use24TimeFormat": false,
  "showOnlineContactsFirst": true,
  "collapsedHeaderTitle": "Development chat",
  "styles": {
    "headerColor": "#3dc8fa",
    "headerSelectedIconColor": "#98feff",
    "unreadConversationsCountColor": "",
    "avatarBorderColor": "#3dc8fa",
    "avatarOnlineColor": "#06ab61",
    "avatarAwayColor": "#d4d410",
    "scrollColor": "#3dc8fa",
    "headerTextColor": "#fff",
    "fontFamily": "Open Sans, sans-serif"
  },
  "position": {
    "right": "15px",
    "bottom": "15px"
  },
  "mode": "",
  "containerId": ""
}

Field	Default	Description
demoMode	false	If set to true, a chat will be demo.
disableExpand	false	If set to true, an opportunity to expand a chat will be disabled.
disableChatWhenNoContacts	false	If set to true, a chat won’t be shown if user doesn’t have contacts.
use24TimeFormat	false	If set to true, a chat will use the 24-hour clock system, otherwise the 12-hour.
showOnlineContactsFirst	false	If set to true, chat contacts will be sorted by online status, otherwise by username.
collapsedHeaderTitle	Last opened page (Contacts, Profile and etc.)	String, Header title when a chat was collapsed.
autoRender	true	If set to false, a сhat will not be rendered automatically.
changeIcon	true	If set to false, a chat will not change the favicon.
disableConversationManagement	false	If set to true, users cannot manage group conversations and cannot see the contact list.
styles	{}	Customization a chat styles.
styles.headerColor	“#3dc8fa”	A primary chat color affects header, icons and buttons style.
styles.headerSelectedIconColor	“#98feff”	A color affect the selected page icon.
styles.unreadConversationsCountColor	“”	A color affects background counter unread messages, conversations.
styles.avatarBorderColor	“#3dc8fa”	A color affects the border avatar.
styles.avatarOnlineColor	“#06ab61”	A color affects the online indicator.
styles.avatarAwayColor	“#d4d410”	A color affects the away indicator.
styles.scrollColor	“#3dc8fa”	A scroll color affects the scroll on conversations, contacts and search screens.
styles.headerTextColor	“#fff”	A color affects the header text.
styles.forwardedMessageBorderColor	“#9999ff”	A color affects the left border of the forwarded message.
styles.fontFamily	“Open Sans, sans-serif”	A font family affects the text used in a chat.
position	{}	Absolute position for a chat widget.
position.right	“15px”	Right position. Right option has higher priority.
position.left	“”	Left position.
position.bottom	“15px”	Bottom position.
mode	“”	Set `embedded`, if you don’t want to render small widget but just embedded large chat.
containerId	“”	String, a chat will be rendered inside this container.

Public JavaScript API

Use the JavaScript API to improve the integration of Maqpie into your own web applications. Here are some things you can do with the JavaScript API:

Manage navigation
Manage messaging
Control UI actions
Manage a chat in embedded mode

MP.navigateToConversations();

MP.navigateToConversations()

Open conversations view.

MP.navigateToContacts();

MP.navigateToContacts()

Open contacts view.

MP.navigateToPersonalConversation('vendor_id');

MP.navigateToPersonalConversation(participantVendorId)

Open one-to-one conversation with the user with given id, userId is id from your system.

Parameter	Type	Description
participantVendorId	String	Required. Participant id provided by the vendor.

Messaging

MP.sendPersonalMessage('vendor_id', 'Hello world!');

MP.sendPersonalMessage(participantVendorId, text)

Send message to one-to-one conversation.

Parameter	Type	Description
participantVendorId	String	Required. Participant id provided by the vendor.
text	String	Required. Message text.

MP.messagesRead('vendor_id');

MP.messagesRead(participantVendorId)

Read messages in one-to-one conversation with the user with given vendor id.

Parameter	Type	Description
participantVendorId	String	Required. Participant id provided by the vendor.

UI actions

MP.collapseChat();

MP.collapseChat()

Minimize a chat widget.

MP.uncollapseChat();

MP.uncollapseChat()

Open widget from minimized state.

MP.openFullscreenMessenger();

MP.openFullscreenMessenger()

Open fullscreen messenger.

MP.openWidgetMessenger();

MP.openWidgetMessenger()

Open widget messenger.

MP.focusTextarea();

MP.focusTextarea()

Put cursor in input field in opened conversation.

MP.toggleSidebar();

MP.toggleSidebar()

Open or close sidebar in a chat widget.

MP.enableAutoFocus();

MP.enableAutoFocus()

Enable autofocus property for input fields.

MP.disableAutoFocus();

MP.disableAutoFocus()

Disable autofocus property for input fields.

MP.disallowBrowserNotifications();

MP.disallowBrowserNotifications()

Disallow browser notifications. User won’t receive notifications.

MP.disableGuideScreenOverlay();

MP.disableGuideScreenOverlay()

Disable screen overlay in guide view.

MP.renderWidget();

MP.renderWidget()

Manually render a chat.

MP.destroyWidget();

MP.destroyWidget()

Manually destroy a chat.

Embedded mode

MP.renderLargeView('html_container_id');

MP.renderLargeView(container)

Render a chat into html component.

Parameter	Type	Description
container	String	Required. Id of container.

MP.showLargeView();

MP.showLargeView()

Make a chat visible.

MP.destroyLargeView();

MP.destroyLargeView()

Destroy a chat and free up resources.

MP.subscribe('unreadMessagesCountChanged', function (count) {
  // update your view
});

MP.subscribe('unreadMessagesCountChanged', cb)

You can subscribe to unread messages count changes. Callback receives number of unread messages as a parameter. It will be invoked immediately when a chat is ready.

Parameter	Type	Description
event	String	Required. Name of event.
callback	function	Required. Callback.

MP.unsubscribe();

MP.unsubscribe()

Remove event listeners.

MP.getUnreadMessagesCount();

MP.getUnreadMessagesCount()

Get unread messages count manually. Works only after a chat has been loaded.

Overview

Introduction

Vulnerability & Improvement Rewards

Authentication

Errors

HTTP status code summary

Application

The application object

User

The user object

Get users list

Retrieve a user

Integration

Create or update a user

Partial user update

Bulk users add

Archive user

Restore user

Update user contacts

Add user contacts

Remove user contacts

Create conversation

Add users to conversation

Remove users from conversation

Contact List

The contact list object

Retrieve a contact list by userId

Company

The company object

Get companies list

Get company by id

Update a company

Conversation

The conversation object

Get conversations list

Mark conversation as read

Add users to conversation

Remove users from conversation

Rename conversation

Open conversation

Close conversation

Settings

Settings object

Public JavaScript API

Navigation

Messaging

UI actions

Embedded mode