Back to top

ChatShipper API Reference

Authentication

All API requests are made on behalf of a registered User. An API request should always include the Authorization: Bearer _token_ header in the request HTTP headers list.

Example of valid API requests using cURL utility:

$ curl -H "Authorization: Bearer 94c70d470e391bdc16a8d8363b5d4891" \
       https://api.chatshipper.com/v2/path/to/resource

API tokens that are tied to a user with role “bot” do not expire, but may be revoked. The API key has the permissions of the associated user, and actions appear as if they were that user. If the associated user has its permissions changed, such as being removed from an organization, then the functionality of the key will change.

We recommend that different systems have different API tokens (bot users) for security purposes.

Time-based Tokens

ChatShipper supports time-based tokens that expire after a set amount of time. These tokens are tied to the user session, and used primarily in our applications.

Create an Access Token
POST/auth/token

To obtain an access token, make a POST request to https://api.chatshipper.com/v2/auth/token. The users’s email and password must be used in a JSON object posted to the token API URL.

The token expires after 24 hours; use the refresh token flow before expiration. After expiration a new token should be generated.

Example URI

POST https://api2.chatshipper.com/v2/auth/token
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "jeff@jeffdoe.com",
  "password": "z3krut"
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "tokenType": "Bearer",
  "token": "eyK8eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1NDUwMDBlNTZkYWU2NzQxMTVjZWYyN2MiLCJpYXQiOjE0MTc0NjQzNDksImV4cCI6MTQxNzQ4MjM0OX0._ihtI_m5vf53m_qF0y_m-y_5X9Hy8Ik2A5qUTSkgNhA",
  "refreshToken": "eyK8eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1NDUwMDBlNTZkYWU2NzQxMTVjZWYyN2MiLCJpYXQiOjE0MTc0NjQzNDksImV4cCI6MTQxNzQ4MjM0OX0._ihtI_m5vf53m_qF0y_m-y_5X9Hy8Ik2A5qUTSkgNhA",
  "user": "599e1fcd9da1c72645c95886",
  "organization": "57c8479433f5d57d3013a0bc",
  "expiresAt": "2016-01-07T14:03:43Z",
  "scope": "admin"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tokenType": {
      "type": "string",
      "description": "Token type."
    },
    "token": {
      "type": "string",
      "description": "Authentication token. Expires after 24h."
    },
    "refreshToken": {
      "type": "string",
      "description": "Authentication token for refresh authentication. Expires after 1 month."
    },
    "user": {
      "type": "string",
      "description": "The ID of the User authenticated."
    },
    "organization": {
      "type": "string",
      "description": "Authenticated user organization ID."
    },
    "expiresAt": {
      "type": "string",
      "description": "ISO8601 date ant ime when token expires."
    },
    "scope": {
      "type": "string",
      "description": "Authenticated user scope."
    }
  }
}

Refresh an Access Token
GET/auth/token?{refreshToken}

Use the refresh token to request a new access token prior to expiration.

Example URI

GET https://api2.chatshipper.com/v2/auth/token?refreshToken
URI Parameters
HideShow
refreshToken
string (required) 

Refresh token.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "tokenType": "Bearer",
  "token": "eyK8eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1NDUwMDBlNTZkYWU2NzQxMTVjZWYyN2MiLCJpYXQiOjE0MTc0NjQzNDksImV4cCI6MTQxNzQ4MjM0OX0._ihtI_m5vf53m_qF0y_m-y_5X9Hy8Ik2A5qUTSkgNhA",
  "refreshToken": "eyK8eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJfaWQiOiI1NDUwMDBlNTZkYWU2NzQxMTVjZWYyN2MiLCJpYXQiOjE0MTc0NjQzNDksImV4cCI6MTQxNzQ4MjM0OX0._ihtI_m5vf53m_qF0y_m-y_5X9Hy8Ik2A5qUTSkgNhA",
  "user": "599e1fcd9da1c72645c95886",
  "organization": "57c8479433f5d57d3013a0bc",
  "expiresAt": "2016-01-07T14:03:43Z",
  "scope": "admin"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tokenType": {
      "type": "string",
      "description": "Token type."
    },
    "token": {
      "type": "string",
      "description": "Authentication token. Expires after 24h."
    },
    "refreshToken": {
      "type": "string",
      "description": "Authentication token for refresh authentication. Expires after 1 month."
    },
    "user": {
      "type": "string",
      "description": "The ID of the User authenticated."
    },
    "organization": {
      "type": "string",
      "description": "Authenticated user organization ID."
    },
    "expiresAt": {
      "type": "string",
      "description": "ISO8601 date ant ime when token expires."
    },
    "scope": {
      "type": "string",
      "description": "Authenticated user scope."
    }
  }
}

Provisioning

The Provisioning APIs provide methods for configuring primary entities in the system for proper account setup.

Users

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

A User object has the following attributes:

Property Type Description Example
id string The unique ID of the user. 57c8479433f5d57d3013a0bc
familyName string Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property. Vries
givenName string Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property. Hans
additionalName string An additional name for a User, can be used for a middle name. de
displayName string Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName. Hans de Vries
email string* Email address of the User, used to log in. jeff@jeffdoe.com
phone string User telephone number. +31209876543
password string Login password for the User. z3krUt
avatar string Avatar URL for the User. http:///images/avatar.png
organization string The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations. 55dcf8aa048ee2227d4aa1a4
role enum The role of the agent within the organization. One of agent, admin, owner. Defaults to agent. agent
settings Settings User preferences. {Settings}
meta MetaParams Free-form object of key-values, that will be passed on to external systems, eg in webhook data. {MetaParams}
status enum The status of the user for given organization. One of queued, invited, active, archived. Defaults to queued. queued
apiToken string API key for role ‘bot’ users. eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV
lastLogin string ISO8601 date and time of when the user last logged in. 2016-08-05T08:40:51.620Z
createdAt string ISO8601 date and time of when the user was created. 2016-01-07T14:03:43Z
updatedAt string ISO8601 date and time of when the user was last modified. 2016-01-07T14:03:43Z

Person name conventions are adapted from JSON-LD standards as specified by Google and described at Schema.org.

The user.settings object specifies user preferences and may have the following properties:

Property Type Description Example
timezone string Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in. Europe/Amsterdam
timezoneSet boolean Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system). Defaults to false. false
locale enum ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location. One of en, nl, de, fr. Defaults to en. en
localeSet boolean Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system). Defaults to false. false
audioOnChat boolean Boolean to bleep on queue increments. Defaults to true. true
audioOnMessage boolean Boolean to bleep on new messages. Defaults to false. false
notifyOnChat boolean Boolean to show desktop notifications on queue increments. Defaults to false. false
notifyOnMessage boolean Boolean to show a desktop notification on each incoming message. Defaults to false. false

List All Users
GET/users

Return a list of all account users (agents and admins).

Example URI

GET https://api2.chatshipper.com/v2/users
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "57c8479433f5d57d3013a0bc",
    "familyName": "Vries",
    "givenName": "Hans",
    "additionalName": "de",
    "displayName": "Hans de Vries",
    "email": "jeff@jeffdoe.com",
    "phone": "+31209876543",
    "password": "z3krUt",
    "avatar": "http:///images/avatar.png",
    "organization": "55dcf8aa048ee2227d4aa1a4",
    "role": "agent",
    "settings": {
      "timezone": "Europe/Amsterdam",
      "timezoneSet": true,
      "locale": "en",
      "localeSet": true,
      "audioOnChat": true,
      "audioOnMessage": true,
      "notifyOnChat": true,
      "notifyOnMessage": true
    },
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "status": "queued",
    "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
    "lastLogin": "2016-08-05T08:40:51.620Z",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create a New User
POST/users

You may create a user using this action. It takes a JSON object containing a name, email and password, and optional settings, role and/or organization.

Example URI

POST https://api2.chatshipper.com/v2/users
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http:///images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    }
  },
  "required": [
    "email"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /users/57c8479433f5d57d3013a0bc
Body
{
  "id": "57c8479433f5d57d3013a0bc",
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http:///images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
  "lastLogin": "2016-08-05T08:40:51.620Z",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    },
    "apiToken": {
      "type": "string",
      "description": "API key for role 'bot' users."
    },
    "lastLogin": {
      "type": "string",
      "description": "ISO8601 date and time of when the user last logged in."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was last modified."
    }
  },
  "required": [
    "email"
  ]
}

User

Retrieve a User
GET/users/{user_id}

View a User. Get the currently authenticated User by issuing a request for GET /users/me.

Example URI

GET https://api2.chatshipper.com/v2/users/user_id
URI Parameters
HideShow
user_id
number (required) 

ID of the User, or the string ‘me’ to return the current user.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "57c8479433f5d57d3013a0bc",
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http:///images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
  "lastLogin": "2016-08-05T08:40:51.620Z",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    },
    "apiToken": {
      "type": "string",
      "description": "API key for role 'bot' users."
    },
    "lastLogin": {
      "type": "string",
      "description": "ISO8601 date and time of when the user last logged in."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was last modified."
    }
  },
  "required": [
    "email"
  ]
}

Update a User
PATCH/users/{user_id}

You may edit a user using this action. It takes a (possibly partial) JSON object containing one or more of the user attributes.

Example URI

PATCH https://api2.chatshipper.com/v2/users/user_id
URI Parameters
HideShow
user_id
number (required) 

ID of the User, or the string ‘me’ to return the current user.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http:///images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    }
  },
  "required": [
    "email"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "57c8479433f5d57d3013a0bc",
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http:///images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
  "lastLogin": "2016-08-05T08:40:51.620Z",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    },
    "apiToken": {
      "type": "string",
      "description": "API key for role 'bot' users."
    },
    "lastLogin": {
      "type": "string",
      "description": "ISO8601 date and time of when the user last logged in."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was last modified."
    }
  },
  "required": [
    "email"
  ]
}

Retrieve user organizations
GET/users/me/organizations

Return a list of currently authenticated user organizations.

Example URI

GET https://api2.chatshipper.com/v2/users/me/organizations
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "57c8479433f5d57d3013a0bc",
  "organizations": [
    {
      "organization": "55dcf8aa048ee2227d4aa1a4",
      "role": "agent",
      "selected": true
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "organizations": {
      "type": "array",
      "description": "A list of user organizations (boolean)."
    }
  }
}

Remove organization from user
DELETE/users/{user_id}/organizations/{organization_id}

Remove user from organizations list.

Example URI

DELETE https://api2.chatshipper.com/v2/users/user_id/organizations/organization_id
URI Parameters
HideShow
user_id
string (required) 

ID of the User.

organization_id
string (required) 

ID of the Organization.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Delete a User
DELETE/users/{user_id}

Sets the archived bit for a User, which will prevent it from coming up in listings and search results, but will keep internal references intact to preserve system data integrity.

Example URI

DELETE https://api2.chatshipper.com/v2/users/user_id
URI Parameters
HideShow
user_id
number (required) 

ID of the User, or the string ‘me’ to return the current user.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

User Avatar

Upload a User Avatar
POST/users/{user_id}/avatar

Upload a user profile image into cloud storage. The image will be resized and cropped.

Example URI

POST https://api2.chatshipper.com/v2/users/user_id/avatar
URI Parameters
HideShow
user_id
string (required) 

ID of the User.

Request
HideShow
Headers
Content-Type: multipart/form-data;boundary=---BOUNDARY
Authorization: Bearer <token>
Body
---BOUNDARY--
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg
Content-Transfer-Encoding: base64

