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

2. Organizations

The Organization resource represents a company on behalf of which chats are performed. Organizations are the primary resource in the ChatShipper system. Most other resources are tied to exactly one organization.

Each Organization is part of an organization hierarchy. At the top (level 1) are Messaging Contact Centers. An MCC's customer organization (level 2) can themselves have sub-organizations (level 3, leaf nodes).

Create an Organization

When authenticated as an MCC admin, you can add organizations and sub-organizations.

Request: POST /v2/organizations

{
  "name": "Acme Corp"
}

Response: 201 Created

{
  "id": "590bcf50458b716046347f36",
  "name": "Acme Corp",
  "email": "",
  "status": "active",
  "stopwords": [],
  "categories": [],
  "parent": "563f8098396c50df77857b6d",
  "path": "563f8098396c50df77857b6d#59178cb1c63934459825dee3",
  "level": 2,
  "createdAt": "2017-05-13T22:46:09.154Z",
  "updatedAt": "2017-05-13T22:46:09.154Z"
}

Note that optional fields like country or meta are only included in the results if specified when the record was created or updated.

Create a Sub-Organization

The above request created a "level-2" account organization with the MCC itself as a parent. Your Acme Corp client may have a subsidiary called "Acme Netherlands B.V."; create this as a sub-organization (level-3) like this:

Request: POST /v2/organizations

{
    "name": "Acme Netherlands B.V.",
    "parent": "59178cb1c63934459825dee3",
    "displayName": "Acme NL",
    "url": "https://example.com",
    "email": "info@example.com",
    "country": "NL",
    "logo": "https://example.com/logo.png",
    "industry": "automotive",
    "stopwords": ["penis", "vagina"],
    "categories": [{ "name": "Sales" }, { "name": "Support" }],
    "commands": ["inruilbot", "vr"],
    "profileFields": {
        "givenName": { "label": "Voornaam", "enabled": true },
        "familyName": { "label": "Achternaam", "enabled": true },
        "additionalName": { "label": "Tussenvoegsels", "enabled": true },
        "email": { "label": "E-mail", "enabled": true }
    }
}

Response: 201 Created

{
    "id": "5917ab8cc63934459825deec",
    "name": "Acme Netherlands B.V.",
    "parent": "59178cb1c63934459825dee3",
    "path": "563f8098396c50df77857b6d#59178cb1c63934459825dee3#5917ae73c63934459825deee",
    "level": 3,
    ... (other attribs emitted for brevity) ...
}

Organization Properties

Note the following organization attributes:

  • parent indicates the parent organization. If omitted, the organization will be created as a child of the organization the API user is active for. When creating the Acme Corp in our first example, the MCC automatically became parent.
  • displayName is shown in the agent UI.
  • stopwords show a warning in the agent UI when typed.
  • categories are conversation tags, of which at most one can be active, and which may have forms attached.
  • commands is a list of bot commands that is shown to agents.
  • profileFields allows disabling some contact profile fields, and giving them custom labels. If not specified, all possible contact profile fields are made available, with sensible English, Dutch or German labels (based on organization country).
  • name, url, email, industry and logo are currently not used by ChatShipper, but this may change in the future. For now, you can put anything you want in there.

As said, for profileFields, by default (if unspecified), all contact profile fields are enabled. Default labels provided for Dutch (organizations with country 'NL'), German (country 'DE' or 'CH') and English (all other countries) are:

Field English Dutch German
givenName First Name Voornaam Vorname
additionalName Middle Name Tussenvoegsel Einf├╝gung
familyName First Name Achternaam Eigenname
honorificPrefix Prefix Voorvoegsel Vorfuchsel
honorificSuffix Suffix Achtervoegsel Hinterfuchsel
gender Gender Geslacht Geschlagt
worksFor Company Bedrijf Betrieb
telephone Phone Telefoon Telefon
email Email E-mail Email
address.streetAddress Street Straatnaam StraBname
address.streetNumber Number Nummer Nummer
address.postalCode Zip Code Postcode Post Kode
address.addressLocality City Plaats Stadt
address.addressRegion Region Provincie Staatsbuchanwalt
address.addressCountry Country Land Land

Note that these language strings are the only multi-language features currently available in the agent UI. If you override the defaults by explicitly specifying a profileFields object when creating an organization, you'll have to specify a custom label for each profile property that you need.

Create an Organization Group

Organizations may be grouped into Organization Groups. They work like tags - each organization can be a member of multiple groups.

It's advisable to manage organizations by assigning them to Organization Groups. This allows you to (later on) apply workflows to these groups, instead of just single organizations.

Let's create an Organization Group for the MCC with both Acme and its subsidiary as its members. We could name this group Acme Group, should specific workflows for Acme organizations be designed, but for now the MCC simply groups by industry, with two members initially. This group is called Automotive:

Request: POST /v2/orggroups

{
    "name": "Automotive",
    "members": [
        "59178cb1c63934459825dee3",
        "5917ab8cc63934459825deec"
    ]
}

Response: 201 Created

{
    "id": "5917af88c63934459825deef",
    "organization": "563f8098396c50df77857b6d",
    "orgPath": "563f8098396c50df77857b6d",
    "name": "Automotive",
    "members": [
        "59178cb1c63934459825dee3",
        "5917ab8cc63934459825deec"
    ],
    "updatedAt": "2017-05-14T01:14:48.783Z",
    "createdAt": "2017-05-14T01:14:48.783Z"
}

MCC agents can now be enabled to handle conversations for all Acme organizations; by creating workflows for "Automotive" group members, conversations on behalf of those group members can be routed to specific channels.

Cross-organization Resource Sharing

Resources like articles and forms can be provided to child organizations by using the same tags for the child organization and the resources you want to share.

Organization Tags

Create groups of organizations by tagging any of the MCC's child organizations:

Request: PATCH /v2/organizations/590bcf50458b716046347f36

{
    "tags": ["nl-aut-retail"]
}

Sharing Articles and other knowledge items

To share any articles, files or locations with your tagged organizations, simply assign the same tags:

Request: PATCH /v2/articles/5d2e6e5d52f2835f96dbc729

{
    "tags": ["nl-aut-retail"]
}

Sharing Forms as Templates

In a similar way, forms can be provided to tagged organizations. Shared forms will appear as form templates to start new forms from.

Request: PATCH /v2/forms/5d38d3753c75975c7532aa6c

{
    "tags": ["nl-aut-retail"]
}

Within the ChatShipper user interface only MCC admins are allowed to edit resource tags.


2. Organizations


Suggested Edits are limited on API Reference Pages

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