The ChatShipper Developer Hub

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

Get Started

1. API Basics

Allowed Methods

The ChatShipper API uses standard GET, POST, PATCH, and DELETE methods to modify endpoints.

PATCH behavior

Partial updates are implemented using PATCH, we do not support PUT for this.

When updating a resource object, a PATCH request will

  • merge with the top-level resource object;
  • replace any nested objects and arrays in your request body, not merge it.

As an example, given the record:

{
    "id": "591a3932dd2ec870ce85bd2f",
    "organization": "590bcf50458b716046347f36",
    "name": "Acme SmartSupp",
    "type": "smartsupp",
    "params": {
        "jid": "uid3710@s1.smartsupp.com",
        "password": "z3kR3t",
        "host": "s1.smartsupp.com",
        "port": 5223
    }
}

... the following PATCH request:

Request: PATCH /v2/services/591a3932dd2ec870ce85bd2f

{
    "name": "Acme Web Widget",
    "params": {
        "jid": "uid8965@s1.smartsupp.com",
        "password": "t0pN0tCH",
        "host": "s1.smartsupp.com"
    }
}

... will result in the following updated resource:

Response: 200 OK

{
    "id": "591a3932dd2ec870ce85bd2f",
    "organization": "590bcf50458b716046347f36",
    "name": "Acme Web Widget",
    "type": "smartsupp",
    "params": {
        "jid": "uid8965@s1.smartsupp.com",
        "password": "z3kR3t",
        "host": "s1.smartsupp.com",
        "port": 5222
    }
}

As you can see, the params nested object is replaced (with port set to the default 5222), the name was updated and the top-level type and organization were merged in from the original.

Filters, paginations and expansions

The API supports features for filtering and population of records. For example,
to retrieve a Conversation with all Messages fully expanded, just add ?populate=messages
to your GET request.

For a full overview of pagination, filtering and population capabilities, see 3.Fetching Resources.

Datetime Handling

All datetime objects in ChatShipper use ISO 8601 formatting. For datetime objects without a specified offset, UTC (Coordinated Universal Time) is assumed.

Rate Limiting

ChatShipper's API limits each IP address and each API key to 20 requests per second. Exceeding this limit will result in a 429 - Too Many Requests error. If you require a higher limit, please contact support.

In addition to this basic request limit (applied per API key to all requests), two specialized rate limits are in place when creating messages (POST /v2/messages), as a bot user. These message creation limits are designed to limit the impact of bots getting stuck in a perpetual loop, either by itself or when interacting with other bots. The following limits apply per bot, per conversation:

  • Bots can create a maximum of 8 identical messages in a single conversation within a 3-minute timespan.
  • Bots can create a maximum of 20 consecutive messages in a single conversation per hour, after which bot messages within that hour are blocked until either an agent or a consumer replies in the conversation (thereby resetting the rate counter to 0).

For example, the following (pseudocode) examples would hit the identical or consecutive ratelimit on their last request:

for (0..9)
    POST /messages { text: "I've said this before..." }

for (0..21)
    POST /messages { text: `/set someVar ${Math.random()}` }

In both cases, ChatShipper will detect the perpetual loop and then prevent the bot from further flooding the conversation (within the rate-limited timespan). When designing, testing and monitoring bot conversation flows, you should detect rate limit errors and adjust the conversation design to stay within these limits; for example by combining multiple commands (/set, /assign, etc) into a single message.

Errors

ChatShipper uses standard HTTP status codes to communicate errors. The response body is JSON-encoded, and may include a "message" key with further information about the failure.

Common codes used by our API include:

HTTP Status Code Status
200 - OK API call succesful.
201 - Created The resource was created.
204 - Success No Content The request succeeded and there is no response data. Often used for DELETE endpoints.
400 - Bad Request The request failed, likely due to invalid or missing parameters. Check for a "message" value in the response with further details.
401 - Unauthorized No authentication was provided in the request.
403 - Forbidden The API key did not have permission to complete this action.
404 - Not Found The resource does not exist.
422 - Unprocessable Entity The request was well-formed but was unable to be followed due to semantic errors.
429 - Too Many Request The API Key was rate-limited due to too many requests. See above for rate limit information.
500 - Server Error ChatShipper's API encountered an unexpected error. Please email support for help.
502, 503 - Service Error ChatShipper's API encountered an intermittent error - please try again.

Backward compatibility and API updates

While we won’t introduce any breaking changes, we plan on adding new features and new endpoints over time. This is a list of changes we consider to be backwards compatible:

  • Adding new fields or links to the responses
  • Adding new resources or endpoints
  • Adding new (optional) request parameters
  • Changing default page length for paginated resources

Please consider this when programming against the API and try to make sure these non-breaking changes don’t break your code. We recommend using our Node.js SDK for optimal, worry-free API usage.

If we introduce a breaking change, we will create new endpoints with a new version prefix in the URI.


1. API Basics


Suggested Edits are limited on API Reference Pages

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