/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z
-----BOUNDARY
Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "57c8479433f5d57d3013a0bc",
  "familyName": "Vries",
  "givenName": "Hans",
  "additionalName": "de",
  "displayName": "Hans de Vries",
  "email": "jeff@jeffdoe.com",
  "phone": "+31209876543",
  "password": "z3krUt",
  "avatar": "http:///images/avatar.png",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "role": "agent",
  "settings": {
    "timezone": "Europe/Amsterdam",
    "timezoneSet": true,
    "locale": "en",
    "localeSet": true,
    "audioOnChat": true,
    "audioOnMessage": true,
    "notifyOnChat": true,
    "notifyOnMessage": true
  },
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "status": "queued",
  "apiToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV",
  "lastLogin": "2016-08-05T08:40:51.620Z",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the user."
    },
    "familyName": {
      "type": "string",
      "description": "Family name or surname. In the U.S. and most of Europe, the last name of an User. This can be used along with givenName instead of the displayName property."
    },
    "givenName": {
      "type": "string",
      "description": "Given name. In the U.S. and most of Europe, the first name of a User. This can be used along with familyName instead of the displayName property."
    },
    "additionalName": {
      "type": "string",
      "description": "An additional name for a User, can be used for a middle name."
    },
    "displayName": {
      "type": "string",
      "description": "Name of the User as it will be displayed in user interfaces. If not provided, this will be composed by concatenating givenName, additionalName and familyName."
    },
    "email": {
      "type": "string",
      "description": "Email address of the User, used to log in."
    },
    "phone": {
      "type": "string",
      "description": "User telephone number."
    },
    "password": {
      "type": "string",
      "description": "Login password for the User."
    },
    "avatar": {
      "type": "string",
      "description": "Avatar URL for the User."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization the user belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "role": {
      "type": "string",
      "enum": [
        "agent",
        "admin",
        "owner"
      ],
      "default": "agent",
      "description": "The role of the agent within the organization."
    },
    "settings": {
      "type": "object",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "Timezone preference for displaying relative dates/times, specified as one of the Zones in the IANA Time Zone Database (https://www.iana.org/time-zones). If not specified, this will be auto-set the first time the user logs in."
        },
        "timezoneSet": {
          "type": "boolean",
          "description": "Boolean indicating that the timezone has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "locale": {
          "type": "string",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "default": "en",
          "description": "ISO 639-1 language code. If not specified, this setting will be inferred by the system based on user-agent settings and/or user IP location."
        },
        "localeSet": {
          "type": "boolean",
          "description": "Boolean indicating that the locale has been manually set by the user (as opposed to inferred by the system).",
          "default": false
        },
        "audioOnChat": {
          "type": "boolean",
          "description": "Boolean to bleep on queue increments.",
          "default": true
        },
        "audioOnMessage": {
          "type": "boolean",
          "description": "Boolean to bleep on new messages.",
          "default": false
        },
        "notifyOnChat": {
          "type": "boolean",
          "description": "Boolean to show desktop notifications on queue increments.",
          "default": false
        },
        "notifyOnMessage": {
          "type": "boolean",
          "description": "Boolean to show a desktop notification on each incoming message.",
          "default": false
        }
      },
      "description": "User preferences."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "invited",
        "active",
        "archived"
      ],
      "default": "queued",
      "description": "The status of the user for given organization."
    },
    "apiToken": {
      "type": "string",
      "description": "API key for role 'bot' users."
    },
    "lastLogin": {
      "type": "string",
      "description": "ISO8601 date and time of when the user last logged in."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the user was last modified."
    }
  },
  "required": [
    "email"
  ]
}

Delete the User Avatar
DELETE/users/{user_id}/avatar

Delete the avatar image from cloud storage and set the User’s avatar property to null.

Example URI

DELETE https://api2.chatshipper.com/v2/users/user_id/avatar
URI Parameters
HideShow
user_id
string (required) 

ID of the User.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Organizations

The Organization resource represents a company on behalf of which chats are performed.

Organizations are the primary resource in the ChatShipper system. Other resources are tied to exactly one organization.

An Organization record has the following attributes:

Property Type Description Example
id string The unique ID of the Organization. 56467a06d9b082b0059151dc
name string* The name of the Organization. Acme Inc.
displayName string Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name. Acme Inc.
status enum Organization status. One of queued, active, pendingArchive, archived. Defaults to active. queued
email string An email address for users to contact support in case of any issues with the organization. support@example.com
url string The URL of the Organization’s corporate website. https://example.com
logo string The URL of the Organization’s logo image. https://example.com/logo.png
country string The two-letter ISO 3166 country code of the Organization’s headquarters. NL
locale enum ISO 639-1 two-letter language code. One of en, nl, de, fr. Defaults to en. en
timezone string Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam. Europe/Amsterdam
domainPrefix string The white label subdomain part for the organization. skynet
domain string The white label domain for the organization. chat.report
industry string The industry the Organization is in. automotive
categories array List of categories and form mappings, used in the agent UI. [{Category Full}]
profileFields ProfileFields An object mirroring the contact profile, representing profile field labels for various locales. {ProfileFields}
stopwords array List of words that should not be used in any communication on behalf of the Organization. [foo]
commands array List of custom (bot) commands that should be made available to the agent. [intakebot]
tags array List of keywords/tags for the organization. [automotive]
emailAs string An email ‘from’ sender address for results notifications. results@example.com
meta MetaParams Free-form object of key-values, that will be passed on to external systems, eg in webhook data. {MetaParams}
createdAt string ISO8601 date and time of when the Organization was created. 2016-01-07T14:03:43Z
updatedAt string ISO8601 date and time of when the Organization was last modified. 2016-01-07T14:03:43Z

Categories

The categories attribute specifies which categories, and for each category which forms are used in the agent console. Each organization may have up to 10 categories, and each category occupies one of 10 ‘slots’ in the category list. Each slot is represented by a color in the UI. A category may be null, meaning the slot is not occupied.

Categories may be managed by the categories organization sub-resource. To change the category order, however, or to replace null-value slots with actual categories, the Organization resource itself needs to be updated (using PATCH /organizations/:id).

Each category has the following properties:

Property Type Description Example
id string The unique ID of the Category. 5877a5ecb6b1bc76263e0a85
name string* The name of the Category. Used Car
forms array A list of Form IDs that may be used for this category. [55dcf8aa048ee2227d4aa1a4]
tags array List of keywords/tags for the category. [automotive]

Profile Fields

The profileFields attribute specifies which contact profile fields are used by the organization. This object mirrors the data structure of the contact profile.

Property Type Description Example
name ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
initials ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
givenName ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
familyName ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
additionalName ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
honorificPrefix ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
honorificSuffix ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
gender ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
address ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
telephone ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
email ProfileFieldLabel A profile field label object. {ProfileFieldLabel}

The address object has the following properties:

Property Type Description Example
streetAddress ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
streetNumber ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
addressLocality ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
addressRegion ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
postalCode ProfileFieldLabel A profile field label object. {ProfileFieldLabel}
addressCountry ProfileFieldLabel A profile field label object. {ProfileFieldLabel}

Each field is an object with the following properties:

Property Type Description Example
label string* A label for the profile field. Field Label
options array An array of option labels, only applicable to the gender profile field. [male]
enabled boolean Flag signifying if this localized label is enabled. Defaults to true. true

List All Organizations
GET/organizations

Return a list of all organizations.

Example URI

GET https://api2.chatshipper.com/v2/organizations
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "56467a06d9b082b0059151dc",
    "name": "Acme Inc.",
    "displayName": "Acme Inc.",
    "status": "queued",
    "email": "support@example.com",
    "url": "https://example.com",
    "logo": "https://example.com/logo.png",
    "country": "NL",
    "locale": "en",
    "timezone": "Europe/Amsterdam",
    "domainPrefix": "skynet",
    "domain": "chat.report",
    "industry": "automotive",
    "categories": [
      {
        "id": "5877a5ecb6b1bc76263e0a85",
        "name": "Used Car",
        "forms": [
          "55dcf8aa048ee2227d4aa1a4",
          "55dcf8aa048ee2227d4aa1b6"
        ],
        "tags": [
          "automotive",
          "insurance"
        ]
      }
    ],
    "profileFields": {
      "name": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "initials": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "givenName": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "familyName": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "additionalName": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "honorificPrefix": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "honorificSuffix": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "gender": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "address": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "telephone": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      },
      "email": {
        "label": "Field Label",
        "options": [
          "male",
          "female"
        ],
        "enabled": true
      }
    },
    "stopwords": [
      "foo",
      "bar"
    ],
    "commands": [
      "intakebot",
      "surveybot"
    ],
    "tags": [
      "automotive",
      "insurance"
    ],
    "emailAs": "results@example.com",
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create a New Organization
POST/organizations

You may create a organization using this action.

Example URI

POST https://api2.chatshipper.com/v2/organizations
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "industry": "automotive",
  "categories": [
    {
      "id": "5877a5ecb6b1bc76263e0a85",
      "name": "Used Car",
      "forms": [
        "55dcf8aa048ee2227d4aa1a4",
        "55dcf8aa048ee2227d4aa1b6"
      ],
      "tags": [
        "automotive",
        "insurance"
      ]
    }
  ],
  "profileFields": {
    "name": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "initials": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "givenName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "familyName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "additionalName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificPrefix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificSuffix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "gender": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "address": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "telephone": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "email": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    }
  },
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "categories": {
      "type": "array",
      "description": "List of categories and form mappings, used in the agent UI."
    },
    "profileFields": {
      "type": "object",
      "properties": {
        "name": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "initials": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "givenName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "familyName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "additionalName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificPrefix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificSuffix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "gender": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "address": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "telephone": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "email": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        }
      },
      "description": "An object mirroring the contact profile, representing profile field labels for various locales."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    }
  },
  "required": [
    "name"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /organizations/56467a06d9b082b0059151dc
Body
{
  "id": "56467a06d9b082b0059151dc",
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "industry": "automotive",
  "categories": [
    {
      "id": "5877a5ecb6b1bc76263e0a85",
      "name": "Used Car",
      "forms": [
        "55dcf8aa048ee2227d4aa1a4",
        "55dcf8aa048ee2227d4aa1b6"
      ],
      "tags": [
        "automotive",
        "insurance"
      ]
    }
  ],
  "profileFields": {
    "name": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "initials": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "givenName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "familyName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "additionalName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificPrefix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificSuffix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "gender": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "address": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "telephone": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "email": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    }
  },
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "categories": {
      "type": "array",
      "description": "List of categories and form mappings, used in the agent UI."
    },
    "profileFields": {
      "type": "object",
      "properties": {
        "name": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "initials": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "givenName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "familyName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "additionalName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificPrefix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificSuffix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "gender": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "address": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "telephone": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "email": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        }
      },
      "description": "An object mirroring the contact profile, representing profile field labels for various locales."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Organization

Retrieve an Organization
GET/organizations/{organization_id}

Returns a specific Organization.

Example URI

GET https://api2.chatshipper.com/v2/organizations/organization_id
URI Parameters
HideShow
organization_id
string (required) 

ID of the Organization.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "56467a06d9b082b0059151dc",
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "industry": "automotive",
  "categories": [
    {
      "id": "5877a5ecb6b1bc76263e0a85",
      "name": "Used Car",
      "forms": [
        "55dcf8aa048ee2227d4aa1a4",
        "55dcf8aa048ee2227d4aa1b6"
      ],
      "tags": [
        "automotive",
        "insurance"
      ]
    }
  ],
  "profileFields": {
    "name": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "initials": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "givenName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "familyName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "additionalName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificPrefix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificSuffix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "gender": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "address": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "telephone": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "email": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    }
  },
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "categories": {
      "type": "array",
      "description": "List of categories and form mappings, used in the agent UI."
    },
    "profileFields": {
      "type": "object",
      "properties": {
        "name": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "initials": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "givenName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "familyName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "additionalName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificPrefix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificSuffix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "gender": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "address": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "telephone": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "email": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        }
      },
      "description": "An object mirroring the contact profile, representing profile field labels for various locales."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update an Organization
PATCH/organizations/{organization_id}

Update a specific Organization.

Example URI

PATCH https://api2.chatshipper.com/v2/organizations/organization_id
URI Parameters
HideShow
organization_id
string (required) 

ID of the Organization.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "industry": "automotive",
  "categories": [
    {
      "id": "5877a5ecb6b1bc76263e0a85",
      "name": "Used Car",
      "forms": [
        "55dcf8aa048ee2227d4aa1a4",
        "55dcf8aa048ee2227d4aa1b6"
      ],
      "tags": [
        "automotive",
        "insurance"
      ]
    }
  ],
  "profileFields": {
    "name": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "initials": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "givenName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "familyName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "additionalName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificPrefix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificSuffix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "gender": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "address": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "telephone": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "email": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    }
  },
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "categories": {
      "type": "array",
      "description": "List of categories and form mappings, used in the agent UI."
    },
    "profileFields": {
      "type": "object",
      "properties": {
        "name": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "initials": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "givenName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "familyName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "additionalName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificPrefix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificSuffix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "gender": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "address": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "telephone": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "email": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        }
      },
      "description": "An object mirroring the contact profile, representing profile field labels for various locales."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    }
  },
  "required": [
    "name"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "56467a06d9b082b0059151dc",
  "name": "Acme Inc.",
  "displayName": "Acme Inc.",
  "status": "queued",
  "email": "support@example.com",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "country": "NL",
  "locale": "en",
  "timezone": "Europe/Amsterdam",
  "domainPrefix": "skynet",
  "domain": "chat.report",
  "industry": "automotive",
  "categories": [
    {
      "id": "5877a5ecb6b1bc76263e0a85",
      "name": "Used Car",
      "forms": [
        "55dcf8aa048ee2227d4aa1a4",
        "55dcf8aa048ee2227d4aa1b6"
      ],
      "tags": [
        "automotive",
        "insurance"
      ]
    }
  ],
  "profileFields": {
    "name": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "initials": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "givenName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "familyName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "additionalName": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificPrefix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "honorificSuffix": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "gender": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "address": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "telephone": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    },
    "email": {
      "label": "Field Label",
      "options": [
        "male",
        "female"
      ],
      "enabled": true
    }
  },
  "stopwords": [
    "foo",
    "bar"
  ],
  "commands": [
    "intakebot",
    "surveybot"
  ],
  "tags": [
    "automotive",
    "insurance"
  ],
  "emailAs": "results@example.com",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization."
    },
    "displayName": {
      "type": "string",
      "description": "Representative name of the Organization, to be used in external communications like chat widgets. Defaults to Organization name."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "pendingArchive",
        "archived"
      ],
      "default": "active",
      "description": "Organization status."
    },
    "email": {
      "type": "string",
      "description": "An email address for users to contact support in case of any issues with the organization."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Organization's corporate website."
    },
    "logo": {
      "type": "string",
      "description": "The URL of the Organization's logo image."
    },
    "country": {
      "type": "string",
      "description": "The two-letter ISO 3166 country code of the Organization's headquarters."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "nl",
        "de",
        "fr"
      ],
      "default": "en",
      "description": "ISO 639-1 two-letter language code."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone of the Organizational HQ, as specified in the IANA time zone (Olson) database. Default: Europe/Amsterdam."
    },
    "domainPrefix": {
      "type": "string",
      "description": "The white label subdomain part for the organization."
    },
    "domain": {
      "type": "string",
      "description": "The white label domain for the organization."
    },
    "industry": {
      "type": "string",
      "description": "The industry the Organization is in."
    },
    "categories": {
      "type": "array",
      "description": "List of categories and form mappings, used in the agent UI."
    },
    "profileFields": {
      "type": "object",
      "properties": {
        "name": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "initials": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "givenName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "familyName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "additionalName": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificPrefix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "honorificSuffix": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "gender": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "address": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "telephone": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        },
        "email": {
          "type": "object",
          "properties": {
            "label": {
              "type": "string",
              "description": "A label for the profile field."
            },
            "options": {
              "type": "array",
              "description": "An array of option labels, only applicable to the `gender` profile field."
            },
            "enabled": {
              "type": "boolean",
              "description": "Flag signifying if this localized label is enabled.",
              "default": true
            }
          },
          "required": [
            "label"
          ],
          "description": "A profile field label object."
        }
      },
      "description": "An object mirroring the contact profile, representing profile field labels for various locales."
    },
    "stopwords": {
      "type": "array",
      "description": "List of words that should not be used in any communication on behalf of the Organization."
    },
    "commands": {
      "type": "array",
      "description": "List of custom (bot) commands that should be made available to the agent."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the organization."
    },
    "emailAs": {
      "type": "string",
      "description": "An email 'from' sender address for results notifications."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems, eg in webhook data."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Delete an Organization
DELETE/organizations/{organization_id}

Delete an Organization. This method can only be called by a master Organization holder. It returns the deleted Organization on success.

Example URI

DELETE https://api2.chatshipper.com/v2/organizations/organization_id
URI Parameters
HideShow
organization_id
string (required) 

ID of the Organization.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Organization Categories

Retrieve all Organization Categories
GET/organizations/{organization_id}/categories

Returns all category objects of a specific Organization.

Example URI

GET https://api2.chatshipper.com/v2/organizations/organization_id/categories
URI Parameters
HideShow
organization_id
string (required) 

ID of the Organization.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "5877a5ecb6b1bc76263e0a85",
    "name": "Used Car",
    "forms": [
      "55dcf8aa048ee2227d4aa1a4",
      "55dcf8aa048ee2227d4aa1b6"
    ],
    "tags": [
      "automotive",
      "insurance"
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Add a Category to an Organization
POST/organizations/{organization_id}/categories

You may add a category to an Organization using this action. An organization may have up to 10 categories; if no slot is available an error will be thrown.

Example URI

POST https://api2.chatshipper.com/v2/organizations/organization_id/categories
URI Parameters
HideShow
organization_id
string (required) 

ID of the Organization.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "name": "Used Car",
  "forms": [
    "55dcf8aa048ee2227d4aa1a4",
    "55dcf8aa048ee2227d4aa1b6"
  ],
  "tags": [
    "automotive",
    "insurance"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Category."
    },
    "forms": {
      "type": "array",
      "description": "A list of Form IDs that may be used for this category."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the category."
    }
  },
  "required": [
    "name"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /organizations/56467a06d9b082b0059151dc/categories/5877a5ecb6b1bc76263e0a85
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Used Car",
  "forms": [
    "55dcf8aa048ee2227d4aa1a4",
    "55dcf8aa048ee2227d4aa1b6"
  ],
  "tags": [
    "automotive",
    "insurance"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Category."
    },
    "name": {
      "type": "string",
      "description": "The name of the Category."
    },
    "forms": {
      "type": "array",
      "description": "A list of Form IDs that may be used for this category."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the category."
    }
  },
  "required": [
    "name"
  ]
}

Retrieve a specific Organization Category
GET/organizations/{organization_id}/categories/{category_id}

Returns a specific category object of a Organization.

Example URI

GET https://api2.chatshipper.com/v2/organizations/organization_id/categories/category_id
URI Parameters
HideShow
organization_id
string (required) 

ID of the Organization.

category_id
string (required) 

ID of the category.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Used Car",
  "forms": [
    "55dcf8aa048ee2227d4aa1a4",
    "55dcf8aa048ee2227d4aa1b6"
  ],
  "tags": [
    "automotive",
    "insurance"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Category."
    },
    "name": {
      "type": "string",
      "description": "The name of the Category."
    },
    "forms": {
      "type": "array",
      "description": "A list of Form IDs that may be used for this category."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the category."
    }
  },
  "required": [
    "name"
  ]
}

Update an Organization Category
PATCH/organizations/{organization_id}/categories/{category_id}

Update a specific Organization category.

Example URI

PATCH https://api2.chatshipper.com/v2/organizations/organization_id/categories/category_id
URI Parameters
HideShow
organization_id
string (required) 

ID of the Organization.

category_id
string (required) 

ID of the category.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Used Car",
  "forms": [
    "55dcf8aa048ee2227d4aa1a4",
    "55dcf8aa048ee2227d4aa1b6"
  ],
  "tags": [
    "automotive",
    "insurance"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Category."
    },
    "name": {
      "type": "string",
      "description": "The name of the Category."
    },
    "forms": {
      "type": "array",
      "description": "A list of Form IDs that may be used for this category."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the category."
    }
  },
  "required": [
    "name"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Used Car",
  "forms": [
    "55dcf8aa048ee2227d4aa1a4",
    "55dcf8aa048ee2227d4aa1b6"
  ],
  "tags": [
    "automotive",
    "insurance"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Category."
    },
    "name": {
      "type": "string",
      "description": "The name of the Category."
    },
    "forms": {
      "type": "array",
      "description": "A list of Form IDs that may be used for this category."
    },
    "tags": {
      "type": "array",
      "description": "List of keywords/tags for the category."
    }
  },
  "required": [
    "name"
  ]
}

Remove a Category from an Organization
DELETE/organizations/{organization_id}/categories/{category_id}

Remove a category from a Organization, by replacing the category in the list with a null value. This way the order of category slots is not affected.

Example URI

DELETE https://api2.chatshipper.com/v2/organizations/organization_id/categories/category_id
URI Parameters
HideShow
organization_id
string (required) 

ID of the Organization.

category_id
string (required) 

ID of the Organization category.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Organization Groups

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

An Organization Group has the following attributes:

Property Type Description Example
id string The unique ID of the Organization Group. 5877a5ecb6b1bc76263e0a85
name string* The name of the Organization Group. Realtors
organization string The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations. 55dcf8aa048ee2227d4aa1a4
members array List of Organization IDs that are a member of this group. [5877a4a9b6b1bc76263e0a83]
createdAt string ISO8601 date and time of when the Organization Group was created. 2016-01-07T14:03:43Z
updatedAt string ISO8601 date and time of when the Organization Group was last modified. 2016-01-07T14:03:43Z

List All Organization Groups
GET/orggroups

Return a list of all Organization Groups.

Example URI

GET https://api2.chatshipper.com/v2/orggroups
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "5877a5ecb6b1bc76263e0a85",
    "name": "Realtors",
    "organization": "55dcf8aa048ee2227d4aa1a4",
    "members": [
      "5877a4a9b6b1bc76263e0a83",
      "5877a4cbb6b1bc76263e0a84"
    ],
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create a New Organization Group
POST/orggroups

You may create a organization group using this action.

Example URI

POST https://api2.chatshipper.com/v2/orggroups
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    }
  },
  "required": [
    "name"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /orggroups/5877a5ecb6b1bc76263e0a85
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization Group."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Organization Group

Retrieve an Organization Group
GET/orggroups/{group_id}

Returns a specific Organization Group.

Example URI

GET https://api2.chatshipper.com/v2/orggroups/group_id
URI Parameters
HideShow
group_id
string (required) 

ID of the Organization Group.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization Group."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update an Organization Group
PATCH/orggroups/{group_id}

Update a specific Organization Group.

Example URI

PATCH https://api2.chatshipper.com/v2/orggroups/group_id
URI Parameters
HideShow
group_id
string (required) 

ID of the Organization Group.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    }
  },
  "required": [
    "name"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "Realtors",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    "5877a4a9b6b1bc76263e0a83",
    "5877a4cbb6b1bc76263e0a84"
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Organization Group."
    },
    "name": {
      "type": "string",
      "description": "The name of the Organization Group."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Group belongs to. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "List of Organization IDs that are a member of this group."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Organization Group was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Delete an Organization Group
DELETE/orggroups/{group_id}

Delete an Organization Group.

Example URI

DELETE https://api2.chatshipper.com/v2/orggroups/group_id
URI Parameters
HideShow
group_id
string (required) 

ID of the Organization Group.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Retrieve all Organization Group members
GET/orggroups/{group_id}/members

Returns all organization IDs that are a member of a specific Organization Group.

Example URI

GET https://api2.chatshipper.com/v2/orggroups/group_id/members
URI Parameters
HideShow
group_id
string (required) 

ID of the Organization Group.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  "5877a4a9b6b1bc76263e0a83",
  "5877a4cbb6b1bc76263e0a84"
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Add organizations to a Group
POST/orggroups/{group_id}/members

You may add one or more member organizations to an Organization Group using this action.

Example URI

POST https://api2.chatshipper.com/v2/orggroups/group_id/members
URI Parameters
HideShow
group_id
string (required) 

ID of the Organization Group.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
[
  "5877a4a9b6b1bc76263e0a83",
  "5877a4cbb6b1bc76263e0a84"
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /orggroups/5877a5ecb6b1bc76263e0a85
Body
[
  "5877a4a9b6b1bc76263e0a83",
  "5877a4cbb6b1bc76263e0a84"
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Remove an organization from a Group
DELETE/orggroups/{group_id}/members/{member_id}

Remove a member organization from an Organization Group.

Example URI

DELETE https://api2.chatshipper.com/v2/orggroups/group_id/members/member_id
URI Parameters
HideShow
group_id
string (required) 

ID of the Organization Group.

member_id
string (required) 

ID of the Organization.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Services

A Service can represent any kind of connector, touchpoint, webservice or other integration that allows browsers and remote systems to enter ChatShipper’s world.

Examples are XMPP connections, website widgets, remote API calls or other communication channels. Services that are used as notification- or event channels (such as emails or webhooks) may be triggered by events, services that are used as connectors may have connection parameters specified; ChatShipper will do the right thing based on the service type.

Account managers may enable services from the organization Integrations page, where you might find sections for adding XMPP accounts and third-party service providers. Multiple services may be attached/removed to or from a conversation during its lifecycle.

A Service object has the following attributes:

Property Type Description Example
id string The unique ID of the Service. 5876bc219b9d2b54a0c464ca
organization string The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations. 5876bc219b9d2b54a0c464c9
name string* Name of the service. SmartSupp Widget
description string Description of the service. Test widget at http://domain/test-widget
type enum Supported type; service provider. One of smartsupp, intercom, smooch, twilio, mailgun, messenger, api, webhook. Defaults to webhook. smartsupp
status enum Service status. One of queued, active, disabled, pendingArchive, archived. Defaults to queued. queued
touchpoints array Consumer touchpoints supported by this service integration. [web]
params ServiceParams* Service connection parameters. {ServiceParams}
smoochId string Smooch service ID, if relevant. 58caef23feee32390091168a
smoochAppId string Smooch App ID, if relevant. app_58caef23feee32390091168a
startDate string ISO8601 date and time when the system should enable the integration by flipping the status from disabled to active. 2017-01-11T23:13:35.000Z
endDate string ISO8601 date and time when the system should disable the integration by flipping the status from disabled to active. 2017-01-11T23:13:35.000Z
meta MetaParams Free-form object of key-values. {MetaParams}
createdAt string ISO8601 date and time of when the Service was created. 2016-01-07T14:03:43Z
updatedAt string ISO8601 date and time of when the Service was last modified. 2016-01-07T14:03:43Z

The content of the params object (connection parameters) depends on the service provider. These are:

SmartSupp

The SmartSupp integration type requires XMPP connection parameters.

  • jid: uid3710@s1.smartsupp.com (string, required) - JID of the XMPP connection.

  • password: z3kRuD (string, required) - Password for the XMPP connection.

  • host: s1.smartsupp.com (string, required) - XMPP host to connect to.

  • port: 5222 (string, optional) - XMPP port to connect to. Default: 5222.

Intercom

The Intercom service integration type requires an application ID and access token, and the ID of an Intercom user. All chats will be made on behalf of this Intercom user.

  • app_id: a3sdd8g4 (string, required) - Intercom AppID

  • access_token: b2PrAP02QFIwhjQ4hbFBmKJfNDZjMV9hZTM0XzMII4FAAdABSjgxOToxOjA= (string, required) - Intercom Application Access Token

  • assignee_id: 846956 (string, required) - Intercom UserID

Smooch

Required Smooch connection parameter credentials:

  • appId: 5876bc219b9d2b54a086647fd5 (string, required) - Smooch AppID

  • keyId: app_5876bc219b9d2b5400d34558 (string) - Smooch application key

  • secret: 0BPGhSWvROXtb37fkp8Q4iJO (string) - Smooch application secret

In addition, there are two internal service types that can be configured; the webhook type needs an URL as parameter, the api service type may receive a list of scopes.

List All Services
GET/services

Return a list of all services.

Example URI

GET https://api2.chatshipper.com/v2/services
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "type": "smartsupp",
    "params": {
      "jid": "uid45669@s1.smartsupp.com",
      "password": "z3kr3d"
    }
  },
  {
    "type": "smooch",
    "params": {
      "mailto": "werkplaats@dealer.nl"
    }
  },
  {
    "type": "intercom",
    "params": {
      "headerColor": "yellow",
      "inviteText": "Stel uw vraag..."
    }
  }
]

Create a New Service
POST/services

You can create a Service integration using this action.

Example URI

POST https://api2.chatshipper.com/v2/services
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to.",
          "default": "5222"
        }
      },
      "required": [
        "jid",
        "password",
        "host"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    }
  },
  "required": [
    "name",
    "params"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /services/5876bc219b9d2b54a0c464ca
Body
{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Service."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to.",
          "default": "5222"
        }
      },
      "required": [
        "jid",
        "password",
        "host"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was last modified."
    }
  },
  "required": [
    "name",
    "params"
  ]
}

Service

Retrieve a Service
GET/services/{service_id}

Returns a specific Service integration.

Example URI

GET https://api2.chatshipper.com/v2/services/service_id
URI Parameters
HideShow
service_id
string (required) 

ID of the Service.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Service."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to.",
          "default": "5222"
        }
      },
      "required": [
        "jid",
        "password",
        "host"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was last modified."
    }
  },
  "required": [
    "name",
    "params"
  ]
}

Update a Service
PATCH/services/{service_id}

Update a Service integration using this call.

Example URI

PATCH https://api2.chatshipper.com/v2/services/service_id
URI Parameters
HideShow
service_id
string (required) 

ID of the Service.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to.",
          "default": "5222"
        }
      },
      "required": [
        "jid",
        "password",
        "host"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    }
  },
  "required": [
    "name",
    "params"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5876bc219b9d2b54a0c464ca",
  "organization": "5876bc219b9d2b54a0c464c9",
  "name": "SmartSupp Widget",
  "description": "Test widget at http://domain/test-widget",
  "type": "smartsupp",
  "status": "queued",
  "touchpoints": [
    "web",
    "email",
    "sms",
    "facebook",
    "whatsapp"
  ],
  "params": {
    "jid": "uid3710@s1.smartsupp.com",
    "password": "z3kRuD",
    "host": "s1.smartsupp.com",
    "port": "5222"
  },
  "smoochId": "58caef23feee32390091168a",
  "smoochAppId": "app_58caef23feee32390091168a",
  "startDate": "2017-01-11T23:13:35.000Z",
  "endDate": "2017-01-11T23:13:35.000Z",
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Service."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Service integration. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "name": {
      "type": "string",
      "description": "Name of the service."
    },
    "description": {
      "type": "string",
      "description": "Description of the service."
    },
    "type": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "api",
        "webhook"
      ],
      "default": "webhook",
      "description": "Supported type; service provider."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "disabled",
        "pendingArchive",
        "archived"
      ],
      "default": "queued",
      "description": "Service status."
    },
    "touchpoints": {
      "type": "array",
      "description": "Consumer touchpoints supported by this service integration."
    },
    "params": {
      "type": "object",
      "properties": {
        "jid": {
          "type": "string",
          "description": "JID of the XMPP connection."
        },
        "password": {
          "type": "string",
          "description": "Password for the XMPP connection."
        },
        "host": {
          "type": "string",
          "description": "XMPP host to connect to."
        },
        "port": {
          "type": "string",
          "description": "XMPP port to connect to.",
          "default": "5222"
        }
      },
      "required": [
        "jid",
        "password",
        "host"
      ],
      "description": "Service connection parameters."
    },
    "smoochId": {
      "type": "string",
      "description": "Smooch service ID, if relevant."
    },
    "smoochAppId": {
      "type": "string",
      "description": "Smooch App ID, if relevant."
    },
    "startDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should enable the integration by flipping the status from `disabled` to `active`."
    },
    "endDate": {
      "type": "string",
      "description": "ISO8601 date and time when the system should disable the integration by flipping the status from `disabled` to `active`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the Service was last modified."
    }
  },
  "required": [
    "name",
    "params"
  ]
}

Delete a Service
DELETE/services/{service_id}

Delete a Service integration.

Example URI

DELETE https://api2.chatshipper.com/v2/services/service_id
URI Parameters
HideShow
service_id
string (required) 

ID of the Service.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Forms

The Forms API provides methods to manage collections of fields.

A Form has the following properties:

Property Type Description Example
id string Unique identifier for the form 5656f3ca42fc302027eba5c6
organization string Organization ID of the owning organization. Defaults to the API user’s active organization. 58bcbafb8547f04f68c14bdb
name string* Name of the form Brochure
type enum Form type. A static form always stays active, while a topic is picked by the agent. One of topic, static. Defaults to topic. topic
profileFields array List of profile fields for this form [gender]
fields array List of fields for this form [{FormField Create}]
notifyEmails array A list of email addresses where form results get sent to. [support@example.com]
meta MetaParams Free-form object of key-values, that will be passed on to external systems. {MetaParams}
createdAt string ISO8601 date and time of when the form was created. 2016-01-07T14:03:43Z
updatedAt string ISO8601 date and time of when the form was last modified. 2016-01-07T14:03:43Z

The profileFields attribute specifies which contact profile fields are included in form results. The list of profileFields can be one or more of honorificPrefix, initials, honorificSuffix, gender, givenName, familyName, additionalName, streetAddress, streetNumber, postalCode, addressLocality, addressRegion, addressCountry, worksFor, email or telephone.

In addition to profile fields, a form may have one or more form-specific fields. Each field has the following properties:

Property Type Description Example
id string Unique identifier for the field. 5877ff19276f4e04db18e330
name string* Field identifier, short name to identify the field hasFacebookPage
label string HTML label to add to the field Has Facebook page
options array An array of options for select form field to display. Each option should be an object with a ‘key’ (string) and a ‘value’ (string). [{FormFieldOption}]
required boolean Field is required. Defaults to false. false
createdAt string ISO8601 date and time of when the form field was created. 2016-01-07T14:03:43Z
updatedAt string ISO8601 date and time of when the form field was last modified. 2016-01-07T14:03:43Z

List All Forms
GET/forms

Return a list of all forms for the organization and sub-organizations.

Example URI

GET https://api2.chatshipper.com/v2/forms
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "5656f3ca42fc302027eba5c6",
    "organization": "58bcbafb8547f04f68c14bdb",
    "name": "Brochure",
    "type": "topic",
    "profileFields": [
      "gender",
      "honorificPrefix",
      "honorificSuffix",
      "initials",
      "givenName",
      "familyName",
      "additionalName",
      "streetAddress",
      "streetNumber",
      "postalCode",
      "addressLocality",
      "addressRegion",
      "addressCountry",
      "worksFor",
      "email",
      "telephone"
    ],
    "fields": [
      {
        "name": "hasFacebookPage",
        "label": "Has Facebook page",
        "options": [
          {
            "key": "yes",
            "value": "Y"
          }
        ],
        "required": true
      }
    ],
    "notifyEmails": [
      "support@example.com",
      "help@example.com"
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create a new Form
POST/forms

You may create a form using this action.

Example URI

POST https://api2.chatshipper.com/v2/forms
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "hasFacebookPage",
      "label": "Has Facebook page",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    }
  },
  "required": [
    "name"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /forms/5656f3ca42fc302027eba5c6
Body
{
  "id": "5656f3ca42fc302027eba5c6",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "hasFacebookPage",
      "label": "Has Facebook page",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the form"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Form

Retrieve a Form
GET/forms/{form_id}

Returns a specific Form.

Example URI

GET https://api2.chatshipper.com/v2/forms/form_id
URI Parameters
HideShow
form_id
string (required) 

ID of the Form.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5656f3ca42fc302027eba5c6",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "hasFacebookPage",
      "label": "Has Facebook page",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the form"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update a Form
PATCH/forms/{form_id}

Update a specific Form.

Example URI

PATCH https://api2.chatshipper.com/v2/forms/form_id
URI Parameters
HideShow
form_id
string (required) 

ID of the Form.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "hasFacebookPage",
      "label": "Has Facebook page",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    }
  },
  "required": [
    "name"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5656f3ca42fc302027eba5c6",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Brochure",
  "type": "topic",
  "profileFields": [
    "gender",
    "honorificPrefix",
    "honorificSuffix",
    "initials",
    "givenName",
    "familyName",
    "additionalName",
    "streetAddress",
    "streetNumber",
    "postalCode",
    "addressLocality",
    "addressRegion",
    "addressCountry",
    "worksFor",
    "email",
    "telephone"
  ],
  "fields": [
    {
      "name": "hasFacebookPage",
      "label": "Has Facebook page",
      "options": [
        {
          "key": "yes",
          "value": "Y"
        }
      ],
      "required": true
    }
  ],
  "notifyEmails": [
    "support@example.com",
    "help@example.com"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the form"
    },
    "organization": {
      "type": "string",
      "description": "Organization ID of the owning organization. Defaults to the API user's active organization."
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "type": {
      "type": "string",
      "enum": [
        "topic",
        "static"
      ],
      "default": "topic",
      "description": "Form type. A `static` form always stays active, while a `topic` is picked by the agent."
    },
    "profileFields": {
      "type": "array",
      "description": "List of profile fields for this form"
    },
    "fields": {
      "type": "array",
      "description": "List of fields for this form"
    },
    "notifyEmails": {
      "type": "array",
      "description": "A list of email addresses where form results get sent to."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-values, that will be passed on to external systems."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Delete a Form
DELETE/forms/{form_id}

Delete a Form, including all its sub-resources.

Example URI

DELETE https://api2.chatshipper.com/v2/forms/form_id
URI Parameters
HideShow
form_id
string (required) 

ID of the Form.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Form Fields

List all Form Fields for a Form
GET/forms/{form_id}/fields

Return a list of all form fields for a Form.

Example URI

GET https://api2.chatshipper.com/v2/forms/form_id/fields
URI Parameters
HideShow
form_id
string (required) 

ID of the Form.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "5877ff19276f4e04db18e330",
    "name": "hasFacebookPage",
    "label": "Has Facebook page",
    "options": [
      {
        "key": "yes",
        "value": "Y"
      }
    ],
    "required": true,
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create a new Form Field
POST/forms/{form_id}/fields

You may add a form field to a form using this action.

Example URI

POST https://api2.chatshipper.com/v2/forms/form_id/fields
URI Parameters
HideShow
form_id
string (required) 

ID of the Form.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "name": "hasFacebookPage",
  "label": "Has Facebook page",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    }
  },
  "required": [
    "name"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /forms/5656f3ca42fc302027eba5c6/fields/5877a5ecb6b1bc76263e0a85
Body
{
  "id": "5877ff19276f4e04db18e330",
  "name": "hasFacebookPage",
  "label": "Has Facebook page",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true,
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the field."
    },
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Retrieve a Form Field
GET/forms/{form_id}/fields/{field_id}

Returns a specific Form Field for a Form.

Example URI

GET https://api2.chatshipper.com/v2/forms/form_id/fields/field_id
URI Parameters
HideShow
form_id
string (required) 

ID of the Form.

field_id
string (required) 

ID of the Form Field.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5877ff19276f4e04db18e330",
  "name": "hasFacebookPage",
  "label": "Has Facebook page",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true,
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the field."
    },
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update a Form Field
PATCH/forms/{form_id}/fields/{field_id}

Update a specific Form Field for a Form.

Example URI

PATCH https://api2.chatshipper.com/v2/forms/form_id/fields/field_id
URI Parameters
HideShow
form_id
string (required) 

ID of the Form.

field_id
string (required) 

ID of the Form Field.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "name": "hasFacebookPage",
  "label": "Has Facebook page",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    }
  },
  "required": [
    "name"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5877ff19276f4e04db18e330",
  "name": "hasFacebookPage",
  "label": "Has Facebook page",
  "options": [
    {
      "key": "yes",
      "value": "Y"
    }
  ],
  "required": true,
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the field."
    },
    "name": {
      "type": "string",
      "description": "Field identifier, short name to identify the field"
    },
    "label": {
      "type": "string",
      "description": "HTML label to add to the field"
    },
    "options": {
      "type": "array",
      "description": "An array of options for select form field to display. Each option should be an object with a 'key' (string) and a 'value' (string)."
    },
    "required": {
      "type": "boolean",
      "description": "Field is required.",
      "default": false
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time of when the form field was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Delete a Form Field
DELETE/forms/{form_id}/fields/{field_id}

Delete a Form Field from a Form.

Example URI

DELETE https://api2.chatshipper.com/v2/forms/form_id/fields/field_id
URI Parameters
HideShow
form_id
string (required) 

ID of the Form.

field_id
string (required) 

ID of the Form Field.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

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.

A Channel has the following attributes:

Property Type Description Example
id string The unique ID of the Channel. 5877a5ecb6b1bc76263e0a85
name string* The name of the Channel. BC One
organization string The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations. 55dcf8aa048ee2227d4aa1a4
members array A list of channel member objects that are a member of this channel. Each object contains a user ID and the online status (boolean). [{ChannelMember}]
createdAt string ISO8601 date and time when the Channel was created. 2016-01-07T14:03:43Z
updatedAt string ISO8601 date and time when the Channel was last modified. 2016-01-07T14:03:43Z

List All Channels
GET/channels

Return a list of all Channels.

Example URI

GET https://api2.chatshipper.com/v2/channels
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "5877a5ecb6b1bc76263e0a85",
    "name": "BC One",
    "organization": "55dcf8aa048ee2227d4aa1a4",
    "members": [
      {
        "user": "56467a06d9b082b0059151dc",
        "online": false
      }
    ],
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create a New Channel
POST/channels

You may create a Channel using this action.

Example URI

POST https://api2.chatshipper.com/v2/channels
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    }
  },
  "required": [
    "name"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /channels/5877a5ecb6b1bc76263e0a85
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false
    }
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Channel."
    },
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Channel

Retrieve a Channel
GET/channels/{channel_id}

Returns a specific Channel.

Example URI

GET https://api2.chatshipper.com/v2/channels/channel_id
URI Parameters
HideShow
channel_id
string (required) 

ID of the Channel.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false
    }
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Channel."
    },
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update a Channel
PATCH/channels/{channel_id}

Update a specific Channel.

Example URI

PATCH https://api2.chatshipper.com/v2/channels/channel_id
URI Parameters
HideShow
channel_id
string (required) 

ID of the Channel.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    }
  },
  "required": [
    "name"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "5877a5ecb6b1bc76263e0a85",
  "name": "BC One",
  "organization": "55dcf8aa048ee2227d4aa1a4",
  "members": [
    {
      "user": "56467a06d9b082b0059151dc",
      "online": false
    }
  ],
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Channel."
    },
    "name": {
      "type": "string",
      "description": "The name of the Channel."
    },
    "organization": {
      "type": "string",
      "description": "The ID of the organization that owns the Channel. Must be the organization that the current API user is an admin for (default) or one of its sub-organizations."
    },
    "members": {
      "type": "array",
      "description": "A list of channel member objects that are a member of this channel. Each object contains a `user` ID and the `online` status (boolean)."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Channel was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Delete a Channel
DELETE/channels/{channel_id}

Delete a Channel.

Example URI

DELETE https://api2.chatshipper.com/v2/channels/channel_id
URI Parameters
HideShow
channel_id
string (required) 

ID of the Channel.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Response  204

Retrieve all Channel members
GET/channels/{channel_id}/members

Returns all Users - as channel member objects - that are a member of a specific Channel.

Example URI

GET https://api2.chatshipper.com/v2/channels/channel_id/members
URI Parameters
HideShow
channel_id
string (required) 

ID of the Channel.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "user": "56467a06d9b082b0059151dc",
    "online": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Add agents to a channel
POST/channels/{channel_id}/members

You may add one or more agent members to a Channel using this action.

Example URI

POST https://api2.chatshipper.com/v2/channels/channel_id/members
URI Parameters
HideShow
channel_id
string (required) 

ID of the Channel.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "user": "56467a06d9b082b0059151dc",
  "online": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "user": {
      "type": "string",
      "description": "The ID of the User that may subscribe to the channel."
    },
    "online": {
      "type": "boolean",
      "description": "Flag signifying if the user is currently subscribed to the channel.",
      "default": false
    }
  },
  "required": [
    "user"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /channels/5877a5ecb6b1bc76263e0a85
Body
{
  "user": "56467a06d9b082b0059151dc",
  "online": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "user": {
      "type": "string",
      "description": "The ID of the User that may subscribe to the channel."
    },
    "online": {
      "type": "boolean",
      "description": "Flag signifying if the user is currently subscribed to the channel.",
      "default": false
    }
  },
  "required": [
    "user"
  ]
}

Remove an agent from a channel
DELETE/channels/{channel_id}/members/{user_id}

Remove a User from a Channel.

Example URI

DELETE https://api2.chatshipper.com/v2/channels/channel_id/members/user_id
URI Parameters
HideShow
channel_id
string (required) 

ID of the Channel.

user_id
string (required) 

ID of the User.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Workflows

Workflows store and execute rules, emit events, and maintain the state needed to route queued conversations to user notification channels. Workflows are executed using a powerful, lightweight rules engine.

Each workflow may be limited to a selected set of organizations and/or, more dynamically, a set of organization tags.

Whenever a conversation enters the state queued, all workflows of the owning organization are run. In addition, all workflows of any parent organizations are run that are not limited to exclude the conversations’s organization (by specifying applicable organizations and organization tags for the workflow).

A Workflow has the following attributes:

Property Type Description Example
id string The unique ID of the Workflow. 56467a06d9b082b0059151dc
organization string Organization ID, conversation owner. Defaults to the API key owner. 58bcbafb8547f04f68c14bdb
name string* Name of the Workflow. Automotive - Generic
enabled boolean Boolean to switch the workflow on or off. Defaults to true. true
rules array An array of rules that are matched to facts. [{WfRule}]
organizations array List of Organization IDs to limit the workflow to. [58bc9aecd906223dcec36495]
organizationTags array List of OrganizationGroup IDs to limit the workflow to. [56467a06d9b082b0059151dc]
createdAt string ISO8601 date and time when the Workflow was created. 2017-01-07T14:03:43Z
updatedAt string ISO8601 date and time when the Workflow was last modified. 2017-01-07T14:03:43Z

For further information on structuring workflows, please review the Provisioning Guide.

List All Workflows
GET/workflows

Return a list of all Workflows.

Example URI

GET https://api2.chatshipper.com/v2/workflows
Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "56467a06d9b082b0059151dc",
    "organization": "58bcbafb8547f04f68c14bdb",
    "name": "Automotive - Generic",
    "enabled": true,
    "rules": [
      {
        "id": "58bc9aecd906223dcec36493",
        "conditions": {
          "any": [
            {
              "fact": "conversation.category",
              "operator": "match",
              "value": "Used Car",
              "path": ".meta"
            }
          ],
          "all": [
            {
              "fact": "conversation.category",
              "operator": "match",
              "value": "Used Car",
              "path": ".meta"
            }
          ]
        },
        "event": {
          "type": "enqueue",
          "params": {
            "name": "Sales",
            "channel": "58bc9aecd906223dcec36493",
            "delay": 20
          }
        },
        "priority": 1
      }
    ],
    "organizations": [
      "58bc9aecd906223dcec36495",
      "58bc9aecd906223dcec36493"
    ],
    "organizationTags": [
      "56467a06d9b082b0059151dc"
    ],
    "createdAt": "2017-01-07T14:03:43Z",
    "updatedAt": "2017-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create a New Workflow
POST/workflows

You may create a Workflow using this action.

Example URI

POST https://api2.chatshipper.com/v2/workflows
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    }
  },
  "required": [
    "name"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /workflows/5877a5ecb6b1bc76263e0a85
Body
{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ],
  "createdAt": "2017-01-07T14:03:43Z",
  "updatedAt": "2017-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Workflow."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Workflow

Retrieve a Workflow
GET/workflows/{workflow_id}

Returns a specific Workflow.

Example URI

GET https://api2.chatshipper.com/v2/workflows/workflow_id
URI Parameters
HideShow
workflow_id
string (required) 

ID of the Workflow.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ],
  "createdAt": "2017-01-07T14:03:43Z",
  "updatedAt": "2017-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Workflow."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Update a Workflow
PATCH/workflows/{workflow_id}

Update a specific Workflow.

Example URI

PATCH https://api2.chatshipper.com/v2/workflows/workflow_id
URI Parameters
HideShow
workflow_id
string (required) 

ID of the Workflow.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    }
  },
  "required": [
    "name"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Automotive - Generic",
  "enabled": true,
  "rules": [
    {
      "id": "58bc9aecd906223dcec36493",
      "conditions": {
        "any": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ],
        "all": [
          {
            "fact": "conversation.category",
            "operator": "match",
            "value": "Used Car",
            "path": ".meta"
          }
        ]
      },
      "event": {
        "type": "enqueue",
        "params": {
          "name": "Sales",
          "channel": "58bc9aecd906223dcec36493",
          "delay": 20
        }
      },
      "priority": 1
    }
  ],
  "organizations": [
    "58bc9aecd906223dcec36495",
    "58bc9aecd906223dcec36493"
  ],
  "organizationTags": [
    "56467a06d9b082b0059151dc"
  ],
  "createdAt": "2017-01-07T14:03:43Z",
  "updatedAt": "2017-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Workflow."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Defaults to the API key owner."
    },
    "name": {
      "type": "string",
      "description": "Name of the Workflow."
    },
    "enabled": {
      "type": "boolean",
      "description": "Boolean to switch the workflow on or off.",
      "default": true
    },
    "rules": {
      "type": "array",
      "description": "An array of rules that are matched to facts."
    },
    "organizations": {
      "type": "array",
      "description": "List of Organization IDs to limit the workflow to."
    },
    "organizationTags": {
      "type": "array",
      "description": "List of OrganizationGroup IDs to limit the workflow to."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Workflow was last modified."
    }
  },
  "required": [
    "name"
  ]
}

Delete a Workflow
DELETE/workflows/{workflow_id}

Delete a Workflow.

Example URI

DELETE https://api2.chatshipper.com/v2/workflows/workflow_id
URI Parameters
HideShow
workflow_id
string (required) 

ID of the Workflow.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  204

Workflow Rules

Retrieve all Workflow Rules
GET/workflows/{workflow_id}/rules

Returns all rule objects of a specific Workflow.

Example URI

GET https://api2.chatshipper.com/v2/workflows/workflow_id/rules
URI Parameters
HideShow
workflow_id
string (required) 

ID of the Workflow.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "58bc9aecd906223dcec36493",
    "conditions": {
      "any": [
        {
          "fact": "conversation.category",
          "operator": "match",
          "value": "Used Car",
          "path": ".meta"
        }
      ],
      "all": [
        {
          "fact": "conversation.category",
          "operator": "match",
          "value": "Used Car",
          "path": ".meta"
        }
      ]
    },
    "event": {
      "type": "enqueue",
      "params": {
        "name": "Sales",
        "channel": "58bc9aecd906223dcec36493",
        "delay": 20
      }
    },
    "priority": 1
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Add a rule to a workflow
POST/workflows/{workflow_id}/rules

You may add a rule to a Workflow using this action.

Example URI

POST https://api2.chatshipper.com/v2/workflows/workflow_id/rules
URI Parameters
HideShow
workflow_id
string (required) 

ID of the Workflow.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /workflows/5877a5ecb6b1bc76263e0a85/rules/58bc9aecd906223dcec36493
Body
{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}

Retrieve a specific Workflow Rule
GET/workflows/{workflow_id}/rules/{rule_id}

Returns a specific rule object of a Workflow.

Example URI

GET https://api2.chatshipper.com/v2/workflows/workflow_id/rules/rule_id
URI Parameters
HideShow
workflow_id
string (required) 

ID of the Workflow.

rule_id
string (required) 

ID of the Worflow rule.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}

Update a Workflow Rule
PATCH/workflows/{workflow_id}/rules/{rule_id}

Update a specific Workflow rule.

Example URI

PATCH https://api2.chatshipper.com/v2/workflows/workflow_id/rules/rule_id
URI Parameters
HideShow
workflow_id
string (required) 

ID of the Workflow.

rule_id
string (required) 

ID of the Worflow rule.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "58bc9aecd906223dcec36493",
  "conditions": {
    "any": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ],
    "all": [
      {
        "fact": "conversation.category",
        "operator": "match",
        "value": "Used Car",
        "path": ".meta"
      }
    ]
  },
  "event": {
    "type": "enqueue",
    "params": {
      "name": "Sales",
      "channel": "58bc9aecd906223dcec36493",
      "delay": 20
    }
  },
  "priority": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Rule ID."
    },
    "conditions": {
      "type": "object",
      "properties": {
        "any": {
          "type": "array",
          "description": "List of conditions evaluates to true if any match."
        },
        "all": {
          "type": "array",
          "description": "List of conditions evaluates to true if all match."
        }
      },
      "description": "Rule conditions."
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Only `enqueue` is supported."
        },
        "params": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Event name."
            },
            "channel": {
              "type": "string",
              "description": "Channel ID of target channel."
            },
            "isLastRule": {
              "type": "boolean",
              "description": "Boolean indicating that no more rules will be processed if this rule matches.",
              "default": false
            },
            "delay": {
              "type": "number",
              "description": "Number of seconds to postpone processing (since the workflow was called)."
            }
          },
          "required": [
            "name",
            "channel"
          ],
          "description": "Event parameters."
        }
      },
      "required": [
        "type",
        "params"
      ],
      "description": "Rule event."
    },
    "priority": {
      "type": "number",
      "description": "Priority of the rule, from 1 (low) to 5 (high priority)."
    }
  },
  "required": [
    "id",
    "conditions",
    "event"
  ]
}

Remove a Rule from a Workflow
DELETE/workflows/{workflow_id}/rules/{rule_id}

Remove a rule from a Workflow.

Example URI

DELETE https://api2.chatshipper.com/v2/workflows/workflow_id/rules/rule_id
URI Parameters
HideShow
workflow_id
string (required) 

ID of the Workflow.

rule_id
string (required) 

ID of the Worflow rule.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Response  204

Messaging

Conversations

A conversation lets you track and describe communications with your users. To start a conversation you and your users can send messages; when the first message is received from a new Contact, a conversation is automatically created.

A conversation may have the following attributes:

Property Type Description Example
id string The unique ID of the Conversation. 56467a06d9b082b0059151dc
slug string Slug for the conversation for use in short URL path segments. Byxu3buKiW
url string Viewer URL. https://skynet.chat.report/c/Byxu3buKiW
organization string Organization ID, conversation owner. 58bcbafb8547f04f68c14bdb
name string Name for the conversation. Bonbowack Acerfuse
type enum Conversation initiator type One of bot, contact, viewer, agent, admin, system. Defaults to bot. bot
status enum Conversation status One of queued, active, closed. Defaults to queued. queued
category string Category name. Used Car
categoryIndex number Index of the category in the organization’s category list. 0
language string Conversation language. en
contact string Contact ID of the visitor. 58bc9aecd906223dcec36493
messages array An array of Message IDs for this conversation. [58bcbafb8547f04f68c14bdb]
meta MetaParams Free-form object of key-value pairs, representing context from the automation that created this conversation. {MetaParams}
participants array An array of conversation participants. [{Participant}]
channels array An array of Channel IDs that were notified for this conversation. [56467a06d9b082b0059151dc]
channelsOffline array An array of Channel IDs that were not notified due to unavailability of agents. [58bcbafb8547f04f68c14bdb]
touchpoints array An array of contact touchpoints. [{Touchpoint}]
forms array An array of incomplete or unsent forms. [{ConversationForm}]
results array An array of completed and sent forms. [{ConversationResult}]
createdBy string User ID of the user that created the conversation. 58bc9aecd906223dcec36495
createdAt string ISO8601 date and time when the Conversation was created. 2016-01-07T14:03:43Z
updatedAt string ISO8601 date and time when the Conversation was last modified. 2016-01-07T14:03:43Z

conversation.participants

Over the course of a conversation, users that have joined or left the conversation are tracked in the participants attribute. It has the following structure:

Property Type Description Example
user string* The UserID of the agent. 59abeb8c55f0992165e691fc
unreadCount number A counter of unseen messages. 0
active boolean Flag signifying if the conversation is currently active for the agent. Defaults to false. false
inbox boolean Flag signifying if the conversation is currently in the agent’s inbox. Defaults to false. false

conversation.touchpoints

A list of possible consumer touchpoints for this conversation. Activated touchpoints will have one or more services specified.

Property Type Description Example
name enum The code name for this touchpoint. One of web, email, sms, facebook, whatsapp. Defaults to web. web
services array* An array of Service IDs of services available for this touchpoint. [58bcbafb8547f04f68c14bdb]
selected boolean Flag signifying if this is the currently active touchpoint. Defaults to true. true

conversation.forms

Activated (unsent) forms that are amenable to completion and sending are available in the forms attribute.

Property Type Description Example
form string* The Form ID of the form. 59abeb8c55f0992165e691fc
name string* Name of the form. Brochure
type enum Form type. A static form always stays active, while a topic is picked by the agent. One of topic, static. Defaults to topic. topic
category string Category name. Used Car
categoryIndex number Index of the category in the organization’s category list. 0
values MetaParams Form key/values. {MetaParams}

conversation.results

Processed forms are tracked in the results attribute.

Property Type Description Example
message string* The Message ID of the results message. 5a23618654c8fe229c12f00c
form string* The Form ID of the form. 59abeb8c55f0992165e691fc
name string* Name of the form result. Brochure
category string Category name. Used Car
categoryIndex number Index of the category in the organization’s category list. 0

List All Conversations
GET/conversations{?sort,offset,limit,select,populate,organization,type,status,categoryIndex,category,slug,participants.user,forms.form,results.form,language,meta.value,createdAt,updatedAt}

Return a list of conversations.

For fetching conversations using a query for a meta variable, at least one of the following parameters is required: id, type, participants.user, status, createdAt, categoryIndex, category, organization, createdAt or updatedAt.

Example URI

GET https://api2.chatshipper.com/v2/conversations?sort=&offset=&limit=&select=&populate=&organization=&type=&status=&categoryIndex=&category=&slug=&participants.user=&forms.form=&results.form=&language=&meta.value=&createdAt=&updatedAt=
URI Parameters
HideShow
sort
string (optional) 

Sort order.

offset
number (optional) 

Pagination start. Default: 0. Maximum 1000.

limit
number (optional) 

Number of results. Default: 200. Maximum 1000.

select
string (optional) 

Field selection.

populate
string (optional) 

Field population.

organization
string (optional) 

see object specification earlier.

type
string (optional) 

see object specification earlier.

status
string (optional) 

see object specification earlier.

categoryIndex
string (optional) 

see object specification earlier.

category
string (optional) 

see object specification earlier.

slug
string (optional) 

see object specification earlier.

participants.user
string (optional) 

see object specification earlier.

forms.form
string (optional) 

see object specification earlier for additional forms properties.

results.form
string (optional) 

see object specification earlier for additional results properties.

language
string (optional) 

see object specification earlier.

meta.value
string (optional) 

see object specification earlier.

createdAt
string (optional) 

see object specification earlier.

updatedAt
string (optional) 

see object specification earlier.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "56467a06d9b082b0059151dc",
    "slug": "Byxu3buKiW",
    "url": "https://skynet.chat.report/c/Byxu3buKiW",
    "organization": "58bcbafb8547f04f68c14bdb",
    "name": "Bonbowack Acerfuse",
    "type": "bot",
    "status": "queued",
    "category": "Used Car",
    "categoryIndex": 0,
    "language": "en",
    "contact": "58bc9aecd906223dcec36493",
    "messages": [
      "58bcbafb8547f04f68c14bdb"
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "participants": [
      {
        "user": "59abeb8c55f0992165e691fc",
        "unreadCount": 0,
        "active": true,
        "inbox": true
      }
    ],
    "channels": [
      "56467a06d9b082b0059151dc"
    ],
    "channelsOffline": [
      "58bcbafb8547f04f68c14bdb"
    ],
    "touchpoints": [
      {
        "name": "web",
        "services": [
          "58bcbafb8547f04f68c14bdb"
        ],
        "selected": true
      }
    ],
    "forms": [
      {
        "form": "59abeb8c55f0992165e691fc",
        "name": "Brochure",
        "type": "topic",
        "category": "Used Car",
        "categoryIndex": 0,
        "values": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "results": [
      {
        "message": "5a23618654c8fe229c12f00c",
        "form": "59abeb8c55f0992165e691fc",
        "name": "Brochure",
        "category": "Used Car",
        "categoryIndex": 0
      }
    ],
    "createdBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create a new Conversation
POST/conversations

Create a conversation using this action.

Example URI

POST https://api2.chatshipper.com/v2/conversations
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    }
  }
}
Response  202
HideShow
Headers
Content-Type: application/json
Location: /conversations/56b9d54c59f2698e0ae9623c
Body
{
  "id": "56467a06d9b082b0059151dc",
  "slug": "Byxu3buKiW",
  "url": "https://skynet.chat.report/c/Byxu3buKiW",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "participants": [
    {
      "user": "59abeb8c55f0992165e691fc",
      "unreadCount": 0,
      "active": true,
      "inbox": true
    }
  ],
  "channels": [
    "56467a06d9b082b0059151dc"
  ],
  "channelsOffline": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "touchpoints": [
    {
      "name": "web",
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    }
  ],
  "forms": [
    {
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "type": "topic",
      "category": "Used Car",
      "categoryIndex": 0,
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "message": "5a23618654c8fe229c12f00c",
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "category": "Used Car",
      "categoryIndex": 0
    }
  ],
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Conversation."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the conversation for use in short URL path segments."
    },
    "url": {
      "type": "string",
      "description": "Viewer URL."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    },
    "participants": {
      "type": "array",
      "description": "An array of conversation participants."
    },
    "channels": {
      "type": "array",
      "description": "An array of Channel IDs that were notified for this conversation."
    },
    "channelsOffline": {
      "type": "array",
      "description": "An array of Channel IDs that were not notified due to unavailability of agents."
    },
    "touchpoints": {
      "type": "array",
      "description": "An array of contact touchpoints."
    },
    "forms": {
      "type": "array",
      "description": "An array of incomplete or unsent forms."
    },
    "results": {
      "type": "array",
      "description": "An array of completed and sent forms."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the conversation."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was last modified."
    }
  }
}

Conversation

Retrieve a Conversation
GET/conversations/{conversation_id}

Returns a specific Conversation.

Example URI

GET https://api2.chatshipper.com/v2/conversations/conversation_id
URI Parameters
HideShow
conversation_id
string (required) 

ID of the Conversation.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "56467a06d9b082b0059151dc",
  "slug": "Byxu3buKiW",
  "url": "https://skynet.chat.report/c/Byxu3buKiW",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "participants": [
    {
      "user": "59abeb8c55f0992165e691fc",
      "unreadCount": 0,
      "active": true,
      "inbox": true
    }
  ],
  "channels": [
    "56467a06d9b082b0059151dc"
  ],
  "channelsOffline": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "touchpoints": [
    {
      "name": "web",
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    }
  ],
  "forms": [
    {
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "type": "topic",
      "category": "Used Car",
      "categoryIndex": 0,
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "message": "5a23618654c8fe229c12f00c",
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "category": "Used Car",
      "categoryIndex": 0
    }
  ],
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Conversation."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the conversation for use in short URL path segments."
    },
    "url": {
      "type": "string",
      "description": "Viewer URL."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    },
    "participants": {
      "type": "array",
      "description": "An array of conversation participants."
    },
    "channels": {
      "type": "array",
      "description": "An array of Channel IDs that were notified for this conversation."
    },
    "channelsOffline": {
      "type": "array",
      "description": "An array of Channel IDs that were not notified due to unavailability of agents."
    },
    "touchpoints": {
      "type": "array",
      "description": "An array of contact touchpoints."
    },
    "forms": {
      "type": "array",
      "description": "An array of incomplete or unsent forms."
    },
    "results": {
      "type": "array",
      "description": "An array of completed and sent forms."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the conversation."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was last modified."
    }
  }
}

Update a Conversation
PATCH/conversations/{conversation_id}

Update a specific Conversation. To be used only under special circumstances (eg corruption repairs); during regular operations, conversation state should be updated by creating messages containing the /set command.

Example URI

PATCH https://api2.chatshipper.com/v2/conversations/conversation_id
URI Parameters
HideShow
conversation_id
string (required) 

ID of the Conversation.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "56467a06d9b082b0059151dc",
  "slug": "Byxu3buKiW",
  "url": "https://skynet.chat.report/c/Byxu3buKiW",
  "organization": "58bcbafb8547f04f68c14bdb",
  "name": "Bonbowack Acerfuse",
  "type": "bot",
  "status": "queued",
  "category": "Used Car",
  "categoryIndex": 0,
  "language": "en",
  "contact": "58bc9aecd906223dcec36493",
  "messages": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "participants": [
    {
      "user": "59abeb8c55f0992165e691fc",
      "unreadCount": 0,
      "active": true,
      "inbox": true
    }
  ],
  "channels": [
    "56467a06d9b082b0059151dc"
  ],
  "channelsOffline": [
    "58bcbafb8547f04f68c14bdb"
  ],
  "touchpoints": [
    {
      "name": "web",
      "services": [
        "58bcbafb8547f04f68c14bdb"
      ],
      "selected": true
    }
  ],
  "forms": [
    {
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "type": "topic",
      "category": "Used Car",
      "categoryIndex": 0,
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "message": "5a23618654c8fe229c12f00c",
      "form": "59abeb8c55f0992165e691fc",
      "name": "Brochure",
      "category": "Used Car",
      "categoryIndex": 0
    }
  ],
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Conversation."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the conversation for use in short URL path segments."
    },
    "url": {
      "type": "string",
      "description": "Viewer URL."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner."
    },
    "name": {
      "type": "string",
      "description": "Name for the conversation."
    },
    "type": {
      "type": "string",
      "enum": [
        "bot",
        "contact",
        "viewer",
        "agent",
        "admin",
        "system"
      ],
      "default": "bot",
      "description": "Conversation initiator type"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "active",
        "closed"
      ],
      "default": "queued",
      "description": "Conversation status"
    },
    "category": {
      "type": "string",
      "description": "Category name."
    },
    "categoryIndex": {
      "type": "number",
      "description": "Index of the category in the organization's category list."
    },
    "language": {
      "type": "string",
      "description": "Conversation language."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the visitor."
    },
    "messages": {
      "type": "array",
      "description": "An array of Message IDs for this conversation."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the automation that created this conversation."
    },
    "participants": {
      "type": "array",
      "description": "An array of conversation participants."
    },
    "channels": {
      "type": "array",
      "description": "An array of Channel IDs that were notified for this conversation."
    },
    "channelsOffline": {
      "type": "array",
      "description": "An array of Channel IDs that were not notified due to unavailability of agents."
    },
    "touchpoints": {
      "type": "array",
      "description": "An array of contact touchpoints."
    },
    "forms": {
      "type": "array",
      "description": "An array of incomplete or unsent forms."
    },
    "results": {
      "type": "array",
      "description": "An array of completed and sent forms."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the conversation."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Conversation was last modified."
    }
  }
}

Messages

A Message represents an event in the Conversation timeline. Commonly this is a text message from a participant, but a Message may also represent commands and fields for example. It has the following attributes:

Property Type Description Example
id string The unique ID of the Message. 56467a06d9b082b0059151dc
organization string Organization ID, conversation owner. Same as the organization owning the conversation. 58bcbafb8547f04f68c14bdb
contact string Contact ID of the consumer that created or received the message, if applicable. Same as the conversation contact. 58bc9aecd906223dcec36493
slug string Slug for the message for use in viewer URL path segments. SJXlgkVbaZ
url string The (possibly white labeled) URL of the message in the viewer. https://view.chatshipper.com/SJXlgkVbaZ
cindex number Index count of the message in the conversation. 5
conversation string* Conversation ID. 58bc9aecd906223dcec36493
text string* Message text or HTML, or the URL of a non-text contentType. Hello 😉
type enum Message type One of chat, card, postback, mention, tag, search, command, form, field, results, report, status. Defaults to chat. chat
role enum Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages. One of contact, agent, bot, system. Defaults to bot. contact
isBackchannel boolean Wether the message is part of the back channel stream aside the main conversation thread. Defaults to true. true
contentType enum Content type. For binary formats, the text property should be to the media URL. Only applies to chat, mention, postback and card messages. One of text/plain, text/html, text/url, image/png, image/gif, image/jpg, image/jpeg, application/pdf. Defaults to text/plain. text/plain
user string User ID of the agent that is represented by the message, if applicable (default: user making the API request). 58bc9aecd906223dcec36495
service string Service ID of external service that this message gets mirrored with (either as a sender or as a receiver). 58bc9aecd906223dcec36493
touchpoint enum Touchpoint/platform source or target at service for this message. One of web, email, sms, facebook, whatsapp. Defaults to web. web
delay number Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown. 5000
items array An array of list items to present to participants, each item containing one or more actions. [{ListItem}]
actions array An array of Action Buttons to present to participants, to serve as a link, reply or postback actions. [{ActionButton}]
results array An array of form results objects that were collected from messages with type results. [{MessageResults}]
meta MetaParams Free-form object of key-value pairs, representing context from the service adapter that created this message. {MetaParams}
serviceType enum Target type of service provider. One of smartsupp, intercom, smooch, twilio, mailgun, messenger, whatsapp, api, webhook. Defaults to smartsupp. smartsupp
createdBy string User ID of the user that created the message. 58bc9aecd906223dcec36495
createdAt string ISO8601 date and time when the Message was created. 2016-01-07T14:03:43Z
updatedAt string ISO8601 date and time when the Message was last modified. 2016-01-07T14:03:43Z

Message Items

Message Items can be sent by including them in the message payload. Only messages of type chat, card or postback support message items.

Property Type Description Example
title string* The title of the item. Tacos
description string The text description, or subtitle. Beef and cheese, hmmm…
actions array Array of message actions. At least 1 is required, a maximum of 3 are allowed. link, webview, and postback actions are supported. See the action schema for details. [{ActionButton}]
size enum The size of the image to be shown in the carousel/list item (Only top item of Facebook Messenger carousel) One of compact, large. Defaults to compact. compact
mediaUrl string The image URL to be shown in the carousel/list item. http://example.org/image.png
mediaType string If a mediaUrl was specified, the media type is defined here, for example ‘image/jpeg’. If mediaType is not specified, the media type will be resolved with the mediaUrl. image/png

Action Buttons

Actions buttons can be sent by including them in the message payload. There are 5 types of supported actions : link, reply, postback, webview and locationRequest. Type must be specified by providing a type argument in the action object.

Link

A link action will open the provided URI when tapped. Links outside the ChatShipper domain will open in a new browser tab.

Property Type Description Example
type string* Button type link. link
text string* The button text. Tacos
uri string The action URI. This is the link that will be used in the clients when clicking the button. http://example.org
meta MetaParams Flat object containing any custom properties associated with the action. {MetaParams}

Postback

A postback action will post the action payload to the server.

Property Type Description Example
type string* Button type postback. postback
text string* The button text. Tacos
payload string* A string payload to help you identify the action context. If the payload represents a JSON message object or array of message objects, these will be processed as conversation messages when the button is clicked. You can also use metadata for more complex needs. tacos
meta MetaParams Flat object containing any custom properties associated with the action. {MetaParams}

Reply

A reply action will echo the user’s choice as a message. You may optionally specify an iconUrl which will render as an icon for each option.

Property Type Description Example
type string* Button type reply. reply
text string* The button text. Tacos
payload string* A string payload to help you identify the action context. Used when posting the reply. If the payload represents a JSON message object or array of message objects, these will be processed as conversation messages when the button is clicked. You can also use metadata for more complex needs. tacos
iconUrl string An icon to render next to the reply option (Facebook Messenger and Web Messenger only). http://example.com/images/tag.png
meta MetaParams Flat object containing any custom properties associated with the action. {MetaParams}
  • reply type actions can be sent either alone or with location request actions. If an action of a different type is included in the message, it will be rejected.

  • Icons are currently only supported on Facebook Messenger and Web Messenger.

Webview

When a webview actions is clicked/tapped, the provided URI will be loaded in a webview. Channels that do not support webviews will open the fallback URI instead.

Property Type Description Example
type string* Button type webview. webview
text string* The button text. Open Form
uri string* The webview URI. This is the URI that will open in the webview when clicking the button. http://example.org
fallback string* The webview fallback URI. This is the link that will be opened in channels that do not support webviews. http://example.org
size enum Controls the webview height. One of compact, tall, full. Defaults to compact. compact
meta MetaParams Flat object containing any custom properties associated with the action. {MetaParams}

Location Request

A location request action will prompt the user to share their location. Unsupported clients will receive text fallback: “App has requested a location”.

Property Type Description Example
type string* Button type locationRequest. locationRequest
text string* The button text. Set Location
meta MetaParams Flat object containing any custom properties associated with the action. {MetaParams}

locationRequest type actions can be sent either alone or with reply actions. If an action of a different type is included in the message, it will be rejected.

List All Messages
GET/messages{?sort,offset,limit,select,populate,type,conversation,organization,type,role,isBackchannel,contentType,touchpoint,delay,user,text,meta,createdBy}

Return a list of all Messages. At least one of the following parameters should be supplied: id, organization, conversation, type, role or createdAt.

Example URI

GET https://api2.chatshipper.com/v2/messages?sort=&offset=&limit=&select=&populate=&type=&conversation=&organization=&type=&role=&isBackchannel=&contentType=&touchpoint=&delay=&user=&text=&meta=&createdBy=
URI Parameters
HideShow
sort
string (optional) 

Sort order.

offset
number (optional) 

Pagination start. Default: 0. Maximum 1000.

limit
number (optional) 

Number of results. Default: 200. Maximum 1000.

select
string (optional) 

Field selection.

populate
string (optional) 

Field population.

conversation
string (optional) 

ID of the Conversation.

organization
string (optional) 

ID of the Organization.

type
string (optional) 

Message type.

role
string (optional) 

Message role.

isBackchannel
boolean (optional) 

Backchannel flag.

contentType
string (optional) 

MIME type of the message content.

touchpoint
string (optional) 

Consumer endpoint type.

delay
integer (optional) 

Number of milliseconds to postpone message processing.

user
string (optional) 

ID of the user.

text
string (optional) 

Message text.

meta
string (optional) 

Meta variable.

createdBy
string (optional) 

ID of the creating user.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "56467a06d9b082b0059151dc",
    "organization": "58bcbafb8547f04f68c14bdb",
    "contact": "58bc9aecd906223dcec36493",
    "slug": "SJXlgkVbaZ",
    "url": "https://view.chatshipper.com/SJXlgkVbaZ",
    "cindex": 5,
    "conversation": "58bc9aecd906223dcec36493",
    "text": "Hello ;-)",
    "type": "chat",
    "role": "contact",
    "isBackchannel": false,
    "contentType": "text/plain",
    "user": "58bc9aecd906223dcec36495",
    "service": "58bc9aecd906223dcec36493",
    "touchpoint": "web",
    "delay": 5000,
    "items": [
      {
        "title": "Tacos",
        "description": "Beef and cheese, hmmm...",
        "actions": [
          {
            "type": "link",
            "text": "Tacos",
            "iconUrl": "http://example.com/images/tag.png",
            "payload": "tacos",
            "uri": "http://example.org",
            "meta": {
              "someKey": "Some value",
              "anotherKey": "Some other value"
            }
          }
        ],
        "size": "compact",
        "mediaUrl": "http://example.org/image.png",
        "mediaType": "image/png"
      }
    ],
    "actions": [
      {
        "type": "link",
        "text": "Tacos",
        "iconUrl": "http://example.com/images/tag.png",
        "payload": "tacos",
        "uri": "http://example.org",
        "meta": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "results": [
      {
        "form": "590d3af9e025187959e5e11c",
        "formName": "Identifiers",
        "type": "static",
        "values": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "serviceType": "smartsupp",
    "createdBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List All Conversation Messages
GET/conversation/{conversation_id}/messages{?sort,offset,limit,select,populate,type,type,role,isBackchannel,contentType,touchpoint,delay,user,text,meta,createdBy}

Return a list of all Messages in a Conversation.

Example URI

GET https://api2.chatshipper.com/v2/conversation/conversation_id/messages?sort=&offset=&limit=&select=&populate=&type=&type=&role=&isBackchannel=&contentType=&touchpoint=&delay=&user=&text=&meta=&createdBy=
URI Parameters
HideShow
sort
string (optional) 

Sort order.

offset
number (optional) 

Pagination start. Default: 0. Maximum 1000.

limit
number (optional) 

Number of results. Default: 200. Maximum 1000.

select
string (optional) 

Field selection.

populate
string (optional) 

Field population.

conversation_id
string (optional) 

ID of the Conversation.

type
string (optional) 

Message type.

role
string (optional) 

Message role.

isBackchannel
boolean (optional) 

Backchannel flag.

contentType
string (optional) 

MIME type of the message content.

touchpoint
string (optional) 

Consumer endpoint type.

delay
integer (optional) 

Number of milliseconds to postpone message processing.

user
string (optional) 

ID of the user.

text
string (optional) 

Message text.

meta
string (optional) 

Meta variable.

createdBy
string (optional) 

ID of the creating user.

Request
HideShow
Headers
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "56467a06d9b082b0059151dc",
    "organization": "58bcbafb8547f04f68c14bdb",
    "contact": "58bc9aecd906223dcec36493",
    "slug": "SJXlgkVbaZ",
    "url": "https://view.chatshipper.com/SJXlgkVbaZ",
    "cindex": 5,
    "conversation": "58bc9aecd906223dcec36493",
    "text": "Hello ;-)",
    "type": "chat",
    "role": "contact",
    "isBackchannel": false,
    "contentType": "text/plain",
    "user": "58bc9aecd906223dcec36495",
    "service": "58bc9aecd906223dcec36493",
    "touchpoint": "web",
    "delay": 5000,
    "items": [
      {
        "title": "Tacos",
        "description": "Beef and cheese, hmmm...",
        "actions": [
          {
            "type": "link",
            "text": "Tacos",
            "iconUrl": "http://example.com/images/tag.png",
            "payload": "tacos",
            "uri": "http://example.org",
            "meta": {
              "someKey": "Some value",
              "anotherKey": "Some other value"
            }
          }
        ],
        "size": "compact",
        "mediaUrl": "http://example.org/image.png",
        "mediaType": "image/png"
      }
    ],
    "actions": [
      {
        "type": "link",
        "text": "Tacos",
        "iconUrl": "http://example.com/images/tag.png",
        "payload": "tacos",
        "uri": "http://example.org",
        "meta": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "results": [
      {
        "form": "590d3af9e025187959e5e11c",
        "formName": "Identifiers",
        "type": "static",
        "values": {
          "someKey": "Some value",
          "anotherKey": "Some other value"
        }
      }
    ],
    "meta": {
      "someKey": "Some value",
      "anotherKey": "Some other value"
    },
    "serviceType": "smartsupp",
    "createdBy": "58bc9aecd906223dcec36495",
    "createdAt": "2016-01-07T14:03:43Z",
    "updatedAt": "2016-01-07T14:03:43Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create a new Message
POST/messages

You may create a new message using this action.

Example URI

POST https://api2.chatshipper.com/v2/messages
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /messages/56467a06d9b082b0059151dc
Body
{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "contact": "58bc9aecd906223dcec36493",
  "slug": "SJXlgkVbaZ",
  "url": "https://view.chatshipper.com/SJXlgkVbaZ",
  "cindex": 5,
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "serviceType": "smartsupp",
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Message."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Same as the organization owning the conversation."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the consumer that created or received the message, if applicable. Same as the conversation contact."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the message for use in viewer URL path segments."
    },
    "url": {
      "type": "string",
      "description": "The (possibly white labeled) URL of the message in the viewer."
    },
    "cindex": {
      "type": "number",
      "description": "Index count of the message in the conversation."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    },
    "serviceType": {
      "type": "string",
      "enum": [
        "smartsupp",
        "intercom",
        "smooch",
        "twilio",
        "mailgun",
        "messenger",
        "whatsapp",
        "api",
        "webhook"
      ],
      "default": "smartsupp",
      "description": "Target type of service provider."
    },
    "createdBy": {
      "type": "string",
      "description": "User ID of the user that created the message."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO8601 date and time when the Message was last modified."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}

Create a new Message
POST/conversation/{conversation_id}/messages

You may create a new message using this action.

Example URI

POST https://api2.chatshipper.com/v2/conversation/conversation_id/messages
URI Parameters
HideShow
conversation_id
string (required) 

ID of the Conversation.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Body
{
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties": {
        "someKey": {
          "type": "string",
          "description": "An example of a free-form key/value pair."
        },
        "anotherKey": {
          "type": "string",
          "description": "Another example of a free-form key/value pair."
        }
      },
      "description": "Free-form object of key-value pairs, representing context from the service adapter that created this message."
    }
  },
  "required": [
    "conversation",
    "text"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: /messages/56467a06d9b082b0059151dc
Body
{
  "id": "56467a06d9b082b0059151dc",
  "organization": "58bcbafb8547f04f68c14bdb",
  "contact": "58bc9aecd906223dcec36493",
  "slug": "SJXlgkVbaZ",
  "url": "https://view.chatshipper.com/SJXlgkVbaZ",
  "cindex": 5,
  "conversation": "58bc9aecd906223dcec36493",
  "text": "Hello ;-)",
  "type": "chat",
  "role": "contact",
  "isBackchannel": false,
  "contentType": "text/plain",
  "user": "58bc9aecd906223dcec36495",
  "service": "58bc9aecd906223dcec36493",
  "touchpoint": "web",
  "delay": 5000,
  "items": [
    {
      "title": "Tacos",
      "description": "Beef and cheese, hmmm...",
      "actions": [
        {
          "type": "link",
          "text": "Tacos",
          "iconUrl": "http://example.com/images/tag.png",
          "payload": "tacos",
          "uri": "http://example.org",
          "meta": {
            "someKey": "Some value",
            "anotherKey": "Some other value"
          }
        }
      ],
      "size": "compact",
      "mediaUrl": "http://example.org/image.png",
      "mediaType": "image/png"
    }
  ],
  "actions": [
    {
      "type": "link",
      "text": "Tacos",
      "iconUrl": "http://example.com/images/tag.png",
      "payload": "tacos",
      "uri": "http://example.org",
      "meta": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "results": [
    {
      "form": "590d3af9e025187959e5e11c",
      "formName": "Identifiers",
      "type": "static",
      "values": {
        "someKey": "Some value",
        "anotherKey": "Some other value"
      }
    }
  ],
  "meta": {
    "someKey": "Some value",
    "anotherKey": "Some other value"
  },
  "serviceType": "smartsupp",
  "createdBy": "58bc9aecd906223dcec36495",
  "createdAt": "2016-01-07T14:03:43Z",
  "updatedAt": "2016-01-07T14:03:43Z"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique ID of the Message."
    },
    "organization": {
      "type": "string",
      "description": "Organization ID, conversation owner. Same as the organization owning the conversation."
    },
    "contact": {
      "type": "string",
      "description": "Contact ID of the consumer that created or received the message, if applicable. Same as the conversation contact."
    },
    "slug": {
      "type": "string",
      "description": "Slug for the message for use in viewer URL path segments."
    },
    "url": {
      "type": "string",
      "description": "The (possibly white labeled) URL of the message in the viewer."
    },
    "cindex": {
      "type": "number",
      "description": "Index count of the message in the conversation."
    },
    "conversation": {
      "type": "string",
      "description": "Conversation ID."
    },
    "text": {
      "type": "string",
      "description": "Message text or HTML, or the URL of a non-text contentType."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "card",
        "postback",
        "mention",
        "tag",
        "search",
        "command",
        "form",
        "field",
        "results",
        "report",
        "status"
      ],
      "default": "chat",
      "description": "Message type"
    },
    "role": {
      "type": "string",
      "enum": [
        "contact",
        "agent",
        "bot",
        "system"
      ],
      "default": "bot",
      "description": "Role of the message sender in the agent console. Only applies to chat, mention, postback and card messages."
    },
    "isBackchannel": {
      "type": "boolean",
      "description": "Wether the message is part of the `back channel` stream aside the main conversation thread.",
      "default": true
    },
    "contentType": {
      "type": "string",
      "enum": [
        "text/plain",
        "text/html",
        "text/url",
        "image/png",
        "image/gif",
        "image/jpg",
        "image/jpeg",
        "application/pdf"
      ],
      "default": "text/plain",
      "description": "Content type. For binary formats, the `text` property should be to the media URL. Only applies to chat, mention, postback and card messages."
    },
    "user": {
      "type": "string",
      "description": "User ID of the agent that is represented by the message, if applicable (default: user making the API request)."
    },
    "service": {
      "type": "string",
      "description": "Service ID of external service that this message gets mirrored with (either as a sender or as a receiver)."
    },
    "touchpoint": {
      "type": "string",
      "enum": [
        "web",
        "email",
        "sms",
        "facebook",
        "whatsapp"
      ],
      "default": "web",
      "description": "Touchpoint/platform source or target at service for this message."
    },
    "delay": {
      "type": "number",
      "description": "Delay in milliseconds to postpone message processing. For chat message with delays of one second or more, a typing indicator is shown."
    },
    "items": {
      "type": "array",
      "description": "An array of list items to present to participants, each item containing one or more actions."
    },
    "actions": {
      "type": "array",
      "description": "An array of Action Buttons to present to participants, to serve as a link, reply or postback actions."
    },
    "results": {
      "type": "array",
      "description": "An array of form results objects that were collected from messages with type `results`."
    },
    "meta": {
      "type": "object",
      "properties":