The ChatShipper Developer Hub

Welcome to the ChatShipper developer hub. You'll find comprehensive guides and documentation to help you start working with ChatShipper as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

3. Users and Channels

Users

Users are people or apps that can log into ChatShipper. A User resource specifies the profile, permissions, preferences and login credentials for ChatShipper registered viewers, agents, admin users and bots.

User Roles

Each user is assigned a specific role within each of the organizations (and its sub-organizations) the user is active for. The following roles, in ascending order of permissions, are available:

  • viewer: a registered user with limited viewing rights;
  • agent: a human full participant in conversations;
  • bot: a non-human/automation participant in conversations;
  • admin: a human user with administrative rights

Each role corresponds to an authentication scope by the same name, and has the associated cascasding permissions attached; for example, an agent logging in will have its authentication token loaded with the 'viewer' and 'agent' permissions. See the
chapter on Authentication for more information.

Create an MCC agent

Readily actived agents can be added to your MCC organization by adding a complete user login account:

Request: POST /v2/users

{
    "givenName": "Joe",
    "familyName": "Johnson",
    "email":"agent007@sis.gov.uk",
    "password": "t0pZ3kR3t",
    "status": "active"
}

Response: 201 Created

{
  "id": "591789e5c63934459825dede",
  "givenName": "Joe",
  "familyName": "Johnson",
  "email": "agent007w@sis.gov.uk",
  "organizations": [
    {
      "orgPath": "563f8098396c50df77857b6d",
      "organization": "563f8098396c50df77857b6d",
      "selected": true,
      "role": "agent"
    }
  ],
  "status": "active",
  "avatar": "/images/avatar.png",
  "updatedAt": "2017-05-13T22:34:13.920Z",
  "createdAt": "2017-05-13T22:34:13.920Z",
}

As an alternative to setting and distributing passwords like this,
a user may be invited by email to finish the registration process. Let's do that next.

Create an Organization agent

Let's create a fully loaded user account, and invite an agent to activate this account for the Acme Corp organization by setting the invite flag:

Request: POST /v2/users

{
    "organization": "590bcf50458b716046347f36",
    "role": "agent",
    "email":"johhny@acme-corp.org",
    "givenName": "John",
    "familyName": "Doe",
    "displayName": "Johnny D.",
    "avatar": "http://example.com/images/avatar.png",
    "settings": {
        "timezone": "Europe/Amsterdam"
    },
    "meta": {
        "some_key": "Some Value"
    },
    "invite": true
}

Response: 201 Created

{
  "givenName": "John",
  "familyName": "Doe",
  "displayName": "Johnny D.",
  "email": "devos@brooklyn.nl",
  "provider": "admin",
  "organizations": [
    {
      "orgPath": "aaa111111111111111111111#590bcf50458b716046347f36",
      "organization": "590bcf50458b716046347f36",
      "selected": true,
      "role": "agent"
    }
  ],
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": false,
    "localeSet": false,
    "locale": "en_EN"
  },
  "status": "queued",
  "avatar": "http://example.com/images/avatar.png",
  "updatedAt": "2017-05-13T23:18:15.374Z",
  "createdAt": "2017-05-13T23:18:15.374Z",
  "name": "John Doe",
  "id": "59179437c63934459825dee5"
}

This results in having invited agent "John Doe", for him to login and activate his account.

View the current user

As a side note, be aware that you can always get the current user (yourself) using:

Request: GET /v2/users/me

{
    "id": "59abeb8c55f0992165e691fc",
    "name": "John Johnson",
    "givenName": "John",
    "familyName": "Johnson",
    "email": "admin@example.com",
    "organizations": [
        {
            "orgPath": "563f8098396c50df77857b6d",
            "organization": {
                "name": "Awesome MCC",
                "displayName": "Awesome MCC",
                "id": "563f8098396c50df77857b6d"
            },
            "selected": true,
            "role": "admin",
            "level": 1
        }
    ],
    "settings": {
        "timezone": "Europe/Amsterdam",
        "timezoneSet": false,
        "localeSet": false,
        "locale": "nl_NL",
        "notifyOnChat": false,
        "audioOnChat": true
    },
    "status": "active",
    "avatar": "/images/avatar.png",
    "lastLogin": "2017-09-06T10:14:09.651Z",
    "createdAt": "2017-09-05T18:54:15.087Z",
    "updatedAt": "2017-09-06T14:35:35.202Z"
}

Channels

Users may be assigned to Queue Notification Channels. This allows an agent to subscribe to those channels to receive notifications of new chat requests (the "queue"). When an agent unsubscribes from a channel, he/she will stop receiving channel notifications.

Create a new MCC Channel

Request: POST /v2/channels

{
    "name": "Switchboard"
}

> Response: 201 Created

```json
{
  "organization": "563f8098396c50df77857b6d",
  "name": "Switchboard",
  "status": "active",
  "members": [],
  "updatedAt": "2017-05-13T23:26:41.067Z",
  "createdAt": "2017-05-13T23:26:41.067Z",
  "id": "59179631c63934459825deea"
}

Add the MCC agent to the Channel

Since members is a full API resource, we can add, update and delete individual channel members using this endpoint.

Request: POST /v2/channels/59179631c63934459825deea/members

{
    "user": "591789e5c63934459825dede"
}

Create another Channel and add the MCC agent as a member

Instead of creating an empty channel and using the members collection like above, we can provide a member list on Channel creation in one step:

Request: POST /v2/channels

{
  "name": "Used Car",
  "members": [
    {
      "user": "591789e5c63934459825dede"
    }
  ]
}

After accepting the invitation, the agent can now login and subscribe to these channels. Let's setup routing using Workflows to direct incoming messages to these Switchboard and Used Car channels.


3. Users and Channels


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